Colibrì 是纯 C、零引擎依赖的 MoE 推理引擎，把显存、内存与磁盘当作统一分层，按需流式加载专家，让 744B 级模型在已有硬件上运行。
项目定位与要解决的问题
按 README 自述，项目的定位是“小引擎、大模型”：在消费级与异构硬件上运行前沿 MoE 模型（文中声称覆盖 744B 到 2.8T 参数），办法是把存储、RAM、VRAM 当作单一推理层级，作者称之为 AI 记忆多级化。它同时自称“今天就能跑的推理引擎”和“开放研究平台”，主要目标是推进软件与硬件边界上的推理侧性能，包括模型格式、内存层级、存储 I/O、放置、调度、内核、投机解码与 CPU/GPU 重叠，从而让大模型更少依赖稀缺硬件、运行成本更低。README 明确表示不提供速度 SLA，但对语义有硬保证：实验必须靠可复现的端到端测量赢得位置，默认策略绝不静默改变模型精度或路由语义；快存不足可以降低速度，但不能悄悄重新定义模型。这种“速度可变、语义不可变”的取舍，是理解该项目全部设计的前提，也是它区别于单纯追求吞吐的引擎的地方。仓库另附网站、Discord 与多语言 README。
核心能力
核心思路是把权重当作需要即时调度的数据，而不是必须常驻的状态，作者类比为“给权重做的 JIT”。据 README，744B MoE 每 token 只激活约 40B 参数，其中仅约 11GB 逐 token 变化，即被路由的专家。因此模型不必塞进快存，而要被放置：稠密部分（注意力、共享专家、嵌入，约 17B 参数）以 int4 常驻 RAM，约 9.9GB；19,456 个路由专家（75 个 MoE 层乘 256，再加 MTP 头，int4 下每个约 19MB）放在磁盘约 370GB，按需流式读取，并配每层 LRU、学习式 pinned 热存与可选 VRAM 层级。实测路由热度决定专家进入哪一层；路由器提前一层运行，以便预取隐藏加载延迟；引擎还会记录你的工作负载路由历史（.coli_usage，每轮更新），越用越热。工程手段包括每个专家的三个矩阵相邻存储、单次 pread 读出，有界异步 I/O 池（PIPE=1，默认），批并集让一批位置只读一次唯一专家，以及 PILOT 前瞻线程；README 称路由一层前瞻的可预测性实测为 71.6%。O_DIRECT、双 SSD 加权条带、NUMA 交错与异构执行也服务同一条流式路径。这些均属项目方自述与仓库内测量。
技术结构与实现思路
架构上，引擎本体是单个 C 文件 c/colibri.c 加少量头文件，不使用 BLAS，运行时不需要 Python，也不要求 GPU；发布包是预编译二进制，覆盖 Linux、macOS 与 Windows，解包即用。coli 启动器与 API 网关是 Python 脚本，因此需要 Python 3，但引擎本身声称零依赖。README 说支持的每个模型家族都是一个“兄弟引擎”：各自一个 C 文件、各自架构，共用同一套 coli chat、coli serve、coli web 前端，目前列出九个家族。执行后端包括 CPU、CUDA、Metal 实验后端与 Vulkan；Vulkan 后端把专家层、稠密投影与 MLA 注意力核心带到任何满足 Vulkan 1.2 的 GPU，可经 Mesa/RADV 支持厂商已停止支持的显卡（如 RX 580），README 称其在 RDNA4 上可与 ROCm 竞争。COLI_NUMA=1 可在多路主机上把常驻权重交错到各内存控制器。另有本地集群模式：协调者把 token 生成、路由与 KV 状态留在本地，磁盘承载的专家 worker 在其他 Mac 上执行被路由的 FFN，一层的路由批并集作为单个持久 TCP 请求发送，避免每专家一次往返；未配置 worker 时该传输通道关闭，单机路径不变。稠密层分片与浏览器/WebGPU worker 被列为后续方向。
实际工作流程
使用流程分准备与运行两部分。准备阶段先取程序：下载对应平台预编译包，或从源码用带 OpenMP 的 gcc/clang 构建，setup.sh 会检查工具链、编译并自测。再取模型：Hugging Face 上有预转换的 GLM-5.2 int4 容器，约 372GB，README 强调必须使用 gs64 组缩放版本并配 int8 MTP 头，旧的按行 int4 镜像在受控对比中质量差约 9 个百分点，是 think 模式循环与永不终止生成的根因；也可以用一个可续传命令从 FP8 源分片下载转换，无需同时占用 756GB 磁盘。运行阶段走 coli chat、coli serve 或 coli web。推理内部，每层每 token 走同样五步：路由、批并集、放置、重叠、学习；放置只决定速度，路由决策与权重精度不因专家来自 VRAM 还是磁盘而改变。磁盘侧还有可选的三步镜像流程：mirror plan 直接读取 safetensors 头，按已学习的专家热度优先挑选分片；mirror stage 通过临时文件复制，保留指定的空闲空间，用 SHA-256 校验每个分片，不删除既有镜像分片，完成后才原子发布回执；mirror verify 做校验。启动时镜像逐文件比对大小与 safetensors 头，不一致或缺失的文件静默留在主盘，因此部分镜像也可用；镜像永不被写入，用量与 KV 等侧车文件都留在主盘；镜像读错误回退主盘并只警告一次。
与同类方案的取舍
差异点主要落在方法论与语义承诺上，而不是单纯跑分。第一，README 主张一个层级而非一个内存要求：同一份权重可在 VRAM、RAM、NVMe 间放置，快存不足只影响速度，模型精度与路由语义不被静默改写，稠密部分常驻、专家流式、全部常驻等配置只是同一引擎的不同档位。第二，权重 JIT 依赖真实工作负载历史，但作者主动承认历史可能过拟合某个提示，前瞻预取在某些主机上也可能亏，因此这些是“可测量策略”而非承诺。第三，投机解码被要求自证价值：MTP 头必须用 int8，int4 头接受率会塌到 0–4%，草稿与验证必须计算同一函数（SPEC_PIN=1），且 README 记录在约 85% 专家命中附近实测到 32% 的性能损失，收益取决于缓存冷热，可用 DRAFT=0 关闭。第四，项目公开假设清单与每项所需的实验，鼓励连负结果一起发布，要求记录硬件、提交、模型与容器、完整命令、提示、缓存状态、吞吐、TTFT、专家命中率、读取字节与质量检查，并一次只改一个变量。第五，README 对未验证项相当坦白：O_DIRECT 依盘而定，QLC、无 DRAM 或虚拟化磁盘可能中性甚至负收益；双 SSD 仍需要更广泛的社区端到端 A/B；学习式 pin 的跨会话对比尚未完成；硬件感知规划器也还没与受控参数扫描逐类硬件比对。文中所有性能与质量数字均为项目方提供的基准与自述，未经我独立验证。
值得关注的设计
Colibrì 的核心主张是把存储、内存与显存视为同一次推理的层级（AI memory multitiering），而不是要求模型装进某一级存储器。它只让约 17B 参数的稠密部分常驻内存（int4 约 9.9GB），把 75 层共 19,456 个路由专家（int4 每个约 19MB，合计约 370GB）留在磁盘按需流式读取，并给出每层 LRU、基于实测路由热度的学习型固定热存储与超前一层预取。README 把它类比为权重的 JIT：不预先装载整个参数空间，而是根据实际路由证明哪些专家该进哪一级。配套机制包括 batch-union（同一批次位置对每个专家只读一次）、异步 I/O 池与 PILOT 预取线程（项目方称路由一层前瞻可预测性为 71.6%）、O_DIRECT 与双 SSD 按实测带宽加权的确定性哈希分片、以及从 .coli_usage 历史规划部分镜像的 plan/stage/verify 工具链。状态侧采用 MLA 压缩 KV（每 token 576 个浮点数而非 32,768，即 57× 更小）并跨重启持久化，DSA 稀疏注意力通过强制全键选择复现稠密注意力来验证。以上多为项目方自述与仓库内实验记录，部分机制 README 自己也标注仍需更广泛的社区端到端对照。
适用领域和具体场景
对使用者而言，最直接的用途是在自有硬件上跑起前沿规模的 MoE 对话：同一个 coli chat 或 coli serve、coli web 前端覆盖从 OLMoE 7B 到 Kimi K3 2.8T 的九个模型家族，无需 API 租赁即可本地持有模型。Web 界面不止是聊天窗口，它把 19,456 个专家画成活体皮层（颜色表示存储层级、亮度表示路由热度），另有 Atlas 页面按实测路由亲和度呈现 13,260 个已刻画专家与 1,041 个复制专精专家的聚类，可用于观察某次对话到底激活了什么。工程侧的应用包括：把第二块 SSD 作为字节完全一致的镜像以叠加读带宽，或在容量不足时按历史热度只镜像最热分片；用 cluster 模式把专家 FFN 分散到其他机器执行，而路由与 KV 留在协调节点；用语法强制草稿（GRAMMAR 指定 gbnf 文件）在 JSON 等受限输出上提高接受率；以及借助持久化 KV 让长对话重启后零重新预填充地热启动。对研究者，它被明确当作可以改动引擎代码的实验平台。
哪些人会受益
目标读者有三类。第一类是拥有消费级或异构硬件的个人与小团队：README 给出的实测梯度覆盖 6× RTX 5090、单张 RTX 5070 Ti 笔记本级机器、128GB 纯 CPU 桌面以及 25GB 开发机，说明它面向的不是机房而是已有设备；后端涵盖 CPU、CUDA、实验性 Metal、Vulkan（含厂商已停止支持的旧卡与 RDNA4），并有 NUMA 交错选项针对多插槽主机。第二类是推理系统与存储 I/O 方向的研究者和工程师：仓库把优化当作假设，列出路由历史放置、多 SSD 带宽、硬件感知规划器、有损表示、路由感知投机、CPU 与 GPU 重叠六条待验证命题，适合做单变量 A/B 的人。第三类是希望本地持有而非租用前沿模型、并且在意的权重精度与路由语义不被静默改写的人；其硬性承诺是缺少快速内存只降低速度、不改变模型语义。此外，愿意记录硬件、提交、命令、提示、缓存状态、吞吐、TTFT、专家命中率与质量检查，并公开失败结果的人，被明确邀请参与。
上手、部署与集成
上手路径被刻意拆成程序与模型两件事。程序侧：可直接从 Releases 取 Linux、macOS、Windows 预编译包，解压后运行 python3 coli info 自检，无需编译器；也可以克隆仓库进 c 目录执行 setup.sh，它检查 gcc 或 clang 与 OpenMP、编译并跑自测，若想让 coli 进 PATH 可用可编辑安装方式从克隆目录注册（不是 wheel）。README 说明启动器与 API 网关是 Python 脚本，需要本机有 Python 3，而引擎本身是纯 C、零依赖。模型侧：官方推荐在 Hugging Face 取预转换的 GLM-5.2 int4 容器，约 372GB，需放在有空间的盘上，且必须用 gs64 版本并确认 MTP 头是 int8；也可用 coli convert 从 FP8 源逐分片、可续地自行转换，避免一次性占用 756GB。仓库明确警告不要用旧的 per-row int4 镜像，称其在受控 A/B 中质量差约 9 个百分点，并给出 int8 MTP 头的文件大小以便核对。整体采用成本主要是磁盘容量与一次性的转换时间，而非新硬件采购；但 O_DIRECT 等参数被建议先测再用。
限制与风险
README 对局限的陈述相对诚实。速度上明确不提供 SLA：25GB 开发机冷启动只有 0.05 至 0.1 tok/s，128GB 纯 CPU 桌面约 1.8 tok/s（热），单张 RTX 5070 Ti 通过 GPU 常驻管线为 1.07 tok/s，6× RTX 5090 全常驻为 5.8 至 6.8 tok/s、TTFT 约 13 秒。质量上有明确代价与坑：per-row int4 镜像被测得质量差约 9 个百分点，是早期循环生成问题的根因；MTP 投机头必须是 int8，int4 会让接受率塌到 0 至 4%；README 还提到在专家命中率约 85% 附近 MTP 曾测得 32% 的性能损失，因此关闭投机是合法退路。机制层面也有保留：学习型固定可能对单一提示过拟合，前瞻预取在某些主机上可能亏；O_DIRECT 依赖盘型，在 QLC、无 DRAM 或虚拟化磁盘上可能中性甚至负面；双 SSD 的带宽模型虽自洽，但仍需更广泛的社区端到端对照。容量上，372GB 模型本身构成门槛。功能前缀约束也需注意：集群传输在未配置 worker 时禁用，稠密层分片与浏览器 WebGPU worker 属于后续工作，Metal 后端被标为实验性，Vulkan 的竞争力表述来自项目方文档。
综合观察
从架构角度看，这个项目最有价值的部分不是模型清单，而是把问题从让模型装进快速内存重述为把权重放到合适层级：稀疏 MoE 每 token 只激活约 40B、其中仅约 11GB 逐 token 变化，因此可缓存的路由结构就是可优化对象。它把这一洞察落成可操作机制，包括热度驱动分层、一层前瞻预取、批量专家并集、双盘确定性分片、压缩且可持久化的 KV，并且约束自己不做静默精度或路由语义替换，这一点比单纯的吞吐数字更难得。更具辨识度的是方法论：仓库把六条优化写成带证据与待做实验的假设表，公开承认历史可能过拟合、前瞻可能亏损、O_DIRECT 可能为负，并把可复现的失败称为比无法解释的快数字更有价值，同时要求记录硬件、提交、命令、提示、缓存状态与质量检查。风险同样清楚：所有性能数字均为项目方在其自有实验日志中测得，读者应视之为自述而非独立结论；部分机制作者自己就标注需要社区 A/B；372GB 的模型体积与首轮转换成本是实际门槛。综合判断，它更适合被当作一个可读、可改、鼓励测量的推理系统研究载体，而不是拿来即用的生产服务；其可信度建立在你愿意按它的协议亲手复现之上。
解读依据仓库 README 与简介，周期榜名次和数据按已采集的日期动态计算；项目文档和实际能力可能变化。