一只蜂鸟如何喂饱九头大象:Colibri 引擎把 744B 到 2.8T MoE 跑在 25GB 内存上的诚实拆解
💬 评论纯 C 推理引擎 Colibri:把 VRAM/RAM/NVMe 当成单一存储层级,JIT 思维跑权重,9 个模型族共用一套 headers——一篇讲透蜂鸟擎大象的工程级魔术。
仓库:JustVugg/colibri ↗ v1.11.0 · 2026-09-15 · ~6MB tarball / 9 个模型族 / 10 个 engine binary “Tiny engine, immense model.”
如果一个 12 核、25GB 内存、12GB VRAM 的笔记本,让你运行一个 744B 参数的 frontier MoE 模型——你会觉得这是在开玩笑。
Colibri 不是在开玩笑。
它是一行 COLI_MODEL=/nvme/glm52_i4 ./coli chat,在 25GB 的机器上冷启 32 秒,把蜂鸟擎起来——一个 744B 的 GLM-5.2 MoE。代价是 0.05 tok/s(冷盘)到 6.84 tok/s(6 张 RTX 5090 全驻)。
这篇文章是想让你先慢下来,再去看它做了什么。
一、先停一下,别急着看代码#
你买过 H100 吗?80GB 显存。卖 30 万。装不下 744B 的 GLM-5.2。
每次缺一截,每次缺一截。每一次工程师拿着预算说”再加一台”。
如果你是 Colibri 的作者(JustVugg),你会怎么办?你会发现一件事——
744B 是 744B,但一次 token 只用 ~40B。
40B 占 ~5.4%。也就是说,94.6% 的参数在你问的整个过程里是死的。
死的东西,可以留在慢的地方——比如 SSD 盘。
慢不等于错。慢只是慢。
这是 Colibri 整个工程的起点。剩下的全是把这个直觉做扎实。
二、三个数字,一只蜂鸟#
如果你只想记住三个数字,记住这三个。
| 数字 | 含义 | 为什么重要 |
|---|---|---|
| 5.4% | 744B 中每次激活的参数比例 | 决定了你不需要装进内存的东西总量决定装机量 |
| 11GB | 一次 token 真正从 SSD 读的数据量 | 决定了你真正要搬的东西总量决定真实带宽 |
| 71.6% | 路由下一层 expert 的预测命中率 | 决定了你等盘的时间总量决定 tok/s 的天花板 |
这三个数字来自 GLM-5.2,也是所有 MoE 故事的实质——只要你相信 MoE 路由有规律(expert atlas 是被实测出来的,不是营销词),你就能把这三个数字摆在你面前,然后说服自己这是工程,不是奇迹。
三、单一推理层级 —— 不要把”在哪一层”和”是不是对的”绑在一起#
3.1 三个 tier,一张图#
Colibri 把 VRAM、RAM、NVMe 当作同一组权重的三个 placement tier:
┌──────────────────────────────────────────────────────────┐
│ VRAM tier │
│ · 最快;不存在时引擎照常工作 │
│ · 6×RTX 5090 全驻 = 6.84 tok/s │
└──────────────────────────┬───────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ RAM tier │
│ · 稠密(~17B) 常驻 int4 ≈ 9.9 GB │
│ · 25 GB 笔记本刚好兜住 dense + 一部分 routed │
└──────────────────────────┬───────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────┐
│ NVMe tier │
│ · 19,456 routed experts ≈ 370 GB 流过来 │
│ · O_DIRECT 可加 +34% decode │
│ · 双盘镜像可加 +33% aggregate bandwidth │
└──────────────────────────────────────────────────────────┘关键的不变性:同一个 mask,同一个 router,同一个精度——不管 expert 是从 VRAM 还是从盘里回来,生成的 token 完全 bit-identical。
这是一个非常重要的事实,我希望你慢点读:
placement 只决定速度,不动 router decisions、不动权重精度。
这是 Colibri 的硬保证(原文 a hard guarantee on semantics)。没有这条,MoE 就只是一场”哪些参数够快”的赌博。有了这条,它变成一个 placement problem。
3.2 三个 JIT-style 杠杆#
三个不为”快就行”服务的可调杠杆——每个都有负结果在旁边:
.coli_usage历史:每个 token 路由都写一行<layer> <expert> <count>,sparse 文本。它可以过拟合你的 prompt——#175列了 cross-session A/B 计划- learned pinned hot-store:基于历史计算哪些 expert 升格为常驻。25% margin 防 ping-pong(老 expert 不会因新 expert 短暂偏热被挤出)
- one-layer-ahead prefetch(PILOT):路由器预测下一层,异步搬盘。实测 71.6% 预测准——剩下 28.4% 是真读
但这里有一个不优雅但诚实的细节:
route_trace.h把 “为什么这样写” 写在注释最前——包括为什么 field 1 不能放 string(fscanf 会断),为什么 engine_id 必须在 field 3(否则 int overflow)。
这不是教科书上的建议,这是写完才补不上的工程教训。分享出来,是为了下一个新引擎的作者少踩一次。
四、PILOT:用上一层的眼睛,看下一层的路#
4.1 路由是有规律的#
如果路由完全随机,11GB/token 就只能等盘读。
但 JustVugg/colibri 的实测 atlas 显示:1,041 个 specialist 是 cluster 成块的——诗歌、法律、中文、SQL 这些域,各自的 experts 是有亲缘关系的(见 docs/media/collab-atlas.png 和 issue #175)。
亲缘 = 可预测 = 可以提前搬。
4.2 PILOT 不是 PIPE#
| 杠杆 | 干什么 | 成本 | 何时有用 |
|---|---|---|---|
PIPE=1(默认) | bounded async I/O pool,算这一层时读下一层 | 增加几路线程 | 默认开,几乎必赢 |
PILOT=1 | 路由器先跑一层,只 prefetch 选中的 experts | 仅 hint,小负载 | PIPE=1 之上更优 |
O_DIRECT=1 | 跳过 page cache | 视盘而异 | DRAM-cached SSD 必开,QLC 反而慢 |
三层叠起来就是:算这一层(在 CPU/GPU)+ PIPE 异步读下一层 + PILOT 预测下一层选谁 + O_DIRECT 让 SSD 真发力。
实测(Blackwell / Windows,docs/benchmarks.md):
+34% decode measured with PIPE=1——4.25→9.69 GB/s in iobench on a GB10
但注释里也写了:
QLC/DRAM-less or virtualised disks can be neutral to negative. Try it first; keep what your hardware rewards.
先调参,再相信。这是 Colibri 全文反复出现的态度。
4.3 batch-union:多个 token 选同一个 expert 只读一次#
一个 batch 的 8 个 token,可能选了 64 个 expert,但去重后可能就 30 个 unique。这是 30 次读,不是 64 次。
这就是 expert_store.h 的 lease 接口——lookup() 拿一份 view(不可复制、不可并发)、用完 release()、prefetch 不抢有 lease 的 slot。这是一个租约,不是一个引用。
/* ExpertStore lease contract:
* - After a successful lookup(), the caller must call release() exactly once
* on the same view (same store). Do not copy ColiExpertView; the lease is
* not shareable.
* - On lookup failure the view is cleared; the caller must not use it and
* must not call release().
* - release() clears the entire view. release() on an already-cleared or
* zero-initialized view is a no-op.
* - destroy() requires zero active leases (debug builds assert). */四行的契约,解释了一个租约式内存管理。在所有用 cache + async + 跨语言边界的系统里,这都是核心问题——Colibri 把答案写在头注释里。
五、Dual-SSD:两盘同一份模型,各跑一半#
5.1 一句命令可加 33% 带宽#
COLI_MODEL=/fast/glm52_i4 COLI_MODEL_MIRROR=/second/glm52_i4 ./coli chat
COLI_DISK_WEIGHTS=9,3 ... # primary,mirror bandwidth ratio (else measured at startup)两个 SSD 装同一份 370GB 的 GLM-5.2 int4,启动时校验一致性(per-file size + safetensors header),然后用 deterministic hash(expert_id) → 9:3 加权 把读流量分流到两盘。
实测:decode ~33% 提速(docs/benchmarks.md)。PIPE=1 + O_DIRECT=1 还能再叠 +34%。
5.2 失败模式都不”丢”#
- 镜像盘掉了 → 一次 warning,fallback 到 primary,引擎不挂
- 镜像不全(小盘装不下整份) → planner 算 hot shards,优先放高频的,partial 仍 OK
- 镜像数据不齐 → 启动时校验,不一致静默退回 primary
./c/coli mirror plan --model /fast/glm52_i4 --mirror /second/glm52_i4 \
--budget-gib 200 --reserve-gib 20
./c/coli mirror stage --model /fast/glm52_i4 --mirror /second/glm52_i4 \
--budget-gib 200 --reserve-gib 20
./c/coli mirror verify --model /fast/glm52_i4 --mirror /second/glm52_i4三个命令,plan → stage → verify,SHA-256 对账,临时文件,留 reserve,不删已有 mirror shard,原子发布 receipt。
这一切的契约是:never silently changes model precision or router semantics。
六、9 头大象 + 一只蜂鸟 = 同一套工具链#
README.md 列了 9 个模型族,一个不漏:
| 模型 | 总参数 / 激活 | 磁盘权重 | 引擎 |
|---|---|---|---|
| GLM-5.2/5.3 | 744B / 40B | 372 GB int4 | colibri.c (12237 行) |
| GLM-5.3-Flash | 321B / 40B | 195 GB(转换后) | glm53.c |
| Inkling | 975B / 41B | 469 GB int4 | inkling.c (3261 行) |
| Kimi K3 | 2.8T / 104B | 1.6 TB 原生 MXFP4 | kimi_k3.c (4084 行) |
| DeepSeek V4 Flash | 284B / 13B | 167 GB 原生 fp4 | deepseek_v4.c (18348 行) |
| DeepSeek V4.1 Flash | 552B / 16B | 203 GB(n-gram 在盘上) | deepseek_v41.c |
| Qwen3.8-Flash-Next | 125B + 51B n-gram / 6B | 185.5 GB FP8 原生 | qwen38.c (2661 行) |
| Qwen3.6 | 35B / 3B | 20 GB int4-gs64 | qwen36.c (3802 行) |
| OLMoE | 7B / 1B | 7 GB int8 | olmoe.c (2272 行) |
每个引擎一个 C 文件,架构差异(MLA / DSA / KDA / Gated DeltaNet / PLE / n-gram)留给自己,safetensors reader / quant decoders / tokenizer / tier admission / expert store / route_trace 共用同一套 headers。
README 里有句话非常关键,值得全文记住:
One
.cper model family, over shared single headers. An engine owns its architecture and nothing else; anything two engines both need — the safetensors reader, the container decoders, the tokenizer, the expert cache — lives in a header they both include, so a fix reaches all of them at once.That rule is not decorative: the defects that keep recurring here are the ones where a mechanism landed in one engine and never reached its siblings.
这是项目维护的开销约束:共享机制不能只在一个引擎,永远不。
6.1 启动选 engine#
./coli 看 config.json 里的架构标识,选正确的引擎 binary,渲染对应的 chat template。所以命令完全一致:
make -C c glm
make -C c inkling
make -C c kimi_k3
COLI_MODEL=/nvme/glm52_i4 ./coli chat # TUI
COLI_MODEL=/nvme/inkling_i4 ./coli chat
COLI_MODEL=/nvme/kimi_k3 ./coli chat
./coli web --model /nvme/inkling_i4 # API + dashboard,带浏览器
./coli serve --model /nvme/inkling_i4 # API + dashboard,不带用户不需要知道现在是 GLM 还是 Inkling——模型不一样,命令一行。
七、诚实胜过速度 —— 这是这个项目最让人尊敬的部分#
如果你只看速度表,你会觉得 Colibri 是一个”便宜的 transformer 替代品”。
不是。
它是一个诚实的工程博物馆。CHANGELOG 和 README 里到处是”曾经对,后来错”的记录。我列了三个:
7.1 MTP head 必须是 int8,不是 int4#
int4 MTP head → 0-4% acceptance [#8]
int8 MTP head → 2.2-2.8 tok/forward社区当时用 int4 跑,接受率几乎是 0。后来调成 int8 才有意义。这是量化噪声把整条捷径堵死的真实故事。
7.2 MTP 在 85% expert hit 时反而亏 32%#
routing-aware speculation can pay before near-full residency
· MTP and grammar drafts work, but
· MTP has also measured a 32% loss around 85% expert hit测机不测环境,把”投机解码总是好”打成 bug。Colibri 的 DRAFT=0 默认就是这个负结果。
7.3 Qwen3.6 选 int4-gs64,不是 int4 per-row#
int4-gs64 · measured cosine 0.98777 → 0.99313
KL 0.109 → 0.080 against per-row
~44% less quantization error
int4 per-row · A/B baseline (差 9pp)不是调参数,是换基线。换对了,KAT-Coder v2.5 的同架构模型直接兼容。
7.4 研究使命(原文)#
Nothing is protected merely because it is conventional; nothing is adopted merely because a microbenchmark looks fast. The deciding result is end-to-end inference on real machines, with correctness and quality measured alongside throughput, latency, memory, and cost.
这一段在 README 的中部。一个开源项目把”为什么我可以相信这个数字”写在这里,而不是写在 release note 里——这是这个项目和那种”fast number but unknown provenance”项目的根本区别。
八、复盘:这只蜂鸟教会我们的事#
你看完 7 节,我想留 5 条任何人都能用的工程启示:
8.1 placement 不动语义——分层只是分层#
把”性能层”和”语义层”严格切开。VRAM / RAM / SSD 不是三个真相,是同一份权重的三个副本。变的是速度,不是答案。这条规则在缓存、CDN、边缘计算、所有多层级架构里都成立。
8.2 先慢再快——承认有个下限#
Colibri 在 25 GB 笔记本上跑 0.05 tok/s——它真的告诉你这是底线,而不是”可以更快”。
微基准不可信。端到端 + 真实机器 + 同时测速度和正确性才可信。
8.3 把”为什么这样写”写在注释最前#
route_trace.h 头部 30 行注释,先把”为什么这个 header 独立而不是 telemetry.h 一部分”写完。先把”这两个 field 不能乱”写完。
这种注释写完是不会再读的——但新人第一次读会读到。这一个新人就是项目未来 5 年的关键杠杆。
8.4 共享机制不偏不倚#
任何”机制只能在某个引擎里”的代码路径,会在 6 个月后成为 bug 滋生地。要么移到 shared header,要么不写。
8.5 负结果也是结果#
CHANGELOG 里 “int4 MTP head acceptance 0%”、“MTP at 85% hit -32%”、“per-row int4 比 gs64 差 9pp”——这些是比 fast number 更值钱的证据。
A well-controlled failure is more valuable here than an unexplained fast number.
一些统计#
- 仓库大小:~6MB tarball(下载),~30MB 解压
- 引擎代码:
colibri.c12237 行(GLM-5.2),deepseek_v4.c18348 行(DS V4) - 共用 headers:
st.h(1108)/quant.h(2102)/tok.h/tier.h/expert_store.h/route_trace.h等 23K 行 - 9 个模型族:GLM-5.2/5.3 / GLM-5.3-Flash / Inkling / Kimi K3 / DeepSeek V4 Flash / V4.1 Flash / Qwen3.8-Flash-Next / Qwen3.6 / OLMoE
- 4 个后端:CUDA / Metal(Apple Silicon)/ Vulkan(Mesa RADV,包括 ROCm 不再支持的 RX 580)/ CPU(x86 + aarch64)
- License:纯 MIT,0 个 engine 依赖
- 实测数据:
docs/benchmarks.md完整硬件类对比 - 启动:12 核笔记本 25GB,32 秒,9.9GB 稠密常驻
- 速度天花板:6×RTX 5090 全驻 = 6.84 tok/s
- 速度底线:25 GB 笔记本冷启 = 0.05-0.1 tok/s
- 项目成熟度:6 大 GPU / CPU 实测,9 模型族,CHANGELOG 579 行
参考#
- JustVugg/colibri 仓库 ↗
README.md↗ — 715 行,真正的项目哲学docs/CACHE_ROUTE.md↗docs/quickstart.md↗docs/benchmarks.md↗docs/ENVIRONMENT.md↗ — 503 行环境变量清单c/route_trace.h↗ — 30 行头注释教你”为什么这样写”c/expert_store.h↗ — 租约式内存管理的样板c/tier.h↗ — adaptive resident tier 算法,4 个纯函数 70 行c/colibri.c↗ — GLM-5.2 引擎,12237 行- issue #175 — measured expert atlas ↗
- issue #8 — MTP int4 vs int8 ↗
- issue #163 — SPEC_PIN forensic story ↗
- eBPF.io — JIT 比喻的近亲 ↗
- REAP, SERE, MoBE, HybriMoE 等论文 — 致谢中列了 11 篇 ↗