FareedKhan-dev/kimi-k3-in-c · 上手攻略
- 仓库：FareedKhan-dev/kimi-k3-in-c
- 链接：https://github.com/FareedKhan-dev/kimi-k3-in-c
- 分类：AI Infra · MoE Inference Engine
- 作者：Tom
- 更新：2026-08-09
这是什么
kimi-k3-in-c 是一个纯 C99 编写的 Kimi K3 推理引擎，可以在只有 8 GB 内存的单 CPU 机器上运行一个 2.78 万亿参数的 MoE（Mixture-of-Experts）模型。整个引擎只有 176 KB，无需任何 ML 框架（无 PyTorch、无 BLAS、无 CUDA、无 GPU）。
Kimi K3 是 Moonshot AI 的旗舰大模型，权重于 2026 年 7 月 27 日公开。该项目用四项工程技巧将本需 70 块 80 GB GPU 才能加载的模型，变成普通笔记本就能跑：
| 指标 | 数值 |
|---|---|
| 参数量 | 2.78 T |
| 磁盘 checkpoint | 1.56 TB |
| 峰值内存占用（测得） | 8.24 GB |
| 引擎二进制大小 | 176 KB |
| 所需 GPU | 0 |
解决什么问题
传统大模型推理依赖 GPU 显存或大量 RAM：K3 若以 16-bit 全精度存储需 5,560 GB。kimi-k3-in-c 的核心思路是把存储当作内存的延伸，而非一次性全量加载：
- 专家以 4-bit 打包存储，从盘直接流式读取，无需全部驻留 RAM
- Dense Trunk（93 层）压缩为 109 GB 单文件，可控制驻留深度
- KDA（Key-Density Attention）：固定内存的注意力机制
- MLA（Multi-head Latent Attention）：1 个隐向量代替 96 个注意力头
结果：同一台机器、同一段 prompt、输出字节完全一致（byte-identical），只是速度随内存增加而提升。
快速安装
硬件要求
| 条件 | 最低 | 推荐 |
|---|---|---|
| OS | Linux x86-64 | Linux x86-64 |
| CPU | AVX2 + FMA | AVX-512（非必须） |
| RAM | 8 GB | 128 GB+ |
| 存储 | ~1.7 TB 可用空间 | 快速 NVMe |
| 编译器 | GCC ≥ 9 或 Clang ≥ 10 | 同 |
⚠️ 不支持 ARM/macOS。项目使用
O_DIRECT、posix_memalign等 Linux 专属系统调用。
快速验证（无需下载模型）
git clone https://github.com/FareedKhan-dev/kimi-k3-in-c.git
cd kimi-k3-in-c
make -j # 编译，约几秒
make test # 运行全量测试，无需 checkpoint，约 1 分钟
测试通过会显示：
GATE 1 teacher forcing : 32/32 positions match tf_pred
GATE 2 greedy decode : 20/20 generated tokens match full_ids
GATE 3 incremental : 20/20 generated tokens match full_ids
VERDICT: ENGINE MATCHES THE REFERENCE EXACTLY
ALL WEIGHTLESS TESTS PASSED
完整安装（六步）
Step 1：检查机器
./scripts/k3-doctor.sh
会测量磁盘速度、检查 RAM 大小并推荐对应 preset，耗时约 1 分钟。
Step 2：编译引擎
make -j
# 或使用 CMake
cmake -B build && cmake --build build -j && ctest --test-dir build
Step 3：验证引擎（下载 checkpoint 前先做）
make test # 不需要 checkpoint，证明引擎正确性
Step 4：下载 checkpoint（1.56 TB，约数小时）
# 需要先在 https://huggingface.co/settings/tokens 生成 token
export HF_TOKEN=hf_your_token_here
./scripts/download-model.sh ~/k3model # 支持断点续传
下载后脚本会逐 shard 校验大小（总字节 + 每个 shard 独立校验），确保字节级一致。
Step 5：打包 Trunk（约 4 分钟，一次性）
./scripts/pack-trunk.sh ~/k3model ~/k3trunk
将 93 层 dense 权重重写为 109 GB 单文件，放置在最快磁盘上。
Step 6：运行推理
./bin/k3 ~/k3model --trunk ~/k3trunk --preset workstation \
--tok ~/k3model --prompt "The capital of France is" --gen 8 --incremental
硬件档位与速度参考
| 机器类型 | RAM | 每 token 时间（实测） |
|---|---|---|
| 普通笔记本 | 8 GB | ~26.5 s/token |
| 高端笔记本 | 32 GB | ~24.2 s/token |
| 台式机 | 64 GB | ~19.8 s/token |
| 工作站 | 128 GB+ | ~5.6 s/token |
⚠️ 所有数据均来自
docs/data/目录下的实测记录；速度随 prompt 长度和磁盘性能浮动。
核心用法
基本命令结构
./bin/k3 <model_dir> [选项]
无需 model_dir 的操作：
./bin/k3 --help # 查看全部选项
./bin/k3 --version # 查看版本
./bin/k3 --list-presets # 列出所有 preset
常用 preset
| Preset | 适用场景 | 内存占用 |
|---|---|---|
laptop |
8 GB RAM | ~8 GB |
server |
32 GB RAM | ~32 GB |
workstation |
128 GB+ RAM | ~128 GB |
生成选项
# 指定 token 数量生成
--gen 32
# 增量输出（边生成边打印）
--incremental
# 设置随机种子
--seed 42
# JSON 输出（需项目支持）
--format json
环境变量
| 变量 | 作用 |
|---|---|
HF_TOKEN |
HuggingFace 下载认证 |
OMP_NUM_THREADS |
OpenMP 线程数（默认自动） |
K3_TRUNK_PATH |
覆盖 --trunk 参数 |
典型适用场景
- 理解 MoE 推理原理：README 本身就是一篇小教材，配有架构图和测量数据，Part II 从第一性原理逐步构建每个组件
- 低硬件成本实验：无需 GPU 即可跑 2.78 T 大模型，适合学生、个人开发者研究
- 嵌入式/受限环境推理：纯 C，无任何外部依赖，可交叉编译到各种 Linux 环境
- 验证模型一致性：在低内存环境跑模型输出，与标准环境逐 token 比对，验证量化/加速方案
坑与注意
| 风险 | 说明 |
|---|---|
| Checkpoint 1.56 TB | 下载需数小时，磁盘空间必须充足；部分下载会产生错误 token（静默错误），不要跳过 shard 校验 |
| x86-64 Linux only | 不支持 macOS（M1/M2）、不支持 ARM、不支持 Windows（WSL 未测试） |
| Base 模型，非对话模型 | 无 chat template，给 "Paris" 开头会续写而非回答；对话需自行加 prompt wrapper |
| 速度极慢 | 即使用 128 GB 也要 ~5.6 s/token；这是教学/研究引擎，不是生产级服务 |
| v1.0.0 前后代际差 | README 中提到 v1.0.0 相较 v0.x：per-token 数学运算轻 8×、跟进问答快 3.9×、长 prompt 内存开销减半；建议确认所用版本 |
| O_DIRECT 磁盘要求 | 使用直接 I/O，需要文件系统支持；NFS 等网络文件系统可能有兼容问题 |
与同类对比
| 项目 | 语言 | 框架依赖 | 最低内存 | 量化方式 | 适用场景 |
|---|---|---|---|---|---|
| kimi-k3-in-c | C99 | 无 | 8 GB | 4-bit MoE streaming | 极致便携 / 教学 |
| llama.cpp | C++/C | 极轻 | ~4 GB（Q4） | Q4/K-quants | 生产 CPU 推理 |
| llm.c (karpathy) | C99 | 可选 PyTorch | 需大 RAM | FP16/INT8 | 简洁研究 |
| vllm | Python+CUDA | PyTorch | 需要大显存 | PagedAttention | 生产 GPU 推理 |
| MNN/BladeDISC | C++ | 框架绑定 | 可压缩 | INT8/FP16 | 移动端/端侧 |
核心差异：kimi-k3-in-c 是目前唯一用纯 C99、无任何依赖、实现完整 MoE 推理流式化的项目；llama.cpp 是最成熟的生产 CPU 方案但使用自定义模型格式；vllm 是 GPU 高吞吐生产方案。
一句话推荐结论
如果你想理解 MoE 大模型如何在极致受限环境下跑起来（8 GB RAM、无 GPU），或者需要一个零依赖便携推理引擎用于教学和研究，kimi-k3-in-c 是目前已知最彻底的实现——整个引擎 176 KB，README 是一篇带实测数据的 MoE 推理论文。
来源：GitHub README.md（Raw）· web_search 补充 Reddit/安全在线报道 · 2026-08-09
⚠️ Kimi K3 权重发布时间（July 27, 2026）及版本号（v1.0.0）来自 README 标注；per-token 速度为各 preset 实测中位数，磁盘性能差异会导致浮动。