在低端硬件上部署 GLM 5.2 模型的方案

网站 · Discord · English · 简体中文 · 繁體中文 · Italiano

小巧的引擎，庞大的模型。探索如何在消费级及异构硬件上运行 GLM-5.2（7440 亿参数 MoE）——使用纯 C 实现，引擎零依赖，并将存储、RAM 和 VRAM 视为一个统一的推理层级体系。

Colibrì 是一个实验性推理引擎和研究平台。它的首要目标是跨越整个软件与硬件边界，追求推理侧性能——涵盖模型格式、内存层级、存储 I/O、放置策略、调度、内核、推测以及 CPU/GPU 重叠执行——从而降低大模型对稀缺硬件的依赖，并减少运行成本。

Colibrì 将 VRAM、RAM 和存储视为一个统一管理的内存层级体系。它被刻意设计成一个用于测试激进系统构想的平台，而不是提供 SLA 的生产运行时。实验必须通过可复现的端到端测量证明自身价值，而且默认策略绝不会悄悄改变模型精度或路由器语义。快速内存不足可能会降低速度，但绝不能暗中重新定义模型。

$ ./coli chat
  🐦 colibri v1.1.0 — GLM-5.2 · 744B MoE · int4 · streaming CPU
  ✓ ready in 32s · resident 9.9 GB
  › ciao!
  ◆ Ciao! 😊 Come posso aiutarti oggi?

Web 仪表盘（./coli web）：一个以 4 tok/s 运行的 7440 亿参数模型，TTFT 为 1.6 秒，磁盘读取为 0——在 6 块 RTX 5090 上实现所有专家完全驻留，并实时显示 token 指标、每轮耗时明细、VRAM/RAM/磁盘层级条，以及角落实时运行的迷你大脑。

Brain 页面：将全部 19,456 个专家呈现为一个鲜活的大脑皮层——颜色表示存储层级，亮度表示路由热度，每一轮中被路由到的专家都会闪烁白光。悬停时会显示该专家经过测量得到的主题亲和度。

Atlas 页面：将测量得到的专家图谱呈现为一个三维星系——包含 13,260 个已经刻画特征的专家，以及 1,041 个按主题聚类的复制型专家，例如诗歌、法律、中文、SQL 等。位置表示测量得到的路由亲和度，而非学习出的嵌入。拖动即可旋转。

前沿推理不应默认要求数据中心级硬件。Colibrì 的研究目标很简单：优化证据表明正在限制推理性能的每一个环节，从而降低推理对硬件的依赖及其总成本。

这包括改变权重的表示和移动方式，决定哪些内容驻留在 VRAM、RAM 或存储中，重叠执行异构计算，减少启动和同步开销，利用稀疏性与复用，以及测试新的解码算法。任何方案都不会仅仅因为它是惯例而受到保护；任何方案也不会仅仅因为微基准测试看起来很快就被采用。最终的判断依据是在真实机器上进行端到端推理，并在测量吞吐量、延迟、内存和成本的同时，衡量正确性与质量。

其实际意义在于可访问性：在你已经拥有的硬件上运行一个 7440 亿参数模型，实时观察每个专家的激活情况，并修改实现这一切的代码。不是通过 API 租用智能，而是将它掌握在自己手中：探究它、测量它、改进它。这个引擎被刻意保持得足够小，让任何愿意进行测量的人都可能贡献下一项有用的优化。

核心技术与测量结果

一个层级体系，而不是一道内存门槛。VRAM、RAM 和 NVMe 是同一组权重的不同放置层级；快速内存有限只会改变速度，不会改变模型语义。

权重的 JIT。测量得到的路由热度驱动逐层 LRU、学习得到的固定热数据存储区以及提前一层的预取，而不是加载所有专家。它在可重复的工作负载上表现良好；历史数据可能过拟合，前瞻预取在某些主机上也可能适得其反，因此两者仍然是可测量的策略，而不是性能承诺。

I/O 是引擎的一部分。批量合并专家集合、重叠读取与计算、O_DIRECT，以及加权双 SSD 条带化，都会直接优化流式加载路径，而不是假装存储延迟不存在。O_DIRECT 的效果取决于具体硬盘，而双 SSD 方案仍需要社区开展更广泛的端到端 A/B 测试。

异构执行。CPU、CUDA、Metal、NUMA 内存，以及部分或全部专家驻留，共享同一个运行时，并可根据具体机器进行组合；哪种组合最有利，取决于算力、带宽、驻留情况和工作负载。

压缩状态，但不改变模型。token 级精确前向验证、缩小 57 倍的 MLA KV 状态、可持久化的热会话以及忠实实现的 DSA，使优化始终与正确性绑定。这些是内存、延迟和正确性方面的特性，而不是笼统的吞吐量声明。

推测必须证明物有所值。原生 MTP 和语法强制草稿会接受端到端测量；当接受率无法抵偿验证成本时，可以将其禁用。

开放的假设、实验及参与方式

在受控的端到端 A/B 测试证明某项优化有效之前，Colibrì 始终将其视为一个假设。以下是目前的主要问题：

想参与吗？选择其中一行，也请发布负面结果。记录硬件、commit、模型/容器、确切命令、提示词、缓存状态、吞吐量、TTFT、专家命中率、读取字节数以及质量检查结果；每次只改变一个变量，重复运行，并附上原始日志。先阅读 CONTRIBUTING.md，按照基准测试协议进行比较，然后创建一个实验 issue。在这里，一次控制严谨的失败，比一个原因不明的高速数字更有价值。

一个 7440 亿参数的混合专家模型，每个 token 只会激活约 400 亿个参数——其中只有约 11 GB 的参数会随 token 改变，也就是被路由到的专家：

因此，整个模型不需要装进快速内存——它需要的是合理放置：

稠密部分（注意力、共享专家和嵌入——约 170 亿参数）以 int4 格式常驻 RAM（约 9.9 GB）；

19,456 个路由专家（75 个 MoE 层 × 256，再加上 MTP 头；以 int4 格式计算，每个约 19 MB）存放在磁盘上（约 370 GB），按需流式加载，并配有逐层 LRU 缓存、学习得到的固定热数据存储区以及可选的 VRAM 层级。

你可以把核心算法理解成一种面向权重的 JIT。编译器 JIT 从不编译整个程序——它观察实际执行了哪些代码，并即时编译热点路径。colibrì 对 7440 亿参数空间作出了同样的押注：参数不是必须始终驻留的状态，而是需要跨异构存储层级（VRAM / RAM / NVMe）调度的数据，并且仅在路由器证明其确实需要时才进行调度。测量得到的路由热度决定哪些专家有资格进入哪个层级；路由器会提前一层运行，让预取掩盖调度延迟；而且与 JIT 一样，引擎会学习你的工作负载：运行得越多，正确专家的热度就越高。这套机制之所以有效，是因为路由具有可测量的结构（参见专家图谱）——而结构是可以缓存的。

引擎由单个 C 文件（c/glm.c）和一些小型头文件组成。无需 BLAS，运行时无需 Python，也不要求 GPU。

每个 token 的每一层都会执行相同的五个步骤。其设计目标是：放置策略只决定速度——无论专家的响应来自 VRAM 还是磁盘，路由器的决策和权重精度都完全相同。

一个内存层级体系，而不是一项内存要求

双 SSD：两份模型副本，两倍读取带宽

在大多数机器上，解码受磁盘性能限制，而专家读取又是只读操作——所以如果你有第二块 SSD，可以把模型的完整副本放到上面，让引擎同时从两块硬盘进行流式读取：

COLI_MODEL=/fast/glm52_i4 COLI_MODEL_MIRROR=/second/glm52_i4 ./coli chat
COLI_DISK_WEIGHTS=9,3 ...   # optional: primary,mirror bandwidth ratio (else measured at startup)

每个专家都会通过确定性哈希被路由到其中一块硬盘，并根据两块硬盘测量得到的（或显式声明的）带宽进行加权，因此 readahead/PILOT 预取和按需读取始终会命中同一块硬盘，不会重复缓存任何内容。总带宽等于两块硬盘带宽之和——由 9 GB/s 和 3 GB/s 硬盘组成的组合，其专家读取速度比仅使用较快硬盘时快约 33%，而且 OMP 并行的固定加载/预热也会同时从两块硬盘进行流式读取。以下细节值得了解：

镜像会在启动时接受验证（逐文件检查大小，并确认 safetensors 头必须与主副本逐字节完全一致）；存在差异或缺失的文件会自动继续使用主副本，因此部分镜像完全可行——即使第二块 SSD 容量较小，只能存放部分分片，也仍然有所帮助；

镜像永远不会被写入：.coli_usage、.coli_kv 及所有 sidecar 文件都保留在主副本上；

如果镜像发生读取错误，系统会回退到主副本（只发出一次警告，不会崩溃），因此即使在运行过程中拔掉第二块硬盘，服务器也只会出现性能下降，而不会被直接终止；

路由永远不会改变 token——两个副本逐字节完全相同，而每次运行的 MIRROR: 统计行会显示每块硬盘提供了多少 GB 的数据。

同一个引擎可以覆盖整个硬件范围：在只有 25 GB 容量的笔记本电脑上，所有内容都从磁盘流式加载（速度慢，但结果正确）；在大型主机上，整套专家都可以常驻内存（CUDA_EXPERT_GB=auto PIN_GB=all），磁盘将完全退出解码路径。不同层级之间还有一个学习型缓存：引擎会记录你的工作负载路由到了哪些专家（保存在 .coli_usage 中，每轮都会更新），并自动固定最热门的专家——你使用得越多，colibrì 确实就会变得越快。在多路主机上，COLI_NUMA=1 会让常驻权重交错分布到多个内存控制器上（#82）。

绝不要重复等待磁盘

缓存未命中优化

缓存未命中的代价高昂，因此引擎的大部分精力都花在避免和交叠这些未命中上：每个专家的三个矩阵相邻存储并通过一次 pread 读取；一个有界的异步 I/O 池（PIPE=1，默认）在驻留专家计算时加载缺失的专家；批处理位置每个唯一专家只读一次（batch-union）；一个路由器前向线程（PILOT=1）预取下一层的专家——路由器可以提前一层预测 71.6%。在 GPU 上，驻留管道（COLI_CUDA_PIPE=2）跨层保持残差流在设备上，使 CPU 专家循环不中断；在 Apple Silicon 上，一个实验性的 Metal 后端在统一内存 GPU 上执行批处理的专家计算。

在真实 NVMe 上，测试 DIRECT=1。O_DIRECT 绕过页面缓存，在具有 DRAM 缓存和带宽余量的驱动器上通常能带来巨大收益（在 Blackwell/Windows 机器上用 PIPE=1 测得解码速度提升 34%；iobench 在 GB10 上从 4.25→9.69 GB/s）——但这取决于驱动器：QLC/无 DRAM 或虚拟磁盘可能中性或负面。先试试；保留硬件奖励的方案。

忠实的模型、压缩状态

前向传递针对 transformers oracle 进行逐令牌精确验证（教师强制 32/32）。MLA 注意力存储压缩的 KV 状态——每令牌 576 个浮点数而非 32,768 个（小 57 倍）——并跨重启持久化（.coli_kv）：对话以热启动重新打开，无需重新预填充，字节级与不中断的会话相同。DSA 稀疏注意力（GLM-5.2 的闪电索引器）忠实实现并通过强制全键选择验证以精确复现稠密注意力。

推测式解码，诚实相告

GLM-5.2 的原生 MTP 头起草令牌，由主模型在一次批处理前向中验证——有回报时达到 2.2–2.8 令牌/前向。两条艰苦获得的规则作为默认值提供：MTP 头必须是 int8（int4 头的接受率崩溃到 0–4%，#8），起草和验证必须计算相同的函数——SPEC_PIN=1 将两者固定到一个内核族（#163 是完整的取证故事）。语法强制起草（GRAMMAR=file.gbnf）为受限 JSON 输出增加大约零成本的接受。推测是否是净胜利取决于缓存温度——测量，当不划算时使用 DRAFT=0。

同一引擎，同一 int4 容器——硬件只改变专家的位置。完整基准表的亮点：

• 6× RTX 5090，完整驻留：5.8–6.8 tok/s 解码，TTFT ~13 s（实验日志）；
• 128 GB 仅 CPU 桌面：~1.8 tok/s 热启动（#200）；
• 单个 RTX 5070 Ti 笔记本级机器：通过 GPU 驻留管道 1.07 tok/s（#273）；
• 25 GB 开发机：0.05–0.1 tok/s 冷启动——这个项目开始的已证实底线，仍是诚实基准。

质量经过测量，非假设：int4 容器的量化成本和缩放粒度/旋转消融在 docs/benchmarks.md 和 #108/#81 中。

安装

你需要两样东西：程序（几百 KB）和模型（372 GB）。快速入门指南中有每个平台的分步说明。

下载预构建版本——Linux、macOS 和 Windows，无需编译器。从发布版本中获取你的平台对应的存档并解包：

mkdir colibri && tar xzf colibri-v1.1.0-linux-x86_64.tar.gz -C colibri && cd colibri
python3 coli info                         # engine ready ✓

你将获得引擎（colibri，在 Windows 上是 colibri.exe）、coli 启动器及其 Python 助手。无需重命名或配置——coli 在自身旁找到引擎。你只需安装 Python 3：启动器和 API 网关是 Python 脚本，而引擎本身是纯 C，零依赖。

或从源代码构建——需要带 OpenMP 的 gcc（或 clang）：

git clone https://github.com/JustVugg/colibri && cd colibri/c
./setup.sh                                # checks gcc/OpenMP, builds, self-tests

想要 coli 在你的 PATH 上？从检出项目，pip install -e . 注册它（引擎仍位于 c/ ——从克隆进行的可编辑安装，不是 wheel）。

模型

一个预转换的 GLM-5.2 int4 容器在 Hugging Face 上——使用带 int8 MTP 头的分组缩放（gs64）构建。它大约 372 GB，所以放在有空间的磁盘上，最好是快速的：

https://huggingface.co/mastouri/GLM-5.2-colibri-int4-g64-with-int8-mtp

⚠️ 使用上面的 gs64 容器，而不是更旧的按行 int4 镜像（mateogrgic/…、jlnsrk/…）：那些质量测得差约 9pp，是 #455 中原始思考模式循环和永不终止生成的根本原因。gs64 容器修复了那些受控的按行 A/B，但不是通用重复或 EOS 饥饿防护。MTP 头也必须是 int8，不是 int4（int4 → 0% 起草接受，#8）：ls -l <model>/out-mtp-* — int8（正确）是 3527131672 / 5366238584 / 1065950496。

或从 FP8 源自己转换——一个可恢复的命令，从不需要一次占用全部 756 GB 磁盘：

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

GLM-5.2 是参考模型，但相同的流式方法运行三个更多的系列。每个是一个兄弟引擎——一个 C 文件、自己的架构、相同的 coli chat / coli serve / coli web 前端（启动器从模型的 config.json 中选择二进制文件）：

Kimi K3 无需转换：其 QAT 训练的 MXFP4 专家直接从原始 Hugging Face 分片流式传输，bf16 稠密集在加载时量化。Inkling 提供 int4 专家但 bf16 稠密权重（49.4 GB 驻留）；在无法容纳这些的主机上，inkling.md 有一个单次传递工具将稠密集降至 15.3 GB，让 975B 在 25 GB 机器上运行——并写下诚实的权衡。

COLI_MODEL=/nvme/glm52_i4 ./coli chat     # RAM budget, cache and MTP auto-detected
COLI_MODEL=/nvme/glm52_i4 ./coli plan     # inspect the planned VRAM/RAM/disk placement
COLI_MODEL=/nvme/glm52_i4 ./coli doctor   # read-only readiness check
COLI_MODEL=/nvme/glm52_i4 ./coli doctor --deep  # strict tensors/shards/index/mirror preflight
./coli web  --model /nvme/glm52_i4        # API + web dashboard on one port
./coli serve --model /nvme/glm52_i4       # OpenAI-compatible API only

在 Windows 上同样的命令与 python coli chat --model D:\glm52_i4 配合工作。引擎在运行时是纯 C——python 仅由单次转换器和可选 API 网关使用。

coli 读取模型的 config.json，选择匹配的引擎二进制文件，并渲染该系列的聊天模板——所以命令行在模型间没有变化。构建你想要的引擎一次，然后只需将 COLI_MODEL 指向正确的目录：

make -C c glm                                     # GLM-5.2
make -C c inkling                                 # Inkling
make -C c kimi_k3                                 # Kimi K3

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

./coli web --model /nvme/inkling_i4               # API + dashboard, same port
./coli web --model /nvme/kimi_k3
./coli serve --model /nvme/inkling_i4             # API only

对于非 GLM 引擎，coli chat 在本地启动网关并将 TUI 附加到它，所以 TUI、API 和仪表板都通过相同的架构感知聊天模板——你从不需要自己传递模板。

两个按模型不同的东西，都在按模型页面中记录：

Inkling 在 RAM 紧张的主机上需要 int4 稠密容器和一个小的专家缓存：./coli chat --model /nvme/inkling_i4 --cap 2（见 inkling.md——默认 --cap 8 在驻留集之上需要 ~14 GB 缓存）。

Kimi K3 从原始检查点流式传输其 MXFP4 专家，所以没有东西要转换——但快照是 ~1.6 TB（见 kimi_k3.md）。

未来工作

推理系统研究是产品。当前的层次结构是 LRU + 学习的固定集；活跃工作跨越模型格式、压缩、放置、调度、I/O、CPU/GPU 内核、异构重叠、KV 状态和路由感知推测。目标是降低硬件要求和降低每有用令牌的成本。一切按这个项目的工作方式进行：端到端测量、评审和开放开发。

更多开放模型。分层算法是模型无关的：任何具有路由专家的 MoE 可以以相同的方式分阶段。GLM-5.2 和 OLMoE 现在运行；对更多开放权重系列的支持——Kimi K2（Moonshot AI）、Qwen3 MoE（阿里巴巴）、MiniMax——在路线图上。

支持项目

colibrì 作为一个人在 12 核笔记本电脑上有 25 GB RAM 的项目开始；今天其数字来自真实机器的社区。如果它对你有用：

⭐ 星标仓库并分享它；

🐛 用你硬件的基准数字开启议题——数据点比任何东西都能推动这个项目；

💬 加入 Discord 社区讨论实验、硬件结果和研究方向；

💬 通过 GitHub 议题联系以赞助开发或捐赠硬件。

Makefile                  根部构建/检查入口点
c/
├── glm.c                 单文件 GLM 引擎
├── st.h, tok.h, json.h   运行时头文件
├── backend_cuda.*        可选 CUDA 层级
├── Makefile              构建和本地检查
├── coli                  用户界面 CLI
├── openai_server.py      OpenAI 兼容的 HTTP 网关
├── setup.sh              一键本地设置
├── tools/                离线转换、测试用例和基准测试
├── scripts/              长期运行的转换助手
└── tests/                无依赖 C 和 Python 测试
web/                      浏览器 UI（纯 OpenAI API 客户端）
desktop/                  Tauri v2 桌面壳体包装 Web UI
docs/                     参考文档、实验、媒体

运行时路径刻意保持扁平和易读：glm.c 加上它的小头文件。从仓库根目录，make、make check 和 make clean 委托给引擎 Makefile。

蜂鸟体重仅数克，悬停静止，一天造访千朵花。这个引擎用蜂鸟的"口粮"——25 GB RAM、12 个 CPU 核心和大量磁盘耐心——让一个 744 亿参数的巨型模型活动起来。

colibrì 是一个引擎；它运行的思维是一份礼物。感谢那些开源发布前沿级权重的团队——Z.ai（GLM）、Moonshot AI（Kimi）、Alibaba Qwen、MiniMax 和 Allen AI（OLMoE）——以及每一位进行基准测试、二分查找、复制 atlas 运行或提交补丁的贡献者。这个项目证明了开源权重所能带来的可能。

Apache 2.0。GLM-5.2 权重由 Z.ai 在 MIT 许可证下发布。