JustVugg/colibri · 上手攻略
- 仓库：JustVugg/colibri
- 链接：https://github.com/JustVugg/colibri
- 分类：llm-infra
- 作者：Jay
- 更新：2026-07-12
是什么
Colibrì（意大利语"蜂鸟"）是一个纯 C 语言编写的轻量推理引擎，可以在只有约 25 GB 内存的消费级机器上运行 GLM-5.2——一个 7440 亿参数的混合专家（MoE）大模型。它完全不使用 Python 运行时，不依赖 BLAS 或 GPU，通过磁盘流式加载专家权重将不可能变为可能：仅 9.9 GB 常驻内存，让一台普通电脑跑上前沿级大模型。
项目发布于 2026 年 7 月 10 日，当日登顶 Hacker News榜首（453 点）。
解决什么问题
运行 744B 级别的前沿模型，传统上需要 8×H100 GPU 集群或同等算力，成本极高。Colibrì 另辟蹊径：利用 MoE 模型的稀疏激活特性——每次只激活约 400 亿参数（11 GB 可变专家权重），而密集部分（注意力层、共享专家、嵌入层，约 17B 参数）以 int4 量化形式常驻内存（~9.9 GB），其余 21,504 个路由专家（每个约 19 MB，共 ~370 GB）按需从磁盘流式加载，配合 LRU 缓存实现本地部署。
技术细节一览
Colibrì 的核心工程挑战是 MoE 稀疏激活 + 磁盘流式 的组合：
- DeepSeek-V3 风格 Sigmoid 路由器：无辅助损失、无 top-k 偏置，路由缩放因子补偿；每次 token 激活 8 个专家（75 层 × 256 专家）。
- MLA 注意力（Multi-head Latent Attention）：GLM-5.2 采用 64 头且无 GQA，标准 KV-cache 极大。Colibrì 用压缩 MLA KV-cache（576 floats/token vs 标准 32,768），缩小 57 倍。
- DSA 稀疏注意力：GLM-5.2 自带的 Lightning Indexer，每层 top-2048 因果键选择。Colibrì 精确还原了稠密注意力的输出（token-for-token validated）。
- MTP 推测解码：GLM-5.2 第 78 层的 Multi-Token Prediction head 充当推测解码器。int8 头接受率 39–59%，每 forward 2.2–2.8 tokens。int4 头接受率崩溃至 0–4%（⚠️ 推测功能几乎失效）。
- Batch-union MoE：prefill 和 MTP 验证阶段，同 batch 中每个唯一专家只读一次，应用到所有路由到它的位置。
- Grammar-forced 推测：使用 GBNF 语法文件引导 JSON/NDJSON/函数调用输出，强制 span 内 token 直接接受，无需推测头，接受率 ~1.0。
快速安装
⚠️ 依赖：Linux/macOS/WSL2，需要 AVX2 支持的 x86 CPU，或 Apple Silicon（M 系列）。
# 1. 克隆仓库
git clone https://github.com/JustVugg/colibri.git
cd colibri
# 2. 下载预转换的 GLM-5.2 int4 模型（~370 GB 磁盘空间）
# HuggingFace：https://huggingface.co/jlnsrk/GLM-5.2-colibri-int4
# 或使用官方转换脚本（需要先下载 FP8 原版）
# 转换工具：c/tools/convert_fp8_to_int4.py（分片下载，累积约 756 GB）
# 3. 编译（纯 C，无外部依赖）
make
# 4. 运行
./coli chat
首次运行大约 32 秒启动完成，常驻内存 9.9 GB。
核心用法
交互式对话
./coli chat
› ciao!
带环境变量的高级用法
# 启用 MTP 推测解码（需要 int8 MTP 头，默认已转换好）
DRAFT=1 ./coli chat
# 强制语法引导输出 JSON（使用 GBNF 语法文件）
GRAMMAR=schema.gbnf ./coli chat
# 开启 KV-cache 持久化（聊天重启后无需重新预填充）
./coli serve # serve 模式会自动保存 KV-cache 到 .coli_kv
# 禁用稀疏注意力（DSA）
DSA=0 ./coli chat
# 禁用推测解码
DRAFT=0 ./coli chat
# 实验性：路由预取（当前层计算时预取下层专家）
PILOT=1 ./coli chat
磁盘空间与性能对照
| 指标 | 值 |
|---|---|
| 模型磁盘占用（int4） | ~370 GB |
| 常驻内存 | ~9.9 GB |
| 冷启动速度 | ~0.05–0.1 tok/s |
| M5 Max（ warmed cache） | ~1 tok/s |
| MTP 推测（int8 头） | 2.2–2.8 tok/forward |
| KV cache 每 token | ~182 KB |
典型适用场景
- 本地前沿模型体验：在没有 GPU 的机器上运行 744B 级模型，感受前沿模型行为
- 模型正确性验证：token-exact 验证（已通过 TF32/32 和 greedy 20/20 测试），适合研究 GLM-5.2 架构细节
- JSON/结构化输出：通过 GRAMMAR 参数强制 JSON、NDJSON、函数调用格式，适合工具调用场景
- 低资源研究：课堂教学、模型行为分析、MoE 稀疏激活与缓存策略研究
- 磁盘流式工程实验：研究 LRU 缓存、专家预取、KV-cache 持久化等技术的实际效果
冷 vs 热：性能的真实体验
Colibrì 的性能极度依赖缓存状态：
- 冷启动（cold）：所有专家均未缓存，~0.05–0.1 tok/s，几乎无法实用
- 热专家 + KV 缓存：LLM 推理变为内存带宽受限，接近 M5 Max 的 ~1 tok/s
- MTP 推测（int8 头）：接受率 39–59%，有效 token/forward 提升至 2.2–2.8
这意味着 Colibrì 的实用场景是：持续对话 + 专家缓存 warm。一次性问答几乎无法接受，但多轮对话在 warm 后可达到每秒 1 token 的体验。
坑与注意
- 冷速度极慢：SSD 随机读带宽约 1 GB/s，冷启动每 token 需要读 ~11 GB，冷速仅 0.05–0.1 tok/s。不要期待用它替代正常推理服务。
- 需要大量磁盘空间：模型约 370 GB，需 NVMe SSD（机械硬盘无法实用）。
- AVX2 必需：普通 CPU 不支持 AVX2 指令集则无法运行。
- Windows 原生不兼容：需要在 WSL2 或 Git Bash 环境下运行。
- 推测解码在 int4 MTP 头下无效：作者测量显示 int4 头推测接受率仅 0–4%，需使用 int8 头才能获得 39–59% 接受率。
- 磁盘温度：持续满载读取引擎会加热 SSD，注意监控磁盘健康。
与同类对比
| 项目 | 语言 | 最低内存 | 硬件要求 | 速度 | 特色 |
|---|---|---|---|---|---|
| Colibrì | C | ~25 GB RAM | AVX2 CPU + NVMe | 0.05–1 tok/s | 零依赖、纯磁盘流式、MoE 专用 |
| llama.cpp | C++/C | ~6 GB VRAM | GPU 最好 | 快 | GPU+CPU 混合、量化方案成熟 |
| gptq.cpp | C++ | ~8 GB VRAM | GPU | 快 | GPU 推理 |
| DeepSeek-R1 本地 | vLLM | ~16 GB VRAM | GPU | 快 | 云端推理引擎本地化 |
| MLX（Apple） | C++/Python | ~8 GB RAM | Apple Silicon | 中等 | Apple GPU 优化 |
| Ollama | Go | 依赖模型 | GPU/CPU | 中等 | 简化部署、本地模型管理 |
Colibrì 的核心差异在于完全不依赖 GPU，且针对 MoE 稀疏性做了极致优化——把"磁盘当 VRAM 用"。代价是速度极慢，适合"能跑就行"的场景。与 llama.cpp 的方向完全不同：llama.cpp 追求速度，Colibrì 追求消费级硬件上限。
MLA vs MHA/GQA：为什么 GLM-5.2 的注意力不一样
传统 LLM（Llama、Mistral）使用 Grouped Query Attention（GQA），KV-cache 相对可控。GLM-5.2 使用 Multi-head Latent Attention（MLA），特点：
- 64 个 KV 头（无 GQA 压缩），标准 MLA KV-cache 极大
- Colibrì 通过压缩投影（Q/KV-LoRA）将每 token KV 从 32,768 floats 压缩到 576 floats，缩小 57 倍
- 这也是 Colibrì 能在 25 GB 内存在 GPU-less 环境下跑得动的关键之一
一句话推荐结论
Colibrì 把"花不起 H100 风扇钱"变成"用笔记本电脑跑 744B 前沿模型"的现实——速度很慢，但它是真正的技术奇迹，值得每一个 LLM infra 学习者关注其设计思路。