colibri

colibri 快速入门

「小引擎，大模型」——colibri（JustVugg/colibri）是纯 C、零第三方依赖的 MoE 推理引擎：专家权重不驻留显存，而是按需从磁盘流式读取，在 VRAM/RAM/SSD 三层之间调度，让一张卡、甚至没有 GPU 的纯内存机器也能跑 GLM-5.2（744B MoE int4）级前沿模型。Apache-2.0，2026-09-22 核验：GitHub 36.7k★ / 3.9k fork，2,438 commits，最近提交 8 小时前。

这是什么？适合谁？

colibri（意大利语「蜂鸟」，CLI 名为 coli）解决的是「前沿 MoE 模型太大、我的机器装不下」的问题：MoE 模型每次推理只激活少数专家，colibri 利用这一点把未激活的专家留在磁盘上、激活时才读入，用顺序 I/O 换显存容量——官方演示在 CPU 上 32 秒就绪、常驻内存约 9.9 GB 跑 GLM-5.2 744B int4。引擎为每个模型家族（GLM、Qwen、OLMoE、DeepSeek、Kimi 等）各写一个 C 文件，共享 coli chat / coli serve / coli web 前端。它同时是一个开放的推理侧研究平台（内存层级、存储 I/O、调度、推测解码等）。

适合人群：

• 本地推理玩家：消费级硬件想跑前沿 MoE 大模型
• 边缘/低成本部署：无 GPU 或小显存服务器的 LLM 推理
• 推理引擎研究者：一个可读的、零依赖的 C 代码基线（743 个 Python 测试 + C 测试）

不适合谁：追求峰值吞吐的生产服务（vLLM/SGLang 的 GPU 批处理路线更优）；只想用 API 不想碰底层的用户。

准备工作

• 运行环境：Linux/macOS/Windows（Makefile 跨平台，Windows 有 mingw 构建路径与文档 docs/windows.md）；GPU 可选（CUDA/HIP/Metal 后端，CPU 是一等公民）
• 账号要求：无需账号；模型权重从 HuggingFace 拉取或用官方转换器从 transformers checkpoint 转换
• 磁盘：一块顺序读快的 SSD（NVMe 最佳）——专家流式读取的性能直接取决于盘速；支持双盘镜像（COLI_MODEL_MIRROR）叠加带宽
• 依赖：核心引擎零依赖（纯 C）；Python 包装与转换工具需要 numpy/huggingface_hub（pip install -e ".[convert]"）
• 时间预算：clone + pip install -e . 约 5-10 分钟；首次转换并下载模型权重视网络与盘速 30 分钟到数小时

快速上手

第一步：安装

git clone https://github.com/JustVugg/colibri.git
cd colibri
pip install -e .            # CLI（coli）+ serve，无重依赖
# 需要转换器再加：pip install -e ".[convert]"

（也可 pip install colibri-engine 用打包版；Docker 有官方镜像，含 115MB 的 slim 多阶段构建。）

第二步：跑通第一次对话

./coli chat
#   🐦 colibri v1.12.0 — GLM-5.2 · 744B MoE · int4 · streaming CPU
#   ✓ ready in 32s · resident 9.9 GB
#   › ciao!

首启会自动定位/转换模型权重（COLI_MODEL 指向本地路径），就绪后进入交互对话。

第三步：起 OpenAI 兼容服务或 Web 面板

./coli serve                # OpenAI 兼容端点，供任意客户端接入
./coli web                  # 1.12.0 重设计的 Web Dashboard：对话 + Brain 页 + Profiling

预期产出：终端对话 / OpenAI 兼容 API / 带「Brain（专家路由可视化）」与性能剖析页的本地 Web 面板。

进阶：coli convert 从 transformers checkpoint 转换权重；COLI_MODEL_MIRROR=/second/glm52_i4 配置第二块盘做专家分流镜像（启动时校验，部分镜像也有效）；./coli cluster coordinator/worker 做多机专家分布。

常见踩坑

1. 机械盘/慢 SSD 性能崩塌：专家按需从盘上读，HDD 随机读会毁掉体验。→ 上 NVMe，或用镜像盘叠加带宽。
2. 首次就绪时间长不代表慢：启动含权重视检/预热（官方演示 32 秒），后续对话是流式的；用 Brain/Profiling 页看真实路由与瓶颈。
3. Windows 构建走 mingw 路径：deepseek_v41 等引擎曾因 <sys/resource.h> 在 Windows 编译失败、后在 docker 镜像修复——遇编译报错先升级到最新版再看 docs/windows.md。
4. 转换器拒绝某 checkpoint：转换器会「拒绝它无法正确放置的张量」（如 2.4T 检查点的 mtp/visual 头会被有意跳过并说明原因），这是防错设计不是 bug；按提示用支持的家族/几何。
5. GPU 后端别想当然：HIP/Metal 后端有明确的能力边界（如 Windows HIP 目前是 dense 张量上 GPU、路由专家仍在 CPU），看 GPU_BACKENDS.md 的实测说明再选型。
6. RAM 也要够：常驻内存 ≈ 激活层+共享权重（演示值 9.9 GB），但转换缓存与 KV cache 另算；256k 长上下文的 KV 开销可达数十 GB（引擎 planner 会预估）。

常见问题 FAQ

Q1：与 llama.cpp 有什么区别？

A：llama.cpp 是通用 GGUF 推理引擎（全模型驻留内存路线）；colibri 专攻 MoE 专家流式读取（磁盘→RAM→VRAM 分层），目标是在小内存机器上跑「本来装不下」的前沿 MoE。两者侧重不同，llama.cpp 生态与格式支持更广。

Q2：支持哪些模型？

A：每个家族一个 C 引擎：GLM-5.2、Qwen3.x/3.8（含 2.4T 检查点的转换支持）、OLMoE、DeepSeek v4/v4.1、Kimi 等；以仓库 README「Full roster」当日清单为准。

Q3：没有 GPU 真能跑 744B？

A：官方演示即纯 CPU（744B MoE int4，常驻 9.9 GB，就绪 32 秒）——MoE 稀疏激活 + 磁盘流式是关键；吞吐取决于盘速与内存带宽，本文未实测具体 tok/s。

Q4：能接 OpenAI 客户端吗？

A：能，coli serve 提供 OpenAI 兼容端点；另有 Tauri 桌面壳与 Web Dashboard。

Q5：商用电什么许可？

A：Apache-2.0（2026-09 补齐了版权人署名与 NOTICE 文件）。

权限、安全、成本与限制

• 许可：Apache-2.0 + NOTICE。
• 安全：coli serve 绑定地址注意不要暴露公网；模型权重来源自 HuggingFace，自行核对其许可。
• 成本：软件免费；硬件成本主要是大容量 NVMe（对比装下整个 744B 所需的显存/内存，这是数量级的节省）。
• 限制：主打 MoE 流式路线，密集模型与峰值吞吐场景非其强项；各 GPU 后端能力边界不同；本文基于官方 README/文档撰写，未在本机实测性能数字。

小技巧

1. COLI_MODEL 与 COLI_MODEL_MIRROR 指向两块盘，专家按带宽加权分流，9GB/s+3GB/s 双盘比单快盘再快约 33%（官方文档实测口径）。
2. coli mirror plan --budget-gib 200 可以按预算规划部分镜像——小盘只放部分 shard 也有效。
3. Web Dashboard 的 Brain 页可看「活体路由」（模型运行时专家激活的实时可视化），调优盘/内存配比前先看它。
4. coli 的 Brio 模式（1.12.0 新增独立端点）适合「给文档、只要受限答案」的场景，如分类/判题。
5. 想读懂引擎：每个模型家族就是一个 C 文件，配合 docs/ 下的 Brain/Profiling/架构页，是学 MoE 推理内核的干净教材。

进阶学习方向

• 多机专家分布：coli cluster coordinator/worker 把专家分片到多台 worker，dense 层与浏览器/WebGPU worker 是后续接缝（官方 README 口径）。
• 推理侧研究平台：仓库 CONTRIBUTING 与 experiments 目录维护可复现的性能记录，适合做存储/调度方向的实验基线。
• GPU 后端矩阵：GPU_BACKENDS.md 记录 CUDA/HIP/Metal 各自的实测边界与构建方法，选型前必读。
• Windows 路径：docs/windows.md 有完整的 mingw/MSVC 构建说明（含 HIP DLL 运行时选择）。

参考链接

• 官方仓库
• 项目站点
• GPU 后端说明
• CHANGELOG
• PyPI colibri-engine