colibri：纯C把744B至2.8T MoE跑在本地硬件上
一个用纯C把744B至2.8T MoE跑在本地硬件上的推理引擎，专家从磁盘流入而非全塞进显存。
GitHub JustVugg/colibri 更新 2026-09-11 分支 main 星标 27.5K 分叉 3.0K
C 本地大模型推理 MoE GLM-5.2 消费级GPU与异构硬件

🧭 决策指南

为什么现在热： README展示了在6× RTX 5090上运行744B GLM-5.2、在128 GB CPU-only桌面达到约1.8 tok/s，并支持744B至2.8T MoE；结合最新版本colibri 1.10.2和当日新增98颗星，这些“消费级或异构硬件运行前沿大模型”的实测信号很可能推动了关注，但材料无法证明具体因果关系。

适合，如果你

  • 你有372 GB磁盘并想运行GLM-5.2 int4，而不是依赖全量显存。
    README“Get started”写明程序仅几百KB、模型约372 GB；“How it works”说明VRAM、RAM和storage组成单一推理层级。
  • 你有128 GB RAM的CPU-only桌面，能接受约1.8 tok/s warm的GLM-5.2表现。
    README“ What it achieves”列出128 GB CPU-only desktop约1.8 tok/s warm。
  • 你有单张RTX 5070 Ti，并希望测试GPU-resident pipeline运行GLM-5.2。
    README基准列出single RTX 5070 Ti laptop-class box达到1.07 tok/s。
  • 你在研究MoE专家放置、存储I/O或CPU/GPU overlap，而不是只需要固定速度SLA。
    README产品说明将model formats、memory hierarchy、storage I/O、placement、scheduling、kernels和CPU/GPU overlap列为研究目标，并明确没有speed SLA。

不适合，如果你

  • 你的部署不能容纳GLM-5.2约372 GB模型，或不能接受25 GB机器0.05–0.1 tok/s cold的速度。
    README“Get started”和“What it achieves”分别给出372 GB模型大小及25 GB dev box基准。
  • 你要求模型推理具备明确的速度SLA，而不是接受硬件改变专家驻留位置。
    README“Faithful model, compressed state”前的说明明确写着“no SLA on speed”。
  • 你只有旧的per-row int4 GLM-5.2镜像，且不愿重新获取gs64容器。
    README警告旧镜像质量约低9pp，并与think-mode loops和never-terminating generations相关。
  • 你计划运行Kimi K3但磁盘不足约1.6 TB。
    README“Kimi K3”说明其从原始checkpoint流式读取MXFP4 experts，但snapshot约1.6 TB。

前置条件

  • 需要“the program（a few hundred KB）”和“the model（372 GB）”。
  • GLM-5.2应使用Hugging Face的gs64 int4容器，并配合int8 MTP head。
  • 运行时引擎是pure C；Python只用于one-time converter和optional API gateway。
  • Inkling的RAM-tight host需要int4 dense container和小expert cache；默认--cap 8约需额外14 GB cache。
  • Kimi K3不需要转换，但原始checkpoint snapshot约1.6 TB。

第一步命令（README 原文）

./coli convert --model /nvme/glm52_i4     # download+convert shard by shard (python, one-time)

要注意

  • 不要把GLM-5.2的旧per-row int4镜像当作gs64容器使用。
    README指出旧镜像约低9pp，并是原始think-mode loops和never-terminating generations的根因。
  • MTP head必须是int8而不是int4，否则draft acceptance为0%。
    README“Get the model”明确写出int4 → 0% draft acceptance，并给出ls -l /out-mtp-*检查方式。
  • Inkling默认--cap 8在RAM紧张主机上可能额外需要约14 GB cache。
    README模型差异说明写明default --cap 8 wants ~14 GB of cache on top of the resident set。
  • 不要直接启动.exe引擎期待加载模型；它们不是launcher，会立即退出。
    README Windows说明指出.exe files are the engines, not the launcher。

替代方案

  • transformers：如果你优先需要README中作为teacher-forcing oracle的Python模型栈，而不是纯C、磁盘流式专家推理。
    README“Faithful model, compressed state”；通用领域知识

材料未说明

  • README未提供各平台的最低操作系统、编译器和CUDA版本要求。
  • README未给出不同模型的完整显存、内存和磁盘最低配置表。
  • README未说明coli serve或coli web的认证、并发控制和生产部署安全边界。
  • README未给出与常见推理引擎的统一吞吐、延迟和质量对比。
  • README未说明Windows、Linux和macOS之间的完整性能差异。
  • README未提供Apache License 2.0下模型权重、Hugging Face容器和商业使用的额外限制说明。

💡 深度解析

6
适合 我想在 RAM 紧张的机器上运行 Inkling 975B int4；如果默认专家缓存会额外占约 14 GB，我应该选择 Colibrì 吗？
适合读者： RAM 紧张、希望运行 Inkling 975B int4 的本地推理用户

适合，但必须使用较小的专家缓存配置；README 已明确记录 Inkling 在 RAM 紧张设备上的专门运行方式。

  • 项目支持 975B 的 Inkling，并使用与其他模型相同的 coli chat、coli serve 和 coli web 入口。
  • README 指出 RAM 紧张时应使用 int4 dense container 和小专家缓存；默认 --cap 8 会在 resident set 之外额外需要约 14 GB cache。
  • 给出的直接命令是 ./coli chat --model /nvme/inkling_i4 --cap 2，这比依赖默认缓存更符合该硬件约束。
  • 专家缓存变小可能增加从磁盘重新加载的次数；项目整体也明确表示快速内存不足会降低速度，而不应静默改变模型语义。
  • Supported models: “Inkling (975B)”
  • Per-model notes: “Inkling on a RAM-tight host needs the int4 dense container and a small expert cache”
  • Per-model notes: “the default --cap 8 wants ~14 GB of cache on top of the resident set”
  • Per-model command: “./coli chat --model /nvme/inkling_i4 --cap 2”
./coli chat --model /nvme/inkling_i4 --cap 2
材料未说明：README 未给出 `--cap 2` 的具体 RAM 占用、缓存命中率和 tok/s。；README 未说明该配置适合的最大上下文长度。
适合 我在研究 GLM-5.2 的 int4、MLA 压缩 KV 和 DSA 稀疏注意力，要求优化不能静默改变路由或输出语义；Colibrì 是否适合作为实验平台？
适合读者： 需要验证量化、MLA 和 DSA 是否保持模型语义的推理系统研究人员

适合，因为 Colibrì 把语义保真和可复现实验写进了项目边界，而不是只追求更高 tok/s。

  • README 声明默认策略“never silently changes model precision or router semantics”，并把语义保证与速度无 SLA 并列说明。
  • 前向路径通过 transformers oracle 做 teacher-forcing 验证，通常达到 30–32/32；这为量化和调度实验提供了可对照基线。
  • MLA 将 KV 状态从每 token 32,768 个浮点数压到 576 个，并支持跨重启持久化；README 声称其与不中断会话字节一致。
  • DSA 稀疏注意力可强制完整 key selection，并复现 dense attention；因此项目尤其适合研究模型专用优化的端到端影响。
  • README opening: “no SLA on speed, and a hard guarantee on semantics”
  • Faithful model, compressed state: “validated against a transformers oracle (teacher-forcing typically 30-32/32)”
  • Faithful model, compressed state: “576 floats/token instead of 32,768 (57× smaller)”
  • Faithful model, compressed state: “forcing full-key selection to reproduce dense attention exactly”
COLI_MODEL=/nvme/glm52_i4 ./coli doctor --deep  # strict tensors/shards/index/mirror preflight
材料未说明：README 未给出所有模型、所有量化粒度和所有硬件上的 oracle 通过率。；README 未说明如何自动导出逐 token 的路由差异报告。
适合 我有 6 张 RTX 5090，想让 GLM-5.2 完整驻留 GPU，并通过本地 Web 或 headless API 使用；Colibrì 是否适合？
适合读者： 拥有 6 张 RTX 5090、希望以本地 Web/API 形式提供 GLM-5.2 的多 GPU 工作站管理员

适合做本地低并发 Web/API 推理，因为 README 已展示 6× RTX 5090 的完整专家驻留结果，但它不是带 SLA 的生产服务框架。

  • “See it running” 给出 6× RTX 5090 上 744B 模型约 4 tok/s、TTFT 1.6 秒、disk 0 的 Web 仪表板结果。
  • 项目提供 coli web 和 coli serve，后者启动 API 与 dashboard 但不打开浏览器，适合 headless 工作站。
  • README 的统一入口会依据 config.json 选择模型引擎和聊天模板，GLM-5.2 不需要手工传模板。
  • 项目明确声明“no SLA on speed”，认证、限流、审计和并发治理不属于 README 承诺范围。
  • See it running: “744B model at 4 tok/s, TTFT 1.6 s, disk 0 — full expert residency on 6× RTX 5090”
  • Get started: “./coli web --model /nvme/glm52_i4”
  • Get started: “./coli serve --model /nvme/glm52_i4”
  • README: “no SLA on speed”
COLI_MODEL=/nvme/glm52_i4 ./coli doctor --deep  # strict tensors/shards/index/mirror preflight
材料未说明：README 未说明多用户并发时的吞吐、队列行为和上下文隔离。；README 未提供认证、权限控制、TLS 或审计功能。
适合 我只有 12 核 CPU、25 GB RAM 和一块容量充足的 SSD，想在本地运行 GLM-5.2 int4；Colibrì 是否适合？
适合读者： 使用 12 核 CPU 和 25 GB RAM 笔记本、希望本地运行 GLM-5.2 744B 的个人开发者

适合，但应接受较低吞吐和较长的磁盘等待，因为 Colibrì 的目标正是让超大 MoE 在低内存设备上可运行。

  • README 说明项目源于“12-core laptop with 25 GB of RAM”，并将存储、RAM 和 VRAM 作为统一推理层级。
  • GLM-5.2 int4 模型约 372 GB，主要门槛是 SSD 容量和持续读取能力，而不是把全部权重装入内存。
  • README 明确区分 cold 与 warm 运行；25 GB 设备的冷启动基线约为 0.05–0.1 tok/s，不能按服务器吞吐预期。
  • 默认策略不会静默改变精度或路由语义，因此更适合本地可行性验证、低并发和隐私场景。
  • Why “colibrì”: “a 12-core laptop with 25 GB of RAM”
  • Get started: “the model (372 GB)”
  • Usage limitations / measured findings: 25GB 设备冷启动约 0.05–0.1 tok/s
  • README: “no SLA on speed, and a hard guarantee on semantics”
COLI_MODEL=/nvme/glm52_i4 ./coli plan     # inspect the planned VRAM/RAM/disk placement
材料未说明：README 未给出该笔记本 SSD 的具体顺序读取速度、文件系统和实际 warm decode 速度。；README 未说明 25 GB RAM 下 GLM-5.2 的稳定最大上下文长度。
视情况 我准备直接使用约 1.6 TB 的 Kimi K3 原始快照，不想执行转换流程；Colibrì 能否满足这个约束？
适合读者： 有约 1.6 TB NVMe 空间、想在不转换模型的情况下运行 Kimi K3 2.8T 的本地模型研究人员

视情况，模型格式和磁盘容量符合项目路径，但“约 1.6 TB”不能自动等同于可稳定运行，还要看 NVMe 余量、读取带宽和可用内存。

  • README 明确写道 Kimi K3 从原始 checkpoint 流式读取 MXFP4 experts，因此“不需要转换”。
  • 同一章节给出的快照大小约为 1.6 TB；模型之外仍需为索引、缓存、日志和其他运行文件留出空间。
  • Colibrì 将存储、RAM 和 VRAM 统一为多级层级，说明 Kimi K3 不要求全部参数驻留快速内存，但磁盘会成为关键瓶颈。
  • 项目支持 make -C c kimi_k3 构建专用引擎，但 README 没有给出 Kimi K3 的具体 tok/s 或最低 RAM/VRAM 配置。
  • Get started / per-model notes: “Kimi K3 streams its MXFP4 experts from the original checkpoint, so there is nothing to convert”
  • Get started / per-model notes: “the snapshot is ~1.6 TB”
  • README opening: “744B to 2.8T parameters”
  • Model build examples: “make -C c kimi_k3”
材料未说明：README 未说明 Kimi K3 的最低 RAM、VRAM、SSD 读取速度和实际启动时间。；README 未说明原始 checkpoint 是否需要特定目录结构或额外索引文件。
视情况 我在 Windows 上准备运行带视觉能力的 GLM-5.3-Flash 321B，并希望直接使用命令行启动；应该采用 Colibrì 吗？
适合读者： 希望在 Windows 上运行 GLM-5.3-Flash 321B（带视觉）的本地应用开发者

视情况：Windows 启动路径和模型族支持是明确的，但 README 没有充分说明 GLM-5.3-Flash 的视觉输入接口与硬件需求。

  • README 将 GLM-5.3-Flash 列为 321B、带 vision 的支持模型，并说明所有模型共用 coli chat、coli serve 和 coli web 入口。
  • Windows 发布包提供 coli.cmd；README 特别提醒不要直接启动 .exe，因为引擎本身不会自动加载模型。
  • Windows 示例命令使用 coli.cmd chat --model D:\glm52_i4，模型路径和启动器都已给出。
  • 运行时核心是纯 C，Python 只用于一次性转换和可选 API gateway；不过 README 没说明视觉输入是否已在 chat、web 或 API 中完整暴露。
  • Supported models: “GLM-5.3-Flash (321B, with vision)”
  • Get started: “On Windows a release archive ships coli.cmd”
  • Get started: “The .exe files are the engines, not the launcher”
  • Get started: “coli.cmd chat --model D:\glm52_i4”
coli.cmd chat --model D:\glm52_i4
材料未说明：README 未给出 GLM-5.3-Flash 的模型下载大小、最低 RAM/VRAM 和 Windows 性能基线。；README 未说明视觉输入的文件格式、API 字段和当前支持的图像任务。

✨ 核心亮点

  • 纯C零引擎依赖，支持744B至2.8T MoE模型
  • 同一coli chat命令覆盖8个模型家族
  • 6× RTX 5090实测5.8–6.8 tok/s
  • 744B GLM-5.2支持RAM、VRAM、磁盘分层
  • GLM-5.2 int4容器约372 GB，存储门槛很高

🔧 工程化

  • 用coli chat、serve、web统一运行GLM-5.2等8个模型家族
  • 以VRAM、RAM和磁盘组成推理层级，流式加载MoE专家
  • MLA将KV状态压到每token 576 floats并持久化.coli_kv
  • coli plan、doctor和tune分别检查、规划并测量机器配置

⚠️ 风险

  • GLM-5.2模型约372 GB，25 GB机器仅达0.05–0.1 tok/s冷启动
  • 项目明确无速度SLA，存储与内存不足会降低推理速度
  • GLM-5.2旧per-row int4镜像质量约低9pp且可能触发循环
  • Kimi K3无需转换但快照约1.6 TB，磁盘要求更高

👥 适合谁？

  • 想在消费级GPU或CPU-only机器运行GLM-5.2的开发者
  • 拥有128 GB RAM或单张RTX 5070 Ti的本地推理用户
  • 需要研究存储、调度、内存分层和CPU/GPU重叠的工程师
  • 接受Python仅用于转换器或可选API网关的C/CUDA开发者