FareedKhan-dev/kimi-k3-in-c

项目介绍

这个仓库是为 Kimi K3 从零实现的 C99 推理引擎。Kimi K3 是 2.78 万亿参数的混合专家模型，检查点体积达 1.56 TB。引擎不依赖 BLAS，不使用 PyTorch 或 ONNX 运行时，没有 GPU 路径，第三方数值库只有 libm 和 OpenMP。目标用户是希望在普通硬件上运行超大开源模型的人，并且愿意用速度和存储空间换取完全不用 GPU 的能力。

内存能压到这么小的原因是一连串缩减。路由专家本身以 MXFP4 格式发布，权重平均只占半个字节；每层 896 个专家中只激活 16 个，因此专家池可以留在磁盘上。始终参与计算的稠密主干被重新打包成一个 109 GB 的文件，通过“固定前缀加环形槽位”的方式流式读取，使实测峰值内存降到 8.24 GB。README 对 KDA、MLA 两种注意力、路由器、专家 LRU 缓存和验证门槛都有少见的详细说明，并用多个章节解释实现为何能与参考结果逐比特对齐。

快速使用

不下载检查点也能构建和测试。建议先走这一步，再决定是否开始大体积下载：

git clone https://github.com/FareedKhan-dev/kimi-k3-in-c.git
cd kimi-k3-in-c
make -j
make test

测试不需要权重、网络或 Python，一分钟内完成，正常结束会输出 VERDICT: ENGINE MATCHES THE REFERENCE EXACTLY，参见 快速开始。

运行真实模型需要完整流程：先用 ./scripts/k3-doctor.sh 检查机器，再用 Hugging Face token 执行 ./scripts/download-model.sh ~/k3model 下载检查点，然后用 ./scripts/pack-trunk.sh ~/k3model ~/k3trunk 打包主干，最后生成文本：

./bin/k3 ~/k3model --trunk ~/k3trunk --preset workstation \
         --tok ~/k3model --prompt "The capital of France is" --gen 8 --incremental

分词器随检查点一起发布，所以 --tok 指向模型目录，详见 完整安装步骤。中间结果：检查点约 1.56 TB，打包后的主干约 109 GB，第一次运行会加载所有固定层，因此比稳定生成阶段慢得多。

使用约束

• 存储是硬门槛。 需要约 1.7 TB 空闲空间（1.56 TB 检查点加 109 GB 打包主干），最好放在快速本地磁盘上。README 认为网络卷不适合这个引擎，并建议用 tools/devbw.py 实测磁盘。
• CPU 与系统。 参考平台是带 AVX2 和 FMA 的 Linux x86-64。macOS/arm64 和 Windows/x86-64 也能构建并通过测试，make portable 生成不带 -march=native 的通用 AVX2 构建。不要求 AVX-512。
• 内存预设。 --preset 选择主干与缓存的内存分配，从 ultra（计划约 3 GB）、laptop（实测峰值 8.2 GB）一直到 max（约 224 GB）。所有预设都流式读取主干，必须配合 --trunk；不指定时主干会整体驻留，约 113.5 GB。
• 生成默认值。 批量生成是贪心解码，在不同内存预算下输出一致；聊天模式可选用温度采样和 top-p。生成上限 4096 个 token，提示词上限 32768 个 token。生成长度不为 1 时应加 --incremental，否则每步都会重跑整个前缀。
• 分词器注意事项。 --prompt 和 --prompt-file 需要 --tok；非 ASCII 文本应使用 --prompt-file，因为 shell 会重新编码 argv。发布的检查点在两个配置文件中声明了不同的结束 id，应通过 --stop-id 同时传入。
• 功能范围。 第一版只支持纯文本 XTML 聊天，没有工具调用、视觉输入、HTTP 服务或上下文压缩。仓库不包含模型权重；Kimi K3 权重遵循 Moonshot AI 自己的许可，本仓库代码为 Apache-2.0。

HotRepo 点评

项目在 2026-11-04 进入 GitHub 全部语言日榜第 11 名，当天 10,017 星、1,606 个 fork，单日新增 351 星。对一个真实工作流要先花数小时下载 1.56 TB 的仓库来说，这个单日成绩相当突出。README 的深度同样少见：一位 Hacker News 读者形容它像是把完整论文放进了 GitHub README，原评论。这一点与材料相符——同一份文档里既有构建步骤，也有张量级不变量、测试门槛结果、从 8 GB 到 224 GB 的内存阶梯测量，以及主干为什么不量化的解释。因此它既是一个推理引擎，也是一篇详细的系统实现记录：告诉你怎么跑的同一份文件，也解释了每个设计选择的来由。