在 2025–2026 年，前沿开源大模型的参数量突破了 7000 亿级别。以 GLM-5.2 为例，它是一个 744B 参数的 MoE（Mixture-of-Experts） 模型，官方 FP8 权重在磁盘上约 756 GB。要运行它，常规做法需要一整机柜的 GPU、数百 GB 显存——这把普通开发者彻底挡在门外。
但 MoE 有一个关键性质：每个 token 只激活约 40B 参数，其中真正逐 token 变化的"路由专家"只有约 11 GB。colibrì（意大利语"蜂鸟"）正是抓住这一点，做了一件近乎"不可能"的事：
- 稠密部分（注意力、共享专家、embedding，约 17B 参数）以 int4 量化 常驻内存（约 9.9 GB）；
- 21,504 个路由专家（75 个 MoE 层 × 256 专家 + MTP 头，每个约 19 MB）留在磁盘上（约 370 GB），按需流式加载，配合每层 LRU 缓存、可选的固定热专家存储（pinned hot-store）、以及操作系统页缓存这个"免费的 L2"。
结果是：一个 744B 前沿模型，在一台 25 GB 内存、12 核、连一块 H100 都买不起的消费级机器上，正确地回答问题。整个推理引擎是单个 C 文件（c/glm.c，约 2500 行）加几个小头文件，零依赖——没有 BLAS，没有 Python 运行时，不需要 GPU（有一个可选的 CUDA 层用于固定专家）。
colibrì 由 JustVugg 一人在一台 12 核、25 GB 内存的笔记本上写成并测试。它是"mechanical sympathy"（贴合硬件的工程哲学）的一次极致演绎：把量化、SIMD 整数点积、投机解码、KV 压缩、磁盘流式与页缓存这些技巧组合到一起，让磁盘 I/O 而非显存成为唯一的物理瓶颈。
从源码出发，逐模块拆解 colibrì 的核心机制：
- 不是官方 README 的翻译——已有的使用说明不再重复
- 不是论文的复述——聚焦于 C 代码层面的具体实现
- 可点击直达源码行号——每个代码引用链接到 submodule 中固定 commit 的精确行
- 由浅入深——从架构全景逐步深入到 int4 packing 的 bit 操作、MLA 权重吸收、MTP 拒绝采样等细节
git clone --recurse-submodules https://github.com/chen3feng/colibri-analysis.git
cd colibri-analysis源码通过 git submodule 引入，固定在文档生成时的 commit。在 VS Code 中打开，Cmd/Ctrl + 点击 代码引用即可跳转到对应行。
| # | 文档 | 内容 |
|---|---|---|
| 1 | 架构概述 | colibrì 是什么、"流式专家"的核心思想、分层架构、一个 token 的完整生命周期、关键设计决策 |
| 2 | 代码结构与构建 | 单文件设计哲学、glm.c 的分区结构、头文件（st.h/json.h/tok.h/tier.h）、Makefile 与 SIMD/CUDA 探测、工具链 |
| 3 | 量化与矩阵乘内核 | QT 张量类型、int8/int4/int2 packing、per-row 缩放、dequant-on-use 矩阵乘、IDOT 整数点积快路径（AVX512-VNNI/AVX2/NEON）、FP8→int4 转换器 |
| 4 | 初始化与权重加载 | 配置解析、Model/Layer/QT 布局、model_init、pread+posix_fadvise 与稠密常驻、专家留盘、embedding、RAM 安全预算 |
| 5 | 推理主流程 | step/layers_forward/layer_forward、一次 forward 的结构、prefill 与 decode、采样（温度+nucleus）、停止词、文本/评分/回放入口 |
| 6 | MLA 注意力与 KV 缓存 | q/kv-LoRA、交错部分 RoPE、压缩 KV-cache（576 floats/token）、MLA 权重吸收、DSA 稀疏注意力（lightning indexer）、KV 磁盘持久化 |
| 7 | MoE 路由与专家流式加载 | DeepSeek-V3 式 sigmoid 路由、共享专家、前 3 层稠密、专家 LRU 缓存、磁盘流式（pread/mmap）、pinned 热存储、tier 分层、repin 与"会学习的缓存" |
| 8 | MTP 投机解码与预取 | GLM-5.2 原生 MTP 头（layer 78）、draft/verify 单次批量前向、拒绝采样保持无损、n-gram draft、router-lookahead PILOT 预取 |
| 9 | CUDA 后端 | 可选的常驻 CUDA 层、固定专家上 GPU、量化内核、多卡预算分配、与磁盘流式分层的组合 |
| 10 | 服务与工具链 | 进程内 HTTP 服务、OpenAI 兼容 API、有界 FIFO 调度、KV slots、openai_server.py 网关、resource_plan 规划器、Web UI |
| 11 | 适用边界与限制 | 只吃 safetensors 不支持 GGUF/Q4_K_M、架构写死 GLM-5.2、精度代价、硬件平台边界（无 ROCm/Metal-MPS） |
- 精确行号：每个代码引用形如
[glm.c:865](../colibri/c/glm.c#L865)，可点击直接跳转 - 可验证：所有行号基于 submodule 中的固定 commit，不会溯源失效
- 架构图：ASCII 流程图和调用链，无需外部工具即可阅读
- 表格总结：每个模块末尾有关键设计决策和行号对照表
按照人类分析代码的路径，系统性地阅读代码：
- 确定分析角度——每篇文档围绕一个核心问题（"专家如何从磁盘流式加载？""MLA 如何把 KV 压缩 57 倍？"）
- 逐层探索——从入口点开始，跟踪调用链；找到关键函数后，读取具体实现
- 回到源头——文档中的行号都是通过 grep/read 精确查找得到的，不是推测
探索完成后，整理出结构化的文档：
- 代码引用可点击——每个函数名、结构体、关键常量后附带
[file:line](path#L行号)格式的链接 - 架构图——生成 ASCII 流程图、调用链、层次关系图
- 交叉引用——文档间互相链接，形成体系
colibri/ 作为 git submodule，固定在文档生成时的 commit a5fc89e88f113fc9d1c9d8752861b158d7c303e7。这保证了：
- 所有行号永久有效
- 查看者可以在 GitHub 上看到文档引用的那个版本的源码
- 后续更新时，只需更新 submodule 指针并检查差异
cd colibri-analysis
cd colibri && git fetch origin && git checkout <new-commit> && cd ..
git add colibri
# 对比新旧版本差异，更新文档
git commit -m "Update colibri submodule to <new-commit>"注意：
docs/index.md是 GitHub Pages 的入口页面，Jekyll 构建时会将其生成为index.html。缺少此文件会导致站点根路径 404。新增文档时无需动它，但不要删除。
首次部署或迁移仓库时，确认以下文件齐全：
docs/
├── index.md # ★ 必须：首页，Jekyll 生成 index.html
├── _config.yml # ★ 必须：Jekyll 配置（remote_theme, url 等）
├── 01-xxx.md # 分析文档（需要有 YAML frontmatter: title + nav_order）
├── 02-xxx.md
└── ...
.github/workflows/deploy.yml 中的 link rewrite step 需要注意：
sed的匹配模式要与文档中的链接格式一致（这里是](../colibri/...）- submodule 路径变更时需要同步更新
submodules: false加速 checkout（只需 submodule 的 commit hash）
欢迎提交 PR 修正错误或补充新内容。请确保引用的行号与当前 submodule 版本一致。
本分析文档采用 MIT 许可。colibrì 引擎本身为 Apache 2.0 许可，GLM-5.2 权重由 Z.ai 以 MIT 许可发布。
