它是干什么的:一句话定位 + 为什么最近火

JustVugg/colibri 把自己定位写得很直白——Tiny engine, immense model. 翻译过来就是:引擎只有几百 KB,模型却能跑 744B 到 2.8T。Apache-2.0 协议,GitHub 仓库 JustVugg/colibri,截至 2026-09-10 总星 27,300,今日新增 +2,249(GitHub Trending Python 类日榜第 7,本周累计涨星 +11,200+)、fork 2,998、活跃 issue 113,主语言 C(99%),作者是此前没有公开项目记录的独立开发者 JustVugg。

它真正要干的事,跟我们以前写过的所有"本地跑大模型"项目都不一样:

  • vLLM / SGLang / TensorRT-LLM:追吞吐上限,要 A100/H100,个人玩家基本无缘;
  • llama.cpp:在 CPU 上跑稠密小模型(7B-70B),量化做得好但装不进 MoE 巨兽;
  • kTransformers:已经能把 DeepSeek-V3 这种 671B MoE 塞进 24GB 显卡 + 1TB 内存;
  • colibri:不要 GPU 也能起,目标是把 744B GLM-5.2 塞进 25GB 内存的笔记本,代价是冷启动只有 0.05 tok/s。

读到这里你大概会问一句"那不慢死了还跑啥"?这是 colibri 设计哲学里最值得讲的一段。开发者 JustVugg 在 README 第一段就写:“This is not fast. Experiments must earn their place through reproducible end-to-end measurements, and the default policy never silently changes model precision or router semantics.” 翻译:速度不是它的卖点,可复现、可验证、不偷偷改模型精度才是。 换句话说——它把"能不能在普通机器上正确回答"这件事做成了 1,反对照基线是 0。

为什么 9 月初这股风把它顶到 Trending 头部:

  • MoE 本地化"第二波"叙事——4 月 kTransformers 上线时被科普过一遍,这次 colibri 走的是另一条路:纯 C、零运行时依赖、磁盘当显存分层用,比 Python 栈的方案更极端,代码量只有 ~2,400 行(README 末附仓库结构里每个 .c 一个模型家族)。
  • 多模型支持矩阵一次铺开——README 里直接列出 8 个家族:GLM-5.2/5.3(744B)、GLM-5.3-Flash(321B,带视觉)、Inkling(975B)、Kimi K3(2.8T)、DeepSeek V4 Flash(284B)、Qwen3.8-Flash-Next(125B+51B n-gram)、Qwen3.6(35B-A3B)、OLMoE(7B)。其中 Inkling 是 Thinking Machines 的 975B,Kimi K3 是月之暗面的 2.8T——都是当下最热的开源旗舰。
  • 作者站得住——OpenAI 兼容 API、Web 仪表盘、专家路由实时可视化(把 19,456 个专家画成可交互的"大脑皮层")、MLA 压缩 KV 状态 57 倍、MTP 投机解码默认开、双 SSD 镜像分摊磁盘带宽……一堆工程细节做完整了,不是 demo。
  • 新浪/网易/CSDN 中文圈二轮传播——本周 CSDN 多篇博客把它解读成"2400 行 C 代码造奇迹",自然带来增星(参考链接里给出 CSDN/网易/新浪 3 条报道)。

核心功能:MoE + 磁盘 + C,一个组合把"装不下"拆成"分时分层"

colibri 的功能不是某个单点技巧,而是一整套把"硬件装不下"换成"硬件按需加载"的工程栈。下面按 README 顺序逐层拆。

1. 硬件装不下?那就别装,把 VRAM/RAM/NVMe 当成一层来用

MoE(Mixture of Experts)的核心特性就是"每 token 只激活一小撮专家"。以 GLM-5.2 为例:

  • 总参数 744B,75 个 MoE 层,每层 256 个路由专家 + 1 个共享专家;
  • 每 token 实际激活约 40B 参数(5.4%),其中真正"会随 token 变化"的路由专家加起来约 11 GB;
  • 稠密部分(注意力层、共享专家、嵌入层)只占约 17B,int4 量化后常驻内存 ~9.9 GB。

colibri 据此把模型切成 三层:

层级存什么容量代价速度
VRAM(可选)当前轮热专家 + 残差流看卡大小最快
RAM(必选)稠密部分 int4(~9.9 GB)+ LRU 专家缓存16 GB 起步中等
NVMe(必选)19,456 个 int4 专家,合计 ~370 GB看磁盘大小最慢但确定可用

模型文件大小约 372 GB,所以最小磁盘就是 400 GB NVMe,文件系统 ext4,网络存储不行——README 里专门写过这一句。

这层的核心概念叫 “JIT for weights”:编译器 JIT 不编译整个程序,只编译热路径;colibri 不预装整个模型,只装路由证明你需要的专家。用得越多,专家越热,引擎越快(.coli_usage 会记录你的路由热度)。

2. 路由热度的三层调度:LRU + 学习置顶 + 下一层预读

光把磁盘当显存不够,还要知道从盘上读哪一段。colibri 用的是 3 个协同机制:

  • 每层 LRU 缓存——和操作系统页面置换算法一样,最近路由到的专家留在内存;
  • 学习置顶 hot-store——.coli_usage 每轮更新,记录"你这台机器上哪些专家被反复路由",自动 pin;
  • 下一层预读(pilot lookahead)——README 测得路由在下一层的可预测性是 71.6%,所以可以在算当前层的同时把下一层可能要的专家异步读到内存。

测试数据(来自 README 与 docs/benchmarks.md):

  • 6× RTX 5090 满驻留:5.8-6.8 tok/s 解码,TTFT ~13 秒;
  • 128 GB CPU-only 桌面:warm 状态 ~1.8 tok/s;
  • 单 RTX 5070 Ti 笔记本级 GPU:走 GPU-resident pipeline,1.07 tok/s;
  • 25 GB 开发机冷启动:0.05-0.1 tok/s,这是它起步的"诚实底线"。

3. 双 SSD 镜像:把第二块盘当带宽,不当中转

decode 阶段多数情况被磁盘带宽卡死。colibri 的解法很工程化:

1
2
3

COLI_MODEL=/fast/glm52_i4 \
COLI_MODEL_MIRROR=/second/glm52_i4 \
./coli chat

第二个路径就是第二块 SSD 上的同一份模型。两份通过 hash + 带宽比确定性分摊,绝不是冗余存储——专家只读不写,读哪块盘是确定的,所以 readahead 和需求读永远命中同一块。

9 GB/s + 3 GB/s 两条线实测能把专家读速提高约 33%(README 测得)。更狠的是:第二块盘可以装不下完整模型——./c/coli mirror plan --budget-gib 200 会按 .coli_usage 热度挑最重要的分片放进去,只放 200 GB 也能提速。

镜像的工程细节我比较佩服这几点:

  • 启动时校验字节一致(safetensors header + 文件大小),不一致静默回落到主盘,所以半镜像也行;
  • 永不写镜像盘——.coli_usage、.coli_kv 全在主盘;
  • 运行中拔盘不崩——读镜像出错就回主盘,只一个 warning。

4. KV 状态压缩 57 倍 + 跨重启热对话

GLM-5.2 用的是 MLA(Multi-head Latent Attention),colibri 把 KV 状态从 32,768 浮点/token 压到 576 浮点/token,压缩率 57×。效果直接体现在对话恢复上:

  • .coli_kv 持久化在磁盘,重启后对话热启动,0 重新预填充;
  • 字节级别和未中断的会话一致——CI 里就有这个测试。

对做长 agent 会话的人这是救命功能(想想看 DeepSeek V4 Flash 的 prefix checkpoint 也是同一思路,只是放 RAM 还是磁盘的差别)。

5. MTP 投机解码 + 语法强制草稿

GLM-5.2 自带 MTP(Multi-Token Prediction)头,colibri 用它来"先猜 2-4 个 token,主模型一次性 verify"——

  • int8 MTP 头(README 警告:必须是 int8,int4 接受率会掉到 0-4%,见 #8)
  • 一次 forward 产出 2.2-2.8 个 token(接受率 39-59%)
  • 语法强制草稿(GRAMMAR=file.gbnf)——给 JSON 这类结构化输出加几乎免费的接受率

但作者也诚实地写了:投机不是默认赢的——MTP 在 85% 专家命中率附近测过 32% 收益损失(README 表格里给的)。所以 DRAFT=0 是一个真实的开关,不是占位。

6. 8 个家族一个 CLI,coli 帮你挑引擎

最妙的设计是这个——coli 是个 launcher,读 config.json 决定调用哪个 .c 引擎。换模型命令一行不变:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

make -C c glm         # GLM-5.2/5.3 引擎
make -C c inkling     # Inkling 引擎
make -C c kimi_k3     # Kimi K3 引擎
make -C c deepseek-v4 # DeepSeek V4 Flash
make -C c qwen38      # Qwen3.8-Flash-Next(CPU only)
make -C c qwen36      # Qwen3.6
make -C c olmoe       # OLMoE

COLI_MODEL=/nvme/glm52_i4     ./coli chat
COLI_MODEL=/nvme/kimi_k3_i4   ./coli chat

OpenAI 兼容 API(./coli serve)和 Web 仪表盘(./coli web,带专家路由热力图、吞吐、TTFT、bytes 读盘、KV slots)也是同一套入口。意味着:

  • Claude Code / Codex / Cursor 的 OpenAI provider 直连——base URL 指到 http://你机器:8000/v1,模型名随便写;
  • Cherry Studio / Open WebUI / NextChat 这类客户端也能直接接;
  • 不用改任何代码就能用本地模型——这就是 OpenAI 兼容最大的价值。

7. Vulkan 后端让被厂商遗弃的显卡续命

这一条单独拎出来讲,因为它直接命中"个人服务器玩家"的痛点:

  • AMD RX 580——ROCm 不支持了,但 Mesa/RADV + Vulkan 1.2 能跑;
  • RDNA4——Vulkan 路径甚至和 ROCm 打了个有来有回(见 docs/vulkan.md);
  • 任意带 Vulkan 1.2 的 GPU 都能进 expert tier、dense projection、MLA 注意力。

加上 Metal(Apple Silicon 统一内存 GPU)、CUDA(NVIDIA 全家),6 个后端共用一个运行时——意味着你这台机器怎么升级、colibri 都跟得上。

8. 集群模式:多台 Mac/PC 拼一台

如果你有两台同型号笔记本,colibri 提供 cluster coordinator/worker 模式:

1
2
3
4
5
6
7
8

# 协调机
./coli cluster coordinator --host 0.0.0.0 --port 8765
# 工作机
./coli cluster worker --model /nvme/glm52_i4 --port 9100 \
  --coordinator http://COORDINATOR:8765 --advertise-host WORKER_IP
# 启动带集群的服务
./coli serve --model /nvme/glm52_i4 \
  --cluster-coordinator http://127.0.0.1:8765

关键设计:一次性的 TCP 批量请求(per-layer batch-union)而不是 per-expert round-trip——这意味着网络延迟不是线性叠加,而是按"层"叠加。几个 mac mini 拼一台家用机,这是 colibri 给出的解法。

怎么用起来:三步,把"前沿模型"请到笔记本上

我们站点的服务器只有 1.6GB 内存(在《1.6GB 内存能跑哪些服务里讲过现状),本文按 README 推荐的最低 16GB / 25GB / 32GB 写,不在本机实测——理由同 9 月 8 日的 hyperframes 那篇:项目最低门槛超过本站硬件,按"项目太大不硬凑"的规则,本文以官方 README 与 docs/ 为准。

第一步:拿引擎(几百 KB)

下载预编译版最快:

1
2

mkdir colibri && tar xzf colibri-v1.10.2-linux-x86_64.tar.gz -C colibri && cd colibri
python3 coli info    # 引擎就绪 ✓

源码编译也行,只需要 gcc/clang + OpenMP:

1
2

git clone https://github.com/JustVugg/colibri && cd colibri/c
./setup.sh          # 自检 + 构建 + 自测

第二步:拿模型(关键步骤,按家族选)

以 GLM-5.2 为例(744B int4,约 372 GB):

1
2
3
4
5

# 直接下预转换好的 int4 容器(推荐 gs64 版本)
# https://huggingface.co/mastouri/GLM-5.2-colibri-int4-g64-with-int8-mtp

# 或从 FP8 自己转(shard by shard,不需 756 GB 中转)
./coli convert --model /nvme/glm52_i4

避坑提示:README 里专门警告过——用 gs64 容器,别用老版本的 per-row int4 镜像(mateogrgic/...、jlnsrk/...)——后者量化质量差约 9pp,#455 里的"思维链死循环"就是它引起的。

每个家族的"硬件需求一览表"我抄一份给你对照:

模型权重磁盘RAMGPU
OLMoE(7B)~7 GB8 GB不要
Qwen3.6(35B-A3B)~20 GB24 GB(需全 RAM 驻留)可选,2×8GB 测得 1.44→10.05 tok/s
DeepSeek V4 Flash(284B)~167 GB16 GB 起步 / 32 GB 舒适可选,Pascal/Turing 起
Qwen3.8-Flash-Next(125B+51B n-gram)~185 GB16 GB 起步不支持,CPU only
GLM-5.3-Flash(321B)~195 GB25 GB不要
GLM-5.2/5.3(744B)~372 GB16 GB 起步 / 24 GB 舒适不要
Inkling(975B)~469 GB25 GB(int4 dense) / 120 GB(全 BF16)不要
Kimi K3(2.8T)~1.6 TB32 GB+不要

第三步:跑起来 + 上 API

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# TUI
COLI_MODEL=/nvme/glm52_i4 ./coli chat

# 资源体检 + 自动规划
COLI_MODEL=/nvme/glm52_i4 ./coli doctor --deep
COLI_MODEL=/nvme/glm52_i4 ./coli plan
COLI_MODEL=/nvme/glm52_i4 ./coli tune    # 测你这台机器的最优配置

# 启 OpenAI 兼容 API + Web 仪表盘
./coli serve --model /nvme/glm52_i4      # headless
./coli web  --model /nvme/glm52_i4      # 自动开浏览器

启动后能看到:

  • API 文档:/v1/models、/v1/chat/completions、/v1/completions、/v1/embeddings(按模型能力裁剪)
  • Web 仪表盘:实时 token/s、TTFT、硬件 tier bar、专家路由热力图
  • 路由"大脑"视图:19,456 个专家画成皮层,每个被路由过的专家会"闪一下"

如果接 Claude Code,在 ~/.claude/settings.json 里加:

1
2
3
4
5
6
7

{
  "providers": [{
    "name": "colibri-local",
    "baseURL": "http://你的机器:8000/v1",
    "apiKey": "any-non-empty-string"
  }]
}

模型名随便写——colibri 的 /v1/models 返回你 COLI_MODEL 路径对应的家族。

和同类比亮点在哪 / 适合谁用

维度colibrivLLMllama.cppkTransformers
目标硬件消费级 RAM + NVMe,可不要 GPUA100/H100 起步CPU/单卡,小模型24GB 显卡 + 1TB RAM
模型规模744B-2.8T MoE任意7B-70B 稠密为主671B MoE
语言/依赖纯 C,~2,400 行,运行时零依赖Python + CUDAC++ + Metal/CUDAPython + CUDA
速度(同硬件)慢,0.05-6.8 tok/s 区间最快中等中等
多模型支持8 个 MoE 家族,统一 CLI任意任意2-3 个
KV 压缩MLA 57×否否部分
OpenAI 兼容是是是(社区)是
集群模式内置 coordinator/worker有无无
视觉/多模态GLM-5.3-Flash 支持是有限有限
协议Apache-2.0Apache-2.0MITApache-2.0

colibri 的独占位:

  1. 唯一支持 2.8T Kimi K3 的纯 CPU 路径——这是月之暗面的旗舰,1.6TB 权重 + 32GB RAM 起步。
  2. 唯一"不要 GPU 也能跑 744B"的现代方案——vLLM / kTransformers 都得有大显存。
  3. 唯一磁盘 = 第三层显存的工程实现——vLLM/llama.cpp 是把模型硬塞进显存,缺货时只能降精度或换模型。

它不适合谁:

  • 想要"秒回"的人——colibri 是研究/学习/Agent 离线后端,不适合对话产品;
  • 想要生产级吞吐的人——TTFT 在大模型上还是十几秒到几十秒,达不到 SaaS SLA;
  • 想要小模型快速方案的人——7B-70B 直接 llama.cpp / Ollama 更划算。

适合谁:

  • 个人 AI 玩家——想在自建机器上"持有一个 744B 模型而不是租用 API",colibri 是当下唯一选项;
  • 学术 / 算法研究者——想拆解 MoE 路由热力、KV 压缩、投机解码边界,colibri 把每条路径都暴露成 issue + 实验记录(README 里那张"Open hypotheses"表就是研究清单);
  • Agent 工具作者——想把 Claude Code / Codex 接本地模型,但不愿意买 A100;
  • 多机拼算力的"穷人机房"——几台二手服务器或 mac mini 用集群模式拼一台。

我的判断:现在就该上 / 再等等 / 别碰

现在就上:

  • 你手上有一台 32GB RAM + 500GB NVMe 的闲置笔记本/台式机,想跑 GLM-5.2/5.3-Flash 这种开源旗舰尝鲜;
  • 你是 Claude Code / Codex / Cursor 重度用户,想给它们接一个完全本地、不出网、不限量的后端(尤其在国内 API 通道不稳定的场景);
  • 你是 MoE 推理研究者,想做路由热力、KV 压缩、投机解码的实验;
  • 你有 2 块 NVMe 想拼带宽,可以白嫖双 SSD 镜像方案。

再等等:

  • 你想用 GLM-5.3-Flash 的视觉能力接图像问答——文档 docs/glm53-flash.md 还有更细的视觉路径,等官方 release notes 更新稳定再说;
  • 你的机器只有 16GB RAM 但想跑 744B——冷启动 0.05 tok/s 是个"能跑"但"不能对话"的边界,24GB 以上才是舒适区;
  • Vulkan 后端你看着眼馋但显卡是 RDNA3 之前的——docs/vulkan.md 标注了实际覆盖范围,先看自己卡在不在里面。

别碰:

  • 你需要生产级 QPS / SLA——colibri 是研究型引擎,没有 SLA 是它自己写的承诺;
  • 你的磁盘是 HDD 或低速 SSD——专家按需读取会直接饿死 decode,NVMe 是硬门槛;
  • 你想跑 7B-70B 稠密模型日常对话——llama.cpp / Ollama 在你硬件上会快 10-100 倍;
  • 你的模型不是它支持的 8 个家族——目前 list 是封闭的,新模型需要走"测通一个才能加一个"的社区流程(README “What’s next” 里写了 MiniMax 在候选名单上,意味着它还没测过自家模型)。

一句话总结

colibri 用 2,400 行 C 代码和"磁盘当显存分层"的工程直觉,把"前沿大模型 = 大 GPU 集群"的预设拆了——速度不是它的卖点,降低硬件门槛才是。在你愿意拿时间换算力、想本地"持有"一个 744B 模型、或者想让 Agent 工具完全离线后端时,这是 2026 年开源社区给出的最有诚意的答案。

站内互链

参考链接

顺带一提:把旧笔记本榨干之前,先看看桌面还缺什么——极客桌面 2000 元整套是入门全景单。

本文由拾光札记编辑部整理,勘误请联系我们。