colibrì 源码分析
colibrì（意大利语”蜂鸟”）是一个单文件、零依赖的纯 C 推理引擎，它做到了一件看似不可能的事：在一台 25 GB 内存、12 核的消费级机器上，正确运行 GLM-5.2 —— 一个 744B 参数的 MoE 大模型。
它的秘诀是”流式专家”：一个 744B 的 MoE 模型每个 token 只激活约 40B 参数，其中真正逐 token 变化的路由专家只有约 11 GB。于是 colibrì 把稠密部分（注意力、共享专家、embedding）以 int4 常驻内存（约 9.9 GB），把 21,504 个路由专家（约 370 GB）留在磁盘上按需流式加载，用每层 LRU 缓存、固定热专家、以及操作系统页缓存把磁盘瓶颈一点点抹平。
本项目从源码出发，逐模块拆解 colibrì 的核心机制——量化内核、MLA 注意力、MoE 路由、专家流式加载、MTP 投机解码——每一个论断都链接到 c/glm.c 中固定 commit 的精确行号。
文档
| # | 文档 | 内容 |
|---|---|---|
| 1 | 架构概述 | colibrì 是什么、”流式专家”的核心思想、分层架构、一个 token 的完整生命周期 |
| 2 | 代码结构与构建 | 单文件设计哲学、glm.c 的分区结构、头文件、Makefile 与 SIMD/CUDA 探测 |
| 3 | 量化与矩阵乘内核 | QT 张量、int8/int4/int2 packing、per-row 缩放、IDOT 整数点积快路径、FP8→int4 转换器 |
| 4 | 初始化与权重加载 | 配置解析、Model/Layer 布局、pread+posix_fadvise、稠密常驻、专家留盘、RAM 安全预算 |
| 5 | 推理主流程 | step/layers_forward、一次 forward 的结构、prefill 与 decode、采样、停止词 |
| 6 | MLA 注意力与 KV 缓存 | q/kv-LoRA、交错部分 RoPE、压缩 KV（576 floats/token）、MLA 权重吸收、DSA 稀疏注意力、KV 磁盘持久化 |
| 7 | MoE 路由与专家流式加载 | sigmoid 路由、共享专家、专家 LRU 缓存、磁盘流式、pinned 热存储、tier 分层、”会学习的缓存” |
| 8 | MTP 投机解码与预取 | GLM-5.2 原生 MTP 头、draft/verify 批量前向、拒绝采样保持无损、router-lookahead 预取 |
| 9 | CUDA 后端 | 可选常驻 CUDA 层、固定专家上 GPU、量化内核、多卡预算、与磁盘流式的组合 |
| 10 | 服务与工具链 | 进程内 HTTP 服务、OpenAI 兼容 API、有界 FIFO 调度、KV slots、Python 网关、资源规划器、Web UI |
| 11 | 适用边界与限制 | 只吃 safetensors 不支持 GGUF/Q4_K_M、架构写死 GLM-5.2、精度代价、硬件边界（无 ROCm/Metal-MPS） |
快速开始
git clone --recurse-submodules https://github.com/chen3feng/colibri-analysis.git
cd colibri-analysis
源码通过 git submodule 引入，固定在文档生成时的 commit。在 VS Code 中打开，Cmd/Ctrl + 点击 代码引用即可跳转到对应行。
特点
- 精确行号：每个代码引用形如
[glm.c:865](../colibri/c/glm.c#L865)，可点击直接跳转 - 可验证：所有行号基于 submodule 中的固定 commit，不会溯源失效
- 架构图：ASCII 流程图和调用链，无需外部工具即可阅读
源码
源码分析基于 colibrì 项目，版本锁定在 commit a5fc89e88f113fc9d1c9d8752861b158d7c303e7。
License
本分析文档采用 MIT 许可。colibrì 引擎本身为 Apache 2.0 许可。