可复现的Colibrì基准测试方法论：面向社区贡献者的端到端A/B实验指南

可复现的Colibrì基准测试方法论：面向社区贡献者的端到端A/B实验指南

【免费下载链接】colibriRun frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦项目地址: https://gitcode.com/gh_mirrors/colibri3/colibri

Colibrì 是一个用纯 C 编写、零依赖的推理引擎，能把你已有的硬件（消费级 PC、Mac 甚至多 GPU 工作站）变成 744B 到 2.8T 参数 MoE 大模型的推理平台——专家权重直接从磁盘流式加载。🐦 在 Colibrì 社区，任何"我的机器更快了"或"这个优化有效"的结论，都必须由可复现的端到端 A/B 基准实验来证明。本文是一份面向新手的完整指南：从硬件基线校准、一条命令跑完 A/B 实验，到阅读效率报告、写出维护者可接受的实验记录，帮你把每一次调优都变成有据可查的数据点。

为什么 Colibrì 的基准测试坚持"可复现优先"

Colibrì 的设计哲学很直接：不对速度做承诺（no SLA on speed），但保证语义绝不悄悄改变（hard guarantee on semantics）。官方明确写道：实验必须通过"可复现的端到端测量"来赢得自己的位置。

这意味着社区把每个优化都当作假设，直到受控的 A/B 实验证明它有效。在 README.md 的"Open hypotheses"一节中，列出了当前仍在验证的猜想——路由历史能否胜过纯 LRU、双 SSD 能否把独立带宽变成解码速度、硬件感知规划器能否接近每台机器的最优配置——每一行都标注了"还差什么实验"。

社区共识一句话：一个控制良好的失败，比一个无法解释的快数字更有价值。

所以，可复现的基准测试方法论不是"加分项"，而是 Colibrì 贡献的入场券。

上图是社区 + 作者实测的解码速度阶梯：25 GB 笔记本冷启动 0.05–0.1 tok/s，6× RTX 5090 全驻留 6.8 tok/s——同一引擎、同一模型容器，硬件只决定专家住在哪一层。完整数据见 docs/benchmarks.md。

第一步：构建与自检，为你的机器建立基准基线

在比较任何"之前 vs 之后"之前，先确认你的机器本身是可复现的起点。

1. 构建 + 架构自检：进入c/目录运行./setup.sh，它会编译引擎并运行架构自检（预期通过 30–32/32 项）。

2. 测量你的磁盘（这一步最关键）。Colibrì 的 MoE 解码是磁盘受限的：冷缓存下每个 token 要读约 11 GB 专家权重。用 c/iobench.c 按引擎真实的读法测盘——19 MB 随机块、8 线程并行读：

   gcc -O2 -fopenmp iobench.c -o iobench ./iobench /path/to/model.safetensors 19 64 8 1 # 1 = O_DIRECT，绕过页缓存

   ⚠️ 避坑提示：大内存机器上，缓冲式（buffered）读测到的是页缓存而不是磁盘。请优先采用 O_DIRECT 结果，并且在一个本次会话未触碰过的分片上测量。

理解你测的是什么：Colibrì 把 VRAM / RAM / NVMe 当作同一个分层来安置 19,456 个专家，不同硬件上"专家住哪层"完全不同——这直接决定了基准测试的瓶颈位置（是等盘、还是等矩阵乘）。

三层内存分层：最热专家驻留 VRAM、暖专家钉在 RAM、冷尾部留在 NVMe 按需流式读取。你的机器 RAM 越少，专家缓存上限越低——小内存机器上，RAM 上限而非磁盘才是真正的约束。

第二步：一条命令跑完端到端 A/B 实验（tools/datapoint.py）

社区贡献的标准实验工具是 c/tools/datapoint.py。一条命令产出"机器信息 + 冷/热解码 + 磁盘带宽"的完整数据点：

python tools/datapoint.py --snap /path/to/model --shard /path/to/model-00000.safetensors

它的可复现设计值得新手记住：

• 页缓存自动驱逐：实验开始前先清空页缓存，iobench 在模型加载重新预热文件之前立即执行；
• 持久服务模式（默认）：同一个引擎进程跑完整个实验——1 次冷请求 → 1 次重复提示的"暖上界" → 4 条轮换提示（内置推理/代码/系统/多语言语料，固定顺序、无随机数）。轮换提示的中位数才是主结果，因为专家缓存必须适应不断变化的路由，而不是背下同一句提示；
• 指标来自引擎DONE帧：完成 token 数、解码 tok/s、专家命中率、RSS 均由引擎直接报告，无需重新分词统计；
• --mode fresh-process仅在你专门测启动/页缓存效应时使用（每行都是新进程，进程内缓存为空，两种模式的结果不能互相比较）。

跑实验时配合coli web的仪表盘观察实时状态：右上角的 tok/s、TTFT、队列深度，左侧的 VRAM/RAM/Disk 分层条和逐卡负载——这些面板正是你 A/B 对比时该记录的活指标。

Web 仪表盘（./coli web）：顶部是实时 tok/s 与 TTFT，左侧显示硬件面板与分层占用，底部是每轮耗时拆解与逐卡吞吐趋势——A/B 实验时，这些就是你要前后对比的"现场读数"。

第三步：一次只改一个变量，遵循受控对比纪律

Colibrì 实验日志中反复出现同一套纪律（以 6× RTX 5090 实验为例，见 docs/experiments/glm52-6x5090-2026-07-12.md）：

1. 贪心解码：TEMP=0、DRAFT=0，固定提示词与固定输出 token 数；
2. ABBA 或轮换顺序：A/B 两组交替执行，消除机器随时间漂移（热机、后台任务）带来的偏差；
3. 至少 3 次有效运行，报中位数，不报最好的一次；
4. 引用 tok/s 时必须注明 token 数：96 token 与 256 token 的解码速率会因固定成本摊薄而不同；
5. 每一步只改一个变量，并且是累积式的——这样"哪一步带来了多少提升"清清楚楚。

那份实验日志的"优化阶梯"就是这个方法的示范：从 2.30 tok/s 基线出发，全驻留 → 动态重钉 → 线程绑定 → 预填充校正，每行一个变量、一个数字、一条证据，最终 6.28–6.84 tok/s。被否决的方向也全部记录在案并回滚——这正是社区想要的记录方式。

第四步：阅读效率报告，让引擎自己解释瓶颈

当 A/B 出现差异时，效率报告帮你定位原因：

COLI_EFFICIENCY_MODEL=../glm52_i4 make efficiency-report

它会打开引擎所有可观测性开关（只加遥测、不改变计算输出），产出一份 9 节报告：吞吐与延迟分位（p50/p90/p99）、时间去向的五阶段占比、专家缓存命中率、磁盘 I/O 的 GB/token 与等待比例、路由质量、投机接受率、GPU 分层状态。任何一行越过建议阈值都会标记[FLAG]，并直接告诉你该拉哪根杠杆（加大RAM_GB、增加PIN_GB、试DIRECT=1……）。

阈值定义在 c/tests/README_efficiency.md 中，例如：磁盘等待 >40% → I/O 受限；缓存命中 <30% → 缓存抖动；p99 > 3×p50 → 存在解码停顿。解析这些遥测的共享工具在 c/tools/efficiency.py。

而"命中率"背后的机制是学习式缓存：引擎记录你的工作负载实际路由到哪些专家（.coli_usage），自动把最热的钉在内存里——用得越多越快。Brain 页面把 19,456 个专家画成一片活的皮层，亮度即路由热度，悬停可看专家主题亲和度——这是你做 A/B 前后对比缓存策略时的直观参照。

Brain 页面：颜色表示存储层级（VRAM/RAM/Disk），亮度表示路由热度，每次被路由的专家会闪白。A/B 实验改变PIN_GB或缓存策略时，热图的分布变化就是最直接的证据。

理解你在测什么路径：每个 token 的每一层都走同样的五步——route → union → place → overlap → learn，安置只决定速度，从不改变精度与路由语义。

每 token 路径：路由打分 → 批量合并 → 分层安置 → I/O 与计算重叠 → 更新用量统计。A/B 实验中的任何优化，都应能指出它作用于这五步中的哪一步。

第五步：质量门槛——正确性没通过的速度提升不算数

Colibrì 把正确性与吞吐、延迟、内存放在同一张报表里：

• 质量基准：./coli bench跑 MMLU / HellaSwag / ARC（0-shot log-likelihood）。官方记录过 OLMoE 的 fp16 vs int4 同环境 A/B，纯量化成本 -8.2pp，且集中在最难的任务上——所以量化类实验必须一起报告质量、移动字节数、延迟，而不能只看压缩比；
• token 精确预言机：引擎必须持续通过 token-exact oracle（main分支的硬性门槛，约 30–32/32 TF + 20/20 贪心一致）。声称"无损"的机制，必须给出逐 token 一致的重放证据；
• 论文/文献中的数字只是背景，永远不是本地证明——社区的论文声明测试矩阵 对每条声明都要求"同硬件、同模型、同提示、同 token 数、同精度策略"下的受控对比，并给出 confirmed / conditional / rejected / pending 的明确裁决。

第六步：写出符合社区标准的实验报告

你的记录会被 docs/benchmarks.md 的社区基准表收录。CONTRIBUTING.md 对基准报告的要求很短，但每一条都是可复现性的关键：

基准报告应包含：commit、精确命令、硬件与存储细节、预热策略、运行次数、中位吞吐。

再加上下列字段，你的数据点就完整了：

负结果同样要发布。README 明确邀请："Pick one row and publish the negative results too." 一次"换盘后 tok/s 不涨、瓶颈从 66% 磁盘翻转到 57% 矩阵乘"的记录（9950X 案例），其价值远超任何单点快数字——它直接改写了后续优化方向。

参考模板：docs/experiments/glm52-6x5090-2026-07-12.md（单卡→多卡全驻留）与 docs/experiments/inference-paper-test-matrix-2026-07-28.md（声明矩阵 + 测量契约）。

新手快速清单

• ✅./setup.sh构建并自检通过（30–32/32）
• ✅ iobench 用O_DIRECT在未触碰的分片上测盘
• ✅datapoint.py一条命令产出冷/热/轮换三态数据点
• ✅ 贪心、固定提示与 token 数、ABBA 顺序、≥3 次取中位数
• ✅ 效率报告定位瓶颈，引用[FLAG]与 PROFILE 拆分
• ✅ 质量门槛通过（token 精确或coli bench有数）
• ✅ 报告含 commit、命令、硬件、缓存状态、原始日志——负结果也写

照着这份方法论走，你的第一次实验就是一份"控制良好"的数据点——而这正是 Colibrì 社区最需要的贡献。🐦

【免费下载链接】colibriRun frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦项目地址: https://gitcode.com/gh_mirrors/colibri3/colibri