Colibri 大规模 MoE 模型本地推理引擎部署教程

Colibri 是一个用纯 C 编写的、零依赖的推理引擎，旨在让您能在已有的消费级硬件上运行 744B 到 2.8T 参数的前沿 MoE（混合专家）模型。其核心思想是将存储、RAM 和 VRAM 视为一个统一的推理层级，通过流式加载专家权重，降低了对昂贵硬件的依赖。

本教程将指导您完成 Colibri 的安装、模型获取与运行。

1. 项目概览与核心原理

  • 核心思想：MoE 模型每次推理只激活一小部分参数（如 744B 模型仅激活 ~40B）。Colibri 利用这一点，将庞大的专家参数存储在磁盘上，仅在需要时流式加载到 RAM 或 VRAM，从而大幅降低内存需求。
  • 内存层级：构建了 VRAM → RAM → NVMe 存储 的多级缓存体系。热门的专家会驻留在高速层级，冷门的则留在磁盘，由智能缓存和预取策略管理。
  • 支持模型：目前已支持 GLM-5.2 (744B)、DeepSeek V4 Flash (284B)、Kimi K3 (2.8T)、Qwen3.8-Flash-Next (125B) 等八个模型家族。每个模型对应一个独立的 .c 引擎文件。

2. 环境准备

2.1 硬件要求

  • 存储：至少 400 GB 可用空间（用于 GLM-5.2 模型）。模型越大，所需空间越大（Kimi K3 需 ~1.6 TB）。强烈建议使用高速 NVMe SSD。
  • 内存 (RAM)：最低 16 GB，推荐 24 GB 或更多。内存用于驻留模型的密集部分（Attention 等）和专家缓存。
  • GPU (可选)：非必须，但可以显著加速。支持 NVIDIA (CUDA)、AMD (Vulkan) 和 Apple Silicon (Metal)。

2.2 软件依赖

  • 操作系统：Linux、macOS 或 Windows。
  • Python 3：用于 coli 命令行工具、转换脚本和 API 网关。
  • 编译器 (如需从源码构建)：gcc 或 clang，并支持 OpenMP。

3. 安装 Colibri

您可以选择下载预编译二进制文件（推荐）或从源码构建。

方式一：下载预编译 Release (最简单)

  1. 访问项目的 GitHub Releases 页面。

  2. 下载适用于您操作系统和架构的压缩包（如 colibri-v*.*.*-linux-x86_64.tar.gz）。

  3. 解压到您选择的目录，例如：

    1
    mkdir colibri && tar xzf colibri-v*.tar.gz -C colibri && cd colibri

  4. 验证安装：

    1
    ./coli info

    如果看到引擎版本信息，则安装成功。

方式二：从源码构建

适合开发者或需要自定义编译选项的用户。

  1. 克隆仓库：

    1
    2
    git clone https://github.com/JustVugg/colibri.git
    cd colibri/c

  2. 运行构建脚本（会自动检查编译器并构建）：

    1
    ./setup.sh

  3. （可选）将 coli 命令安装到 PATH：

    1
    2
    # 在仓库根目录下
    pip install -e .

4. 获取并运行模型

4.1 下载预转换模型 (以 GLM-5.2 为例)

官方推荐使用 Hugging Face 上已转换好的 int4 量化 模型容器。

  1. 模型大小：约 372 GB。请确保有足够的磁盘空间。
  2. 下载地址：https://huggingface.co/mastouri/GLM-5.2-colibri-int4-g64-with-int8-mtp
    • 重要：请务必使用此 gs64 版本，它修复了旧版模型的质量问题。同时确认 MTP 头是 int8 版本（文件大小约 3.5GB），而非 int4。
  3. 您可以使用 huggingface-cli 或 git lfs 下载整个模型目录。

4.2 运行模型

使用 coli 命令指定模型路径即可启动交互式对话。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 设置模型路径环境变量
export COLI_MODEL=/path/to/your/GLM-5.2-colibri-int4-g64-with-int8-mtp

# 启动交互式 TUI 聊天
./coli chat

# 查看模型在您硬件上的放置计划
./coli plan

# 运行兼容 OpenAI 的 API 服务器和 Web 仪表盘
./coli web --model $COLI_MODEL

# 仅启动 API 服务器（无浏览器）
./coli serve --model $COLI_MODEL

4.3 针对硬件的调优

  • 内存与缓存：Colibri 会自动探测 RAM 并设置专家缓存大小。您也可以通过 --ram 参数手动指定。

  • 双 SSD 加速：如果您有两块 SSD，可以将模型复制到第二块盘上，让引擎从两块盘同时读取专家数据，叠加带宽。设置环境变量：

    1
    2
    3
    export COLI_MODEL=/path/to/primary/model
    export COLI_MODEL_MIRROR=/path/to/second/model
    ./coli chat

  • O_DIRECT 选项：在某些高速 NVMe 上，绕过操作系统页缓存能提升性能。尝试设置环境变量 export DIRECT=1。此选项对硬盘性能有依赖，请自行测试。

5. 其他支持模型

Colibri 支持多种模型，构建对应的引擎后，使用同样的 coli chat/serve/web 命令，只需更改 COLI_MODEL 路径。

模型 参数规模 磁盘占用 构建命令 (在 c/ 目录下)
GLM-5.2 744B ~372 GB make glm
DeepSeek V4 Flash 284B ~167 GB make deepseek-v4
Kimi K3 2.8T ~1.6 TB make kimi_k3
Qwen3.6-35B-A3B 35B ~20 GB make qwen36
OLMoE 7B ~7 GB make olmoe

6. 性能预期与基准

性能高度依赖于您的硬件（SSD 速度、内存大小、CPU 核心数、GPU 能力）。

  • 顶级配置 (6× RTX 5090，模型全驻留 VRAM)：解码速度可达 5.8–6.8 tokens/秒。
  • 中端配置 (128 GB RAM CPU 主机)：热身（缓存命中）后约 1.8 tokens/秒。
  • 入门配置 (单 RTX 5070 Ti)：GPU 驻留管线约 1.07 tokens/秒。
  • 最低配置 (25 GB RAM 笔记本)：纯冷启动约 0.05–0.1 tokens/秒，这是该项目证明可行性的起点。

重要提示：速度是受限于您的存储和内存层级的，尤其是在冷启动（专家缓存未命中）时。模型会随着您的使用，通过学习路由模式自动将热门专家固定到高速缓存中，从而越用越快。

7. 常见问题与排查

问题 可能原因与解决方案
coli 命令找不到 未将 coli 所在目录添加到 PATH，或未从解压目录执行。请使用 ./coli 或添加目录到 PATH。
启动时报错 “Model not found” COLI_MODEL 环境变量未设置或路径错误。请确保指向包含 config.json 和权重文件的模型目录。
推理速度极慢 (<0.1 tok/s) 属于冷启动正常现象。耐心等待模型预热。若持续缓慢，检查 SSD 读取速度，并确保有足够 RAM 用于专家缓存。尝试使用 --ram 分配更多内存给缓存。
内存不足 (OOM) 错误 模型所需内存超过物理 RAM。减少缓存大小：./coli chat --cap 2（将每层专家缓存数减为2），但会降低速度。
Windows 下运行失败 确保使用 Release 提供的 coli.cmd 启动。从源码构建需在 MSYS2 环境下。参考 docs/windows.md。
CUDA GPU 未被使用 确认已构建 CUDA 后端 (make cuda)。且模型需以 COLI_CUDA_EXPERT_GB=N 或 auto 指定 VRAM 专家缓存大小。

通过以上步骤，您已经成功部署了 Colibri 推理引擎，并能够在本地硬件上运行超大规模的 MoE 模型。这是一个前沿的、不断发展的项目，欢迎通过运行测试、提交 Issue 或加入 Discord 社区来贡献您的一份力量。