第 1 章 · 01 Colibrì 命题与 MoE 稀疏性洞见

第 1 章 · 01 Colibrì 命题与 MoE 稀疏性洞见

本节摘要:本节讲清 Colibrì 的核心命题——一个纯 C 的"tiny engine, immense model"推理引擎,要把 744B 到 2.8T 参数的前沿 MoE 模型搬到消费级和异构硬件上跑。关键洞见是 MoE 稀疏性:744B 模型每个 token 只激活约 5.4% 的参数,真正随 token 变化的"路由专家"只有约 11GB。模型不需要"塞进"高速内存,而需要被"智能放置"——稠密部分常驻 RAM,19456 个路由专家放磁盘按需流式加载。Colibrì 把这叫"权重的 JIT",与编译器 JIT 只编译热点代码同理。读完本节,你理解了为什么万亿参数模型能在你的笔记本上跑。

内容来源:原项目源码 README.md("The idea"/"How it works" 段)、docs/media/sparse.png 测量结论。

⚠️ 注意:本节所有数字(5.4% 激活、约 11GB 路由专家、约 17B 稠密、约 370GB 专家盘、19456 个专家)都是 GLM-5.2 744B 这个具体模型的实测值,不是通用理论值。换一个 MoE 架构(如 DeepSeek V4 284B、Kimi K3 2.8T)数字会不同,但稀疏性的结构性洞见一致。

学习目标

阅读完本节,你应当能够:

1. 复述 Colibrì 的命题(tiny engine, immense model;744B-2.8T 在消费硬件)。
2. 解释 MoE 模型每 token 仅激活约 5.4% 参数意味着什么。
3. 把模型拆成"稠密常驻部分"与"路由专家按需流式部分"两块,并说出各自大小。
4. 说清 19456 这个专家数是怎么来的(75 MoE 层 × 256 + MTP 头)。
5. 用"编译器 JIT 只编译热点"类比解释"权重 JIT 只加载热点专家"。
6. 理解"放置只决定速度、不改语义"是 Colibrì 的第一性原理。

一、命题:tiny engine, immense model

Colibrì 是蜂鸟(意大利语 colibrì),意指"小引擎、大模型"(tiny engine, immense model)。它是一个纯 C、零引擎依赖的 LLM 推理引擎,作者 JustVugg,Apache 2.0 协议,版本 1.4.0。它的命题写在 README.md 开头第一句:

Run frontier MoE models — 744B to 2.8T parameters — on consumer and heterogeneous hardware, in pure C with zero engine dependencies, by treating storage, RAM, and VRAM as a single inference hierarchy.

翻译过来就是:让前沿 MoE 模型——744B 到 2.8T 参数——在消费级和异构硬件上运行,用纯 C 实现、零引擎依赖,把存储、RAM、VRAM 当成同一个推理层级。 目前已经支持五个模型族,共用一套 coli chat/coli serve/coli web 前端:

• GLM-5.2(744B),引擎源码 c/colibri.c(9514 行)。
• Inkling(975B),引擎源码 c/inkling.c(2250 行)。
• Kimi K3(2.8T),引擎源码 c/kimi_k3.c(1938 行)。
• DeepSeek V4 Flash(284B),引擎源码 c/deepseek_v4.c(10993 行)。
• OLMoE(7B),引擎源码 c/olmoe.c(1211 行)。

注意这条架构红线:一个 .c 文件对应一个模型族(下一节详讲)。每个模型族都是独立的 C 文件,但都共享同一套头文件(st.h/quant.h/tok.h/expert_store.h)和同一个 coli 前端命令。

README.md 还给了一句定位的话值得记住:"Colibrì is an inference engine you can run today, and an open research platform."(它是一个你今天就能跑的推理引擎,也是一个开放研究平台)。这双重身份决定了它的很多设计取舍——既要有可用的默认行为(今天就能跑),又要保留机制的可证伪性(每个优化都能被测量、被推翻)。这条线索贯穿本章第三节。

二、核心洞见:MoE 稀疏性

万亿参数模型为什么能跑在消费硬件上?关键洞见是 MoE 模型的稀疏性。看 README.md "The idea" 段的测量结论:

A 744B Mixture-of-Experts model activates only ~40B parameters per token — and only ~11 GB of those change from token to token (the routed experts).

GLM-5.2 是 744B 总参数的 MoE,但每个 token 只激活约 40B 参数(约 5.4%)。这 40B 里还能进一步拆:

• 真正随 token 变化的部分:只有约 11GB 的"路由专家"(routed experts)。
• 其余的激活参数是 attention、shared experts、embedding 等几乎不变的部分。

总参数 744B ──┬── 每 token 激活 40B(约 5.4%)
              │       ├── 路由专家 ~11GB(随 token 变化,放磁盘按需流式)
              │       └── 稠密部分 ~17B(attention/shared/embedding,常驻 RAM)
              └── 其余 ~704B 在本 token 完全用不到
​

配图 images/sparse.png 直观展示了这一点——只有约 5.4% 的参数在每个 token 上是激活的。这意味着:真正需要随 token 搬运的数据量极小,大约就是 11GB 量级,这恰好是消费硬件能玩转的规模。

三、放置而不是塞进:稠密 + 路由专家

基于稀疏性洞见,Colibrì 把模型拆成两块,分别用不同的存储策略:

模型不需要"塞进"内存,而需要被"放置"——
  稠密部分 ~17B  →  常驻 RAM,int4 量化,约占 9.9GB
  19456 个路由专家  →  放磁盘 ~370GB,按需流式加载
​

README.md 给出的精确拆解:

• 稠密部分(attention、shared experts、embeddings,约 17B 参数)常驻 RAM,以 int4 量化存储,约占 9.9GB。这部分几乎不随 token 变,启动时一次加载。
• 19456 个路由专家(75 个 MoE 层 × 256 + MTP 头,每个在 int4 下约 19MB)放磁盘,约占 370GB。这些是按需流式加载的——哪个 token 路由到哪个专家,才去读那几个专家。

注意 19456 这个数字的来源:75 个 MoE 层,每层 256 个路由专家,再加上 MTP 头(多 token 预测头,推测解码用)。每个专家在 int4 下约 19MB——它内部是三个矩阵(gate/down/up),按 Colibrì 的存储约定这三个矩阵是相邻摆放的,可以一次 pread 读完(第 5 章详讲)。

💡 深潜要点:19456 个专家放 370GB 磁盘看似天文数字,但每个 token 真正需要读的只是当前层路由命中的那几个专家。如果一共有 75 层、每层平均激活 8 个专家,一个 token 也就读约 600 个专家 × 19MB ≈ 11GB——正好对应上面"随 token 变化的 11GB"。稀疏性把"必须随 token 搬运的数据量"从 TB 级压到了 GB 级。

这套拆解的工程意义还可以从启动开销看出。README.md 开头的 ./coli chat 启动日志写着 "ready in 32s · resident 9.9 GB"——这 32 秒主要在做什么?把稠密部分(约 9.9GB)从磁盘加载到 RAM。注意:启动只加载稠密部分,不加载路由专家。370GB 的路由专家留在磁盘,等推理时按需流式。这是"放置策略"的直接结果——启动快(只读 9.9GB),且峰值 RAM 只占稠密 + 缓存,不是整个模型。如果换成稠密模型范式(全权重常驻),744B 模型在消费硬件上根本启动不了。

⚠️ 注意:"约 9.9GB"是 GLM-5.2 在 int4 下的稠密部分实测。换模型族数字会变——DeepSeek V4 284B 的稠密部分大小不同,Kimi K3 2.8T 的稠密部分也不同。但结构性洞见一致:稠密部分常驻,路由专家按需流式。这也是为什么第 2 章 st.h 要做"只读需要的字节"——它就是这套策略在数据读取层的落地。

四、权重 JIT:像编译器 JIT 一样只编译热点

Colibrì 把上面这套策略叫**"权重的 JIT"**(a JIT, but for weights)。README.md 用编译器 JIT 做类比,极其精准:

Think of the core algorithm as a JIT, but for weights. A compiler JIT never compiles the whole program — it watches what actually runs and compiles the hot paths, just in time. colibrì makes the same bet about a 744B parameter space: parameters are not resident state to be held, they are data to be staged across a heterogeneous storage hierarchy (VRAM / RAM / NVMe), exactly when the router proves they are needed.

翻译关键句:"参数不是要被持有的常驻状态,而是当路由器证明需要它们时,跨异构存储层级(VRAM/RAM/NVMe)精确放置的数据。" 这句话的每个字都值得拆:

• 不是常驻状态(not resident state):与稠密模型"权重全在显存"的默认假设相反——MoE 的路由专家没必要全在显存。
• 跨层级放置(data to be staged across a hierarchy):VRAM/RAM/NVMe 不是"二选一能不能装下",而是"放哪层最快"。
• 路由器证明需要时(when the router proves they are needed):不是预测,不是猜测,是路由器算出 top-k 后才知道要哪个专家。
• 测量驱动(Measured routing heat):哪些专家是"热点",由路由器的实测历史决定。

类比编译器 JIT 的精妙之处在于:编译器 JIT 不编译整个程序,只编译热点代码——因为大部分代码很少执行。MoE 也是——大部分专家在大部分 token 上不会被激活。Colibrì 的 LRU 缓存、学习型固定热存(pinned hot-store)、一层前瞻预取,都是把"热点专家"留在高速层,把冷专家放在磁盘,这与 JIT 编译器把热点循环编译成机器码、冷代码留解释执行,是同构的工程哲学。

五、第一性原理:放置只决定速度

稀疏性洞见 + 权重 JIT,推出 Colibrì 的第一性原理(也是贯穿全书的心法):

有限的高速内存只改变速度,绝不改变模型语义。

README.md 在 "Core techniques" 第一条就说清楚:"One hierarchy, not limited by tier capacity. VRAM, RAM, and NVMe are placement tiers for the same weights; limited fast memory changes speed, not model semantics."

也就是说:

• 专家从 VRAM 应答,还是从磁盘应答,路由决策一样、权重精度一样、输出 token 一样。
• 25GB 内存的开发机能跑(慢,0.05-0.1 tok/s 冷启动),6× RTX 5090 全驻留也能跑(快,5.8-6.8 tok/s)。
• 同一个引擎、同一个 int4 容器——硬件只改变专家住哪一层。

这条原理贯穿后续所有章节:第 3 章的 LRU 缓存、第 4 章的多层放置、第 5 章的双 SSD,都在反复落实"放置只改速度"。它是 Colibrì 区别于"OOM 就报错退出"的传统推理引擎的根本所在。

⚠️ 注意:这里的"语义不变"是硬保证。Colibrì 自述"对速度没有 SLA,对语义有硬保证"——默认策略绝不静默改变模型精度或路由语义。高速内存不足可能降速,但绝不能悄悄重定义模型。后续章节你会看到很多优化(LRU 驱逐、预取、推测解码)都受这条硬约束管制,无法接受则必须默认关闭。

本节要点回顾

1. 命题:Colibrì 是纯 C 零依赖引擎,要把 744B-2.8T MoE 跑在消费硬件上,目前支持 GLM-5.2/Inkling/Kimi K3/DeepSeek V4/OLMoE 五个模型族。
2. 稀疏性洞见:744B MoE 每 token 只激活约 40B(约 5.4%),随 token 变化的路由专家只有约 11GB。
3. 放置策略:稠密部分约 17B 常驻 RAM int4 约 9.9GB;19456 个路由专家(75 层 × 256 + MTP 头,各约 19MB)放磁盘约 370GB 按需流式。
4. 权重 JIT 类比:编译器 JIT 只编译热点代码,Colibrì 只加载热点专家;参数不是常驻状态,而是按需跨层级放置的数据。
5. 第一性原理:放置只决定速度,绝不改变模型语义——这是全书的总纲。

下一节,我们看 Colibrì 为什么选纯 C 零依赖,以及"一个 .c 一个模型族"加"共享头文件"的架构红线。