Kimi K3：用便携C99在8.24GB内存运行2.78T推理
给本地开发者的Kimi K3 C99推理引擎，用磁盘流式读取让2.78T模型在8.24GB内存运行。
GitHub FareedKhan-dev/kimi-k3-in-c 更新 2026-11-05 分支 main 星标 10.3K 分叉 1.6K
C99 本地推理 Kimi K3 CPU与低内存环境

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你要在无GPU、无BLAS的C99环境运行Kimi K3
    README开头明确写着“Portable C99: no BLAS, no framework, no GPU.”
  • 你的机器只有8 GB RAM，但能接受26.5 s/token的速度
    README的内存阶梯列出ordinary laptop为8 GB、26.5 s/token。
  • 你需要检查推理引擎、KV cache和KDA state是否与参考实现一致
    Quick start中的make test输出GATE 1、GATE 2、GATE 3，并要求生成token精确匹配。

不适合，如果你

  • 你需要低延迟生成，而设备只有8 GB RAM和普通磁盘
    README示例在8 GB配置下为8 tokens in 261.5 s，平均32.69 s/token。
  • 你的环境无法容纳1.56 TB checkpoint或承担持续磁盘读取
    README列出checkpoint on disk为1.56 TB，并说明8 GB机器每一步都从磁盘读取模型。
  • 你必须使用int4量化trunk来降低内存并保持已验证的输出质量
    Why the trunk is not quantised章节说明int4采样最高有65%相对误差，且没有运行下游logit或token比较。

前置条件

  • 构建需要编译器和OpenMP；README的make -j说明为“Seven C files, a compiler and OpenMP”。
  • 完整模型运行需要1.56 TB checkpoint；README测得峰值RSS为8.24 GB的示例使用该checkpoint。
  • 运行无权重测试不需要checkpoint、网络或Python；Quick start明确写着“No checkpoint, no network, no Python”。
  • tools/sim_cache.py需要Python 3.9+和numpy，并读取tests/fixtures/expert_trace.bin。

第一步命令（README 原文）

git clone https://github.com/FareedKhan-dev/kimi-k3-in-c.git

要注意

  • 不要把cache报告中的raw hits当作驻留命中率，应查看TRUE resident hit rate。
    Reading the run report章节说明raw hits包含prefetcher刚从磁盘读入的expert，而TRUE resident hit rate才表示RAM服务。
  • 不要用前置memory plan替代实际内存值，应记录PEAK RSS。
    README明确写着“PEAK RSS for the whole run: 94.74 GB <- quote this, not the plan”。
  • 批量命令生成的是raw continuation，不是带多轮历史的聊天回答。
    README说明该batch command deliberately asks for a raw continuation，并要求聊天使用XTML REPL。

材料未说明

  • 省略内容未给出Requirements章节中的具体操作系统、编译器版本和OpenMP版本要求。
  • 省略内容未给出Step 4 fetch the checkpoint的下载命令、来源和完整磁盘空间要求。
  • 材料没有说明Windows、macOS和NEON端口分别支持哪些版本或硬件型号。
  • 材料没有给出完整checkpoint运行的总耗时、吞吐范围或不同磁盘型号的系统化基准。
  • int4研究只测了31个attention tensors的weight reconstruction error，没有测量完整模型的下游输出质量。

💡 深度解析

6
不适合 我想把 108.81 GB 的 BF16 trunk 改成 int4，以便在更小内存的设备上运行；README 的证据是否足以支持这个改动？
适合读者： 计划把 108.81 GB BF16 trunk 改成 int4、以进一步降低内存占用的量化研究者

不适合直接采用，因为 README 的量化实验显示 int4 会引入显著权重重构误差，而且没有证明下游输出质量可接受。

  • 项目明确保留 trunk 为 BF16；只有两种权重类型：WF32 和 WBF16，没有 trunk 位宽开关。
  • 对 31 个 attention tensor 的抽样中，int8 平均相对误差约 1%，int4 约 17%，最差行达到 65%。这不是简单的存储收益问题。
  • README 引述模型报告称专家使用经过量化感知训练的 MXFP4，而非专家组件保持更高精度；trunk 并未被证明能承受四比特量化。
  • 文档同时明确指出，该研究测量的是权重误差，不是输出质量，也没有进行 int4 的 logit 或 token 对比。因此不能据此声称修改后仍保持原输出。

更稳妥的结论是：项目支持专家的 MXFP4 路径，但不支持把 BF16 trunk int4 化作为已验证方案。

  • README 章节 Part IV: Measurements / Why the trunk is not quantised
  • README 原句："This one has exactly two weight types and no knob at all"
  • README 原句："int4 mean ... 0.17383"、"worst individual rows at int4 reach ... 65 percent relative error"
  • README 原句："this is weight reconstruction error and not output quality"
材料未说明：README 未给出 trunk int4 改动后的完整模型输出、困惑度、logit 或任务质量结果。；README 未说明是否存在经过量化感知训练、可直接替换 BF16 trunk 的官方权重。
适合 我只有 8 GB RAM 和一台没有 GPU 的普通笔记本，能否用这个项目运行 2.78T 的 Kimi K3？
适合读者： 只有 8 GB RAM、没有 GPU、希望在普通笔记本上运行 2.78T Kimi K3 的个人研究者

适合，但它解决的是“能运行”，不是“低延迟交互”。

  • README 明确报告 8 GB 峰值 RSS，并说明专家权重不会常驻内存，而是从磁盘流式读取；完整 checkpoint 仍需要约 1.56 TB 磁盘空间。
  • 8 GB laptop preset 的示例速度为 26.5 秒/token，README 的实测命令为 8.24 GB 峰值 RSS、32.69 秒/token；因此普通笔记本可以完成推理，但生成会很慢。
  • 项目不依赖 BLAS、深度学习框架或 GPU，核心是可移植 C99，并包含 OpenMP、SIMD 和模型读取链路。

第一步可以先在不下载 checkpoint 的情况下编译和运行无权重测试；这样不会立即承担 1.56 TB 数据准备成本。

  • README 原句："A 2.78-trillion-parameter model. One CPU. 8 GB of RAM."
  • README 原句："1.56 TB checkpoint on disk"、"8.24 GB peak RSS"
  • README 章节 Part I: Getting started / Quick start
  • README 原句："an ordinary laptop 8 GB 26.5 s"
make -j
材料未说明：README 摘录没有给出这台笔记本的具体 CPU、磁盘顺序读取速度和可用文件系统空间，因此无法判断实际 token 延迟。；README 未说明该笔记本是否满足项目所需的具体编译器版本和指令集要求。
适合 我需要在准备 1.56 TB checkpoint 之前，先确认 C99 引擎、KV cache、KDA state 和增量解码都正确；这个项目能否支持这种验证流程？
适合读者： 需要在下载 1.56 TB checkpoint 前验证模型执行图和增量解码正确性的推理测试工程师

适合，因为 README 明确提供了无权重、无网络、无 Python 的验证路径，并且测试覆盖了增量状态而不只是最终字符串。

  • Quick start 写明整个流程不需要 checkpoint、网络或 Python，make test 通常在一分钟内完成。
  • 测试包含 teacher forcing、greedy decode 和 incremental decode；README 特别标注 incremental gate 会检查 KV cache 与 carried KDA state。
  • 测试使用仓库内的 13 层小模型和 PyTorch reference fixture，验证 tokenizer、safetensors reader、配置读取、完整解码和增量解码。
  • 只有无权重测试通过后，才进入 checkpoint 获取和 trunk packing 阶段，这能把编译或算子错误与超大文件准备成本分开。

这对底层推理实现的回归测试很合适，但它不能替代完整 2.78T checkpoint 上的性能和存储验证。

  • README 章节 Part I: Getting started / Quick start
  • README 原句："No checkpoint, no network, no Python"
  • README 原句："GATE 3 incremental : 20/20 generated tokens match full_ids <- KV cache + carried KDA state"
  • README 原句："a 13-layer model ... checked against a PyTorch reference"
make -j
材料未说明：README 摘录没有列出无权重测试覆盖的全部算子边界，也没有给出每个平台的测试矩阵。；README 未说明小模型 oracle 与完整 Kimi K3 checkpoint 之间仍可能存在的模型特定错误类型。
适合 我正在研究 KDA、MLA、MoE 路由和 MXFP4，希望在无 BLAS、无深度学习框架、无 GPU 的 C99 环境中逐层检查完整推理链路，这个项目是否适合？
适合读者： 研究 KDA、MLA、MoE 路由和 MXFP4 内核的 C/C99 系统工程师，希望在无 BLAS、无框架环境中复现推理链路

适合，因为项目本身就是围绕可审计的 C99 推理链路和模型结构实现构建的。

  • README 将实现定义为 portable C99、No BLAS、No framework、No GPU，核心引擎约 176 KB，便于直接阅读文件读取、算子和状态传递代码。
  • Part II 覆盖 safetensors、配置解析、tokenizer、KDA 线性注意力、MLA、MoE 专家选择、MXFP4 权重和 LRU 专家缓存等组件。
  • make test 会验证 teacher forcing、greedy decode 和 incremental decode，并用 13 层小模型与 PyTorch reference 对照；这比只验证最终文本更适合定位 KV/KDA 状态或增量解码错误。
  • 项目数据还列出 AVX2、SIMD、OpenMP，以及 macOS、Windows 和 NEON 适配，但不同平台的具体性能仍需单独测量。
  • README 原句："Portable C99. No BLAS. No framework. No GPU."
  • README 原句："176 KB the whole engine"
  • README 章节 Part II: How it works / The four reductions / An LRU cache for the experts
  • README 章节 Part III: Validation / Quick start 中的 GATE 1、GATE 2、GATE 3
make test
材料未说明：README 摘录没有给出每个算子对应的完整源文件映射，也没有说明各平台 SIMD 路径的覆盖边界。；README 未说明在 Windows、macOS 和 NEON 平台上是否都能获得与主测量环境相同的数值一致性。
视情况 我只有单机 CPU 和本地磁盘，想用官方 Kimi K3 的 XTML 格式进行多轮聊天；这个项目是否适合，而不是只做原始文本续写？
适合读者： 要用官方 Kimi K3 XTML 多轮聊天、但只有单机 CPU 和本地磁盘的离线实验人员

视情况：功能路径适合，但交互体验取决于 RAM、磁盘和对几十秒每 token 延迟的接受程度。

  • README 区分了 batch prompt 的原始续写和官方 Kimi K3 的聊天模式；需要多轮对话时，应使用 XTML REPL，而不是把 batch 示例当作聊天接口。
  • 项目支持聊天模式、tokenizer、KV cache 和增量解码，因此从功能上覆盖了本地多轮推理所需的链路。
  • 但 8 GB 示例约为 26.5 秒/token，且完整 checkpoint 约 1.56 TB；低内存设备会持续从磁盘读取专家和 trunk。
  • README 和项目洞察都把它定位为离线、底层研究和可复现实验工具，而不是实时聊天或并发服务平台。

如果目标是验证 XTML 格式和多轮状态，它合适；如果目标是流畅聊天体验，则不适合仅凭“能在 CPU 上运行”作判断。

  • README 原句："This particular batch command deliberately asks for a raw continuation"
  • README 原句："use the XTML REPL below when you want answers and multi-turn history"
  • README 原句："the official Kimi K3 checkpoint is also chat-capable"
  • README 原句："an ordinary laptop 8 GB 26.5 s"
make test
材料未说明：README 摘录没有给出 XTML REPL 在不同上下文长度下的具体 token 延迟和状态内存增长。；README 未说明多轮聊天是否支持并发会话、会话持久化或外部服务接口。
适合 我有 128 GB 以上 RAM、快速 NVMe 和 124 核 CPU；如果目标是降低 Kimi K3 的单 token 延迟，这个项目是否比 8 GB 配置更合适？
适合读者： 拥有 128 GB 以上 RAM、快速 NVMe 和 124 核 CPU 的工作站使用者，希望降低 Kimi K3 单 token 延迟

适合，因为该项目把更多 RAM 直接转化为更少的磁盘等待，但它仍不是 GPU 服务引擎。

  • README 的内存阶梯显示，8 GB、32 GB、64 GB 和 128 GB+ 的时间分别为 26.5、24.2、19.8 和 5.6 秒/token；128 GB+ 时模型完全驻留内存，磁盘等待消失。
  • 文档还指出，在同一台 124 核机器上，前几档仍受磁盘读取影响，因此 CPU 核数不能单独消除存储瓶颈。
  • 项目保持不同内存预算下的输出字节一致，增加 RAM 主要改变速度，而不是改变结果。

因此，这个工作站适合做可复现的低吞吐推理实验；若需求是并发 API、实时聊天或高吞吐生产服务，README 明确不把它定位为这类平台。

  • README 原句："128 GB+ 5.6 s"、"the model fits entirely in memory, the disk wait is gone"
  • README 原句："One machine, 124 cores, fast NVMe drive"
  • README 原句："the output was byte-identical from the smallest machine to the largest"
  • 项目洞察：usage_limitations 明确写明不适合实时聊天、并发请求或大规模 API 服务
make test
材料未说明：README 摘录没有给出该 124 核工作站的具体 OpenMP 配置、CPU 型号或 NVMe 吞吐，因此 5.6 秒/token 不能直接视为保证值。；README 未提供并发请求下的吞吐、队列行为或服务接口指标。

✨ 核心亮点

  • 8.24 GB峰值RSS运行2.78T模型
  • C99无BLAS、框架或GPU依赖
  • make test验证13层参考图精确匹配
  • 1.56 TB checkpoint按步从磁盘流式读取

🔧 工程化

  • make -j构建C99引擎，make test运行无权重测试
  • 支持Kimi K3批量prompt、增量生成与XTML REPL

⚠️ 风险

  • 8 GB机器每步读盘，示例平均32.69 s/token
  • 磁盘I/O占墙钟41%-61%，慢盘会继续拖慢生成
  • trunk不量化，int4采样相对误差最高达65%

👥 适合谁？

  • 有8 GB RAM且能接受26.5 s/token的本地开发者
  • 需要无BLAS、无框架、无GPU的C99实现者
  • 拥有128 GB以上内存、希望消除磁盘等待的用户