企业官网建设流程全解析

如何用 Colibrì 的 --topp 减少每 token 的专家磁盘读取以提速解码？

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

在 RAM 装不下整个模型的机器上，colibrì 把 MoE 模型的 routed experts 放在磁盘上按需流式读取（例如 GLM-5.2 int4 容器，冷 token 一次要读约 11 GB 专家字节，见 docs/benchmarks.md）。此时 token/s 基本由磁盘带宽决定。--topp的作用是在路由阶段按累计权重截断每个 token 实际参与计算的 routed experts，直接减少每 token 的专家磁盘读取，从而在磁盘瓶颈机器上提速解码。本文以coliCLI 驱动的主引擎为主线，给出从确认瓶颈、记录基线到验证提速的完整操作路径，并在末尾给出 Inkling 与 Kimi K3 两个姊妹引擎上的同名开关（可选分支）。

先确认瓶颈确实在磁盘

--topp的收益来自减少磁盘读取，所以第一步是确认冷专家字节还留在磁盘上。docs/tuning.md 的表述是：如果 plan 让冷专家字节留在磁盘上，速度就取决于缓存命中率。用coli plan查看放置计划：

COLI_MODEL=/nvme/glm52_i4 ./coli plan

coli plan会报告 hot（VRAM）、warm（RAM）、cold backing（磁盘）三层的放置、每项放置的理由以及预期瓶颈。若结果显示大量冷专家字节在磁盘层，就是--topp适用的场景——docs/inkling.md 把这个截断称为 "the lever that matters on a disk-bound host"。

可选地，按引擎实际的方式测一下磁盘随机读带宽（19 MB 并行随机读、8 线程）。注意文档提示（#86）：大内存机器上的 buffered 读可能测到的是 page cache 而不是磁盘，取 O_DIRECT 那次（末位参数1）才是真实数字，且要选一个本会话没读过的 shard：

cd c gcc -O2 -fopenmp iobench.c -o iobench ./iobench /path/to/glm52_i4/out-00069.safetensors 19 64 8 0 # buffered, 8 threads ./iobench /path/to/glm52_i4/out-00069.safetensors 19 64 8 1 # O_DIRECT (bypass cache)

命令中/path/to/glm52_i4替换为你的模型快照目录（即 quickstart 第 3 步的模型文件夹，例如/nvme/glm52_i4或 Windows 的D:\glm52_i4）；out-00069.safetensors需存在于该目录。该步骤会在c/下生成编译产物iobench。

记录一次不带 --topp 的基线

先按默认配置跑一轮，并保留每轮的 per-turn 统计行，作为后续对比的基线：

COLI_MODEL=/nvme/glm52_i4 ./coli chat

docs/benchmarks.md 的 "Test your machine, in order" 一节说明：聊天时观察每轮统计行，其中包含 tok/s、expert hit-rate（专家缓存命中率）和 RSS，这三项就是判断--topp是否见效的基线数字。

加上 --topp 重跑

COLI_MODEL=/nvme/glm52_i4 ./coli chat --topp 0.85

文档中出现的两个取值：docs/quickstart.md 推荐--topp 0.85（"reads less from disk, same quality"），docs/tuning.md 记录--topp 0.7的效果为减少 30–40% 的磁盘读取。两者都出自文档，任选其一并在相同提示词长度下与基线对比。

几个与执行直接相关的细节：

• --topp映射到引擎环境变量TOPP（默认0，即关闭）。docs/SETTINGS.md 明确：对有 flag 的旋钮（--temp、--ram、--topk、--topp等），优先使用 flag，这是受支持的设置面。
• 默认的--policy quality和--policy balanced会保留 checkpoint 的量化与路由决策；传入--topk或--topp属于显式的 lossy override，引擎会打印一条 warning 后继续运行。所以启动时看到警告是预期行为，不是故障。
• Windows（native，无 WSL）：python coli chat --model D:\glm52_i4 --topp 0.7（docs/windows.md）。
• Vulkan 构建：./coli run "Hello" --topp 0.7（docs/vulkan.md）。

如何判断是否生效

1. 对比 per-turn 统计行：加--topp后重跑同样长度的提示，看 tok/s 与 expert hit-rate 相对基线的变化。
2. 文档中的实测数据（docs/benchmarks.md 社区实测，均为--topp 0.7，属于特定机器的测量值，不是你机器上的固定预期）：
   • Intel Core Ultra 7 270K Plus · WSL2 · 24 GB RAM：默认 0.07 tok/s →0.11 tok/s（expert hit 11%）；
   • Ryzen 7 9800X3D · WSL2 · Samsung 9100 PRO PCIe 5.0 · RTX 5090：0.41 tok/s →0.52 tok/s；
   • Ryzen AI Max+ 395（Strix Halo）· 128 GB 统一内存：DIRECT=1 PIPE=1 --topp 0.70.06 冷启动 →1.10 tok/s持续；
   • 在小 RAM 机器（24 GB，引擎自动把专家缓存压到 2 slots/layer，RAM cap 而非磁盘是绑定约束）上，--topp 0.7alone 带来 "a clean 1.6× end-to-end speedup"。
3. 完整 datapoint（可选）：tools/datapoint.py一条命令产出机器信息 + 冷/热解码 + 磁盘的自动数据点，会自动根据 config.json 选择 GLM、Inkling、Kimi K3、OLMoE、Qwen3.6 或 DeepSeek V4 引擎：

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

注意该脚本在加载引擎前会逐出 OS page cache（以便测出真实的冷读行为），请在机器空闲时运行。/path/to/model与/path/to/container/model-00000.safetensors分别替换为你的模型目录和一个容器 shard 文件。

可选分支：Inkling 与 Kimi K3 上的同一语义

• Inkling 引擎（直接以./c/inkling启动，不经过coliflag）：使用环境变量TOPP=<p>，语义与主引擎一致——保留累计权重达到p的 routed experts、丢弃尾部，"a different computation from the declared top-k"。默认关闭；运行时报告[topp] … N/M routed used (X% trimmed)，可以直观看到裁剪比例（docs/inkling.md）。
• Kimi K3 引擎：环境变量K3_TOPP（默认0= off），同样按累计门控权重裁剪 routed experts；docs/ENVIRONMENT.md 将其标注为 quality lever，建议与K3_LOGITS做 A/B 对比。

限制与冲突说明

• 这是 lossy 路由：改变了模型实际执行的计算。若叠加 MTP 投机解码，注意 tuning.md 的提示：--topp下的 MTP acceptance 百分比跨引擎版本不可比（#163），对比接受率时保持引擎版本一致。
• 收益来自减少磁盘读取，前提是冷专家字节仍在磁盘上；docs/tuning.md 的瓶颈实验显示，当缓存命中率高、解码转为 matmul-bound 时，继续压路由对总速度的贡献有限。
• 文档间的一处措辞差异：docs/ENVIRONMENT.md 把TOPP列在采样相关变量下（默认0，"0 = use NUCLEUS"），而 tuning.md、inkling.md 与 quickstart.md 描述的是它对专家路由的裁剪。本文按后者的行为写作，操作时以 CLI flag--topp为准。
• 想要更强的路由裁剪时，tuning.md 给出的--topk（配合--policy experimental-fast）被标注为 "Explicit research-only router reduction"，与--topp同属显式 lossy override，会打印 warning。

如果--topp之后仍受磁盘限制，tuning.md 中的磁盘侧旋钮（PIN/PIN_GB固定热专家、DIRECT=1、PIPE=1、PILOT=1预取）都标注了各自的测量条件与适用硬件，建议在同一个基线上逐一 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/GitHub_Trending/colibri3/colibri