Colibri

项目概述

colibri 是一款用纯 C 编写的轻量级推理引擎，目标是在普通消费级硬件上运行超大规模开源模型。引擎采用"按需加载专家"策略：MoE 模型虽拥有数千亿参数，但每个 token 实际只激活一小部分，因此 colibri 将常用部分常驻内存，其余专家则按路由需求从磁盘流式读取，无需 GPU 即可运行。

目前共支持十三个引擎：十个语言模型（GLM-5.2/5.3、GLM-5.3-Flash、Inkling、Kimi K3、DeepSeek V4/V4.1 Flash、MiMo-V2.6 Flash/Pro、Qwen3.8-Flash-Next、Qwen3.6、OLMoE）、一个图像生成模型（Qwen-Image-2.1），以及三个决策模型（Laya、GLiNER2.5-Decide、Clef）。

快速启动

最低要求为 8 GB 内存、22 GB 可用磁盘空间以及网络连接，GPU 可选。

Windows：下载 ZIP 并解压，双击 START-HERE.bat 即可。

Linux（Ubuntu/Debian）：

# 安装依赖后克隆仓库并运行一键脚本
sudo apt install git python3 build-essential
git clone https://github.com/JustVugg/colibri
cd colibri
./start-here.sh

macOS（使用 Homebrew）：

xcode-select --install
brew install libomp git python
git clone https://github.com/JustVugg/colibri
cd colibri
./start-here.sh

脚本会自动完成五步流程：检测机器硬件（内存、磁盘、CPU、GPU）→ 推荐匹配模型 → 获取引擎（优先本地编译，否则下载预构建版本；CUDA > Vulkan > CPU）→ 下载模型（支持断点续传）→ 启动服务并打开浏览器面板。

常用参数：

参数	作用
--list	列出所有模型对当前机器的适配情况
--model ID	安装指定模型
--yes	自动接受推荐配置
--dir DIR	将模型存放至其他磁盘
--backend vulkan/cuda/cpu	手动选择引擎后端
--model-dir DIR	使用已下载的模型目录
--reconfigure	切换至其他模型

服务启动后可访问以下地址：

• 浏览器面板：http://127.0.0.1:8000/
• OpenAI 兼容接口：http://127.0.0.1:8000/v1
• Anthropic 兼容接口：http://127.0.0.1:8000

后续启动只需再次运行 START-HERE.bat 或 ./start-here.sh。状态查询使用 c/coli status，停止服务使用 c/coli stop（Windows 下对应 c\coli.cmd）。

核心架构

每个 token 在每一层都遵循 route → union → place → overlap → learn 五步流程。设计原则是权重摆放位置只影响速度，不影响结果：无论专家来自 VRAM、RAM 还是磁盘，路由器决策和权重精度都保持一致。

• 权重的 JIT：借鉴编译器按热度编译热路径的思路，colibri 根据实际路由热度将专家分配到 VRAM、RAM 或磁盘三层存储，并随使用持续学习优化。
• 避免重复磁盘等待：专家的三个矩阵通过单次 pread 读取；加载器在常驻专家计算时预取缺失专家；批量处理时每个专家只读一次；GLM-5.2 的路由在提前一层时可达 71.6% 可预测性，可启用预取线程。
• 多盘并行：COLI_MODEL_MIRROR=/second/glm52_i4 指定第二份模型镜像目录，独立 NVMe 控制器实测可带来约 +37.5% 解码速度提升。
• 从笔记本到机架：25 GB 笔记本上所有专家均从磁盘流式读取；大内存主机可设置 CUDA_EXPERT_GB=auto PIN_GB=all 让全部专家常驻；多插槽主机使用 COLI_NUMA=1 跨内存控制器分布权重。
• 忠实于原模型：每个引擎在 CI 中与参考实现对照验证；GLM-5.2 的 MLA 注意力将每个 token 的 KV 状态压缩至 576 个浮点数（57 倍压缩），重启后对话无需重读提示词。
• 投机解码：GLM-5.2 的 int8 MTP 头可草拟 2.2–2.8 token；Qwen3.8-Flash-Next 的 MTP 头默认开启，带来 16–20% 提速。

引擎代码每个模型族一个 C 文件（如 c/colibri.c 对应 GLM-5.2），共享头文件，不依赖 BLAS，运行时无 Python；Python 仅用于启动器、转换器和 API 网关。

决策接口 System One

多数应用场景需要的不是生成段落，而是结构化决策。POST /v1/systemone 接收状态文本或 JSON 及一组类型化问题，返回每个允许选项的概率与置信度，且不会生成列表外的答案。

curl -s http://127.0.0.1:8000/v1/systemone \
  -H 'Content-Type: application/json' -d '{
    "state": "340 lines, 8 files, no tests. CI is green.",
    "questions": {
      "review": {"type": "choice", "instructions": "What should the reviewer do?",
                 "criteria": {"merge": null, "request changes": null, "close": null}},
      "risky":  {"type": "noul", "instructions": "Is this change risky?"}}}'
# choice 返回所选标签、每标签概率及 0-1 的置信度；noul 返回 yes 概率；score 返回期望等级

支持三种调用方式：任意聊天模型通过评分实现（同一文档的多个问题可一次性处理，在 Qwen3.6 上比逐个生成快 5.7 倍）；三个原生决策模型 Laya、GLiNER2.5-Decide、Clef 单次前向完成。请求与回复格式兼容 TypeSafe 的 Jev API，客户端只需修改 TYPESAFE_BASE_URL=http://127.0.0.1:8000 即可切换。终端中可通过 /decide merge | request changes | close 调用。

多端支持

• CPU：所有引擎默认支持，无需额外组件。
• Vulkan：任意支持 Vulkan 1.2 的 GPU（AMD、Intel、NVIDIA，集成或独立）。提供专家层（GPU 缓存热点专家）与稠密链（整层一次性提交）两种使用模式；集成 GPU 在 Qwen3.6、Qwen3-Coder、Qwen3.8-Flash-Next 上有实测加速。
• CUDA：Linux 下安装 CUDA toolkit 后自动构建；Windows 下作为独立 DLL 发布。新增 Qwen3.6 的 DeltaNet 层 GPU 卸载（Q36_DN_GPU=1），在 RTX 3070 上可达 25.4–30.0 tok/s。
• Metal：macOS 统一内存 GPU 支持 colibri、inkling、kimi_k3；COLI_METAL=1（Kimi K3 使用 K3_METAL=1）开启。

服务与外部应用集成

coli serve 启动的单一服务同时暴露：

• OpenAI 兼容：/v1/chat/completions、/v1/completions、/v1/models，支持流式、JSON、停止序列、logprobs
• Anthropic 兼容：/v1/messages，Claude Code 与 Anthropic SDK 可直接对接
• 工具调用：除 Inkling 与 OLMoE 外的所有聊天引擎均支持
• 图像输入：GLM-5.3-Flash、DeepSeek V4.1 Flash、MiMo-V2.6、Qwen3.8-Flash-Next、Qwen3.8-27B
• 图像输出：Qwen-Image-2.1 通过 POST /v1/images/generations
• 决策接口：POST /v1/systemone
• 多会话并行：coli serve --kv-slots N 最多支持 16 个并发 KV 上下文

编码 CLI 与编辑器作为普通 OpenAI 兼容服务对接即可：base URL http://127.0.0.1:8000/v1，模型 ID 取自 coli status，API key 任意非空字符串。