Colibrì 是一个纯 C、零依赖的 MoE 推理引擎，把显存、内存与磁盘当作统一分层，按需流式加载路由专家，让消费级与异构硬件运行 744B 至 2.8T 参数的前沿模型。
项目定位与要解决的问题
项目自我定位为既能今天运行、又是开放研究平台的推理引擎，主攻软件与硬件边界上的推理侧性能：模型格式、内存层级、存储 I/O、放置、调度、内核、投机与 CPU/GPU 重叠，目标是让大模型对稀缺硬件的依赖更小、运行成本更低。它公开声明不在速度上给 SLA，却在语义上给硬保证：快速内存不足只能降低速度，不能悄悄改变模型精度或路由语义；任何优化必须通过可复现的端到端测量来证明自己，而不是靠微基准好看。README 还把可及性当作实际后果：在自己已有的机器上运行 744B 参数模型，实时观察每个专家的触发，并改动实现它的代码，而不是租用 API 背后的智能。
核心能力
核心机制被作者类比为权重版的 JIT：不把全部参数当作必须常驻的状态，而是按路由证据分时装载，运行越多，正确的专家越热。测量得到的路由热度驱动每层 LRU、学到的常驻热存储以及提前一层的预取；一批位置会让每个唯一专家只读一次，即 batch-union；有界异步 I/O 池把缺失专家的读取与常驻专家的计算重叠；O_DIRECT 绕过页缓存，双 SSD 按实测或声明带宽做确定性哈希分流，使预读与按需读落在同一块盘。状态压缩方面，MLA 注意力把每 token 的 KV 状态从 32768 个浮点压到 576 个，README 称小 57 倍，并跨重启持久化；DSA 稀疏注意力通过强制全键选择复现稠密注意力来验证。投机解码使用原生 MTP 头与语法强制草稿，README 强调 MTP 头必须为 int8、草稿与验证必须计算同一函数，收益不足时可关闭投机。
技术结构与实现思路
引擎本体是单个 C 文件加少量小头文件，不用 BLAS，运行时不依赖 Python，也不要求 GPU；发行包里的 coli 启动器与 API 网关是 Python 脚本。内存层级上，稠密部分（注意力、共享专家、嵌入，约 17B 参数）以 int4 常驻内存，约 9.9 GB；19,456 个路由专家（75 个 MoE 层各 256 个，再加 MTP 头，int4 下每个约 19 MB，合计约 370 GB）放在磁盘按需流式读取，并可选一个显存层。每 token 约激活 40B 参数，其中约 11 GB 逐 token 变化。执行后端覆盖 CPU、CUDA、Metal 与 Vulkan，多路主机可用环境开关把常驻权重交错到各内存控制器。集群模式下协调者保留 token 生成、路由与 KV 状态，专家 worker 在其它机器上执行路由 FFN，一层的 batch-union 作为单个持久 TCP 请求发送，避免每个专家一次往返。
实际工作流程
每层每 token 走相同的五步：route、union、place、overlap、learn。路由先决定激活哪些专家，batch-union 合并一批位置所需的唯一专家，放置阶段在显存、内存、NVMe 三层间决定命中位置，重叠阶段用异步 I/O 与一层前瞻预取掩盖读盘延迟（README 称路由提前一层有 71.6% 可预测），学习阶段把本轮路由写入使用记录并自动固定最热的专家，于是重复性负载会逐渐变快。操作上，运行 coli chat 或 coli serve 即可，命令行示例显示约 32 秒就绪、常驻 9.9 GB。磁盘受限时可用 mirror plan、stage、verify 三步为第二块盘规划部分镜像：规划器直接读 safetensors 头、按最热专家优先，staging 走临时文件、做 SHA-256 校验、保留请求的剩余空间且不删除已有镜像分片。会话状态存在 KV 文件里，重启后对话可热开启、无需重新预填充。
与同类方案的取舍
从 README 自述看，差异点有三类。其一是工程形态：整个引擎是单个 C 文件加小头文件，不用 BLAS、运行时不依赖 Python、不要求 GPU，专家权重可从磁盘流式读取，因此不要求模型装进快速内存，25 GB 笔记本、128 GB 纯 CPU 台式机到多卡主机跑的是同一个引擎与同一个 int4 容器。其二是语义纪律：放置层级只影响速度，不影响路由决策与权重精度，前向过程与 transformers 参照实现做过 token 级校验，MLA 的 KV 压缩与 DSA 稀疏注意力都要求能复现稠密结果。其三是研究姿态：README 把优化当作假设，列出尚未完成的对照实验，并明确欢迎公布负面结果，还声明速度不设 SLA。文中性能数字（全常驻约 5.8 至 6.8 tok/s、纯 CPU 约 1.8 tok/s、25 GB 机器 0.05 至 0.1 tok/s 等）均为项目方在特定硬件上的自述测量，此处未独立验证，也不构成与其它引擎的快慢结论。
值得关注的设计
核心创新在于把权重视为需要暂存的数据而非常驻状态，README 称之为面向权重的 JIT。引擎用实测路由热度驱动每层 LRU、学习型 pinned 热存储和提前一层的预取，路由器先跑一层以掩盖加载延迟；批处理位置对每个唯一专家只读一次，即 batch-union。显存、内存、NVMe 是同一套权重的放置层，放置只决定速度，不改动路由决策与权重精度。双 SSD 场景下按测得或声明的带宽比例做确定性哈希，把专家读取分摊到两块盘，镜像只读、启动时逐文件校验，缺文件或读错回退主盘；另有部分镜像的 plan、stage、verify 流程，用已学到的专家历史排序要复制的分片。I/O 层使用 O_DIRECT、重叠读取与计算、加权双盘条带。MLA 注意力把 KV 压到每 token 576 个浮点并持久化。还提供本地集群模式，把路由 FFN 交给其他机器，按层的批量并集走一个持久 TCP 请求。
适用领域和具体场景
主要应用是在自己已有的机器上运行前沿规模的 MoE 模型，而不是通过 API 租用智能。README 展示了一条连续的硬件谱：6 张 RTX 5090 全驻留、128GB 纯 CPU 台式机、单张 RTX 5070 Ti 的笔记本级机器，以及 25GB 开发机上从磁盘全流式加载的基线。配套的网页仪表盘显示实时 token 指标、每轮时间分解和显存、内存、磁盘三层驻留条；Brain 页面把 19,456 个专家画成实时皮层，颜色表示存储层、亮度表示路由热度，被路由到的专家会闪白；Atlas 页面把测量得到的专家图谱画成三维星系，位置是实测路由亲和度而非学习到的嵌入，可用于观察诗歌、法律、中文、SQL 等主题聚类。另有本地集群模式，用其他 Mac 执行磁盘支撑的专家 FFN，适合手头有多台机器却没有单台大内存主机的用户。项目同时把自己定位为开放研究平台，用于跑放置、预取、量化、推测解码的端到端 A/B 实验。
哪些人会受益
面向愿意自己测量、并且能接受慢速的开发者与研究者：拥有消费级 GPU、多块 NVMe 或异构机器的个人；希望在本地持有权重而不租用 API 的隐私敏感用户；研究推理系统、内存层级、存储 I/O、调度、内核与推测解码的工程人员；以及 C 与系统编程贡献者，因为引擎是一个 C 文件加少量头文件，没有 BLAS，运行时不需要 Python，也不需要 GPU。README 明确说这是研究平台、没有速度 SLA，因此不适合需要稳定吞吐承诺或开箱即用服务质量的生产团队。进入门槛也不低：参考模型容器约 372GB，需要大容量且最好快速的磁盘，在纯 CPU 或小内存机器上只是能正确运行但很慢。项目还格外欢迎按协议记录硬件、提交、模型容器、命令、提示、缓存状态、吞吐、TTFT、专家命中率、读取字节与质量检查，并愿意公开失败实验的人。
上手、部署与集成
采用路径大致分三步。程序本体很小，官方在 Releases 提供 Linux、macOS、Windows 预编译包，解压即用，无需编译器，解压后运行 coli info 即可确认引擎就绪；从源码构建需要带 OpenMP 的 gcc 或 clang，执行 setup.sh 完成构建与自检。启动器和 API 网关是 Python 脚本，所以需要安装 Python 3，但引擎本体是纯 C、零依赖。模型侧，Hugging Face 上有预转换的 GLM-5.2 int4 容器，README 强调要选 gs64 分组缩放版本并搭配 int8 的 MTP 头，理由是旧的逐行 int4 镜像在受控 A/B 中质量差约 9 个百分点，并被认为导致了 think 模式循环和无法终止的生成；也可以用一个可恢复的转换命令从 FP8 源分片转换，避免同时占用全部磁盘。README 列举了多个模型家族，各自一个 C 文件，共用 coli chat、serve、web 前端。双 SSD 通过环境变量启用，集群模式通过 coordinator 与 worker 子命令启用，未配置 worker 时传输路径保持禁用，单机路径不变。
限制与风险
README 自己划定了边界：对速度没有 SLA，只有语义上的硬保证，即默认策略不会静默改变模型精度或路由语义，快内存不足可以降低速度，但不应重新定义模型。磁盘 I/O 在多数机器上是解码瓶颈。各项优化都被当作假设：路由历史可能过拟合某个提示，预取前瞻在某些主机上可能反而更慢；O_DIRECT 依盘而异，在 QLC、无 DRAM 或虚拟化磁盘上可能中性甚至为负；双 SSD 仍需要更广泛的社区端到端 A/B；MTP 推测在约 85% 专家命中附近曾测得 32% 的性能损失，且 int4 的 MTP 头会把草稿接受率压到 0 至 4%；推测与语法强制草稿是否净赚取决于缓存温度，不赚时应关闭。gs64 容器修好了受控对比中的问题，但不是通用的重复或 EOS 饥饿防护。README 也说明各后端的收益组合取决于算力、带宽、驻留与工作负载。此外，文中模型名称、规模与全部性能数字均为项目方自述，本文无法独立验证。
综合观察
总体看，colibri 的价值不在某个单点跑分，而在于把超大 MoE 推理重新表述成一个放置与暂存问题：模型不需要装进快内存，只需要被放置在分层存储中，由路由器决定谁进入哪一层，并用实测热度持续调整。这个抽象配合面向权重的 JIT、批合并、层前瞻预取、压缩 KV 状态和可选本地集群，形成一套自洽且有可操作界面的工程叙事。README 罕见地列出自身未解决的假设、需要补的对照实验，并强调负面结果比无法解释的快数字更有价值，这种方法论姿态是它最可信的部分。风险同样清楚：所有性能与质量数字都来自项目方，缺少第三方复现；文中出现的模型版本与参数规模无法在本次分析中核验；实际体验高度依赖磁盘、内存、GPU 与工作负载，25GB 机器上 0.05 至 0.1 tok/s 的冷启动更像可行性证明而非可用性证明。建议把它当作可修改、可测量的实验平台来评估，而不是当作带服务等级承诺的推理服务。
解读依据仓库 README 与简介，周期榜名次和数据按已采集的日期动态计算；项目文档和实际能力可能变化。