第 6 章 · 02 ROUTE_TRACE 流与学习型缓存

第 6 章 · 02 ROUTE_TRACE 流与学习型缓存

本节摘要:ROUTE_TRACE=<path> 每条 (moe 调用, batch 行) 输出一行 <call> <row> <layer> <id>:<gate.4f> ...,字节级和旧 colibri.c 一致,tools/route_pairs.py 和 .coli_pairs 流水线原样消费。.coli_usage 每个 turn 更新,驱动 PIN=auto 把最热专家钉进热存——这就是"路由有可测结构、结构可缓存"的工程化体现,也是整个权重 JIT 的可行性基础。学习型缓存越用越快。但 Colibrì 对此诚实:路由历史可能过拟合,所以用 held-out 跨会话 A/B(coding/chat/multilingual/long-context)验证。route_trace 的 engine-agnostic 设计让所有引擎发同样字节,这是协同基础。

内容来源:原项目源码 c/route_trace.h(L46-50)、README.md(L200-209)

⚠️ 注意:本节是第 6 章的收口节,也是整个"权重 JIT + 学习型缓存"主线的总结。路由遥测不只是"日志",它是 Colibrì 越用越快的发动机——每一次推理都在喂养下一次推理的热存决策。但要理解它为什么有效,必须先理解"路由结构可缓存"这个核心命题。

学习目标

1. 读懂 ROUTE_TRACE 流格式和 tools/route_pairs.py 消费链。
2. 理解 .coli_usage 每 turn 更新驱动 PIN=auto。
3. 理解 expert atlas 专家热图与"结构可缓存"命题。
4. 说清学习型缓存越用越快的机制。
5. 理解诚实假设:held-out 跨会话 A/B 防过拟合。

一、ROUTE_TRACE 流:字节级兼容的逐行路由日志

ROUTE_TRACE 环境变量指向一个文件路径,开启后引擎在每次 MoE 调用、每个 batch 行输出一行记录。注释第 46-49 行定义格式:

46    * ---- trace format (ROUTE_TRACE=<path>) ----
47    * One line per (moe call, batch row): "<call> <row> <layer> <id>:<gate.4f> ...".
48    * Byte-identical to what colibri.c emitted before this header; tools/route_pairs.py and
49    * the .coli_pairs pipeline consume it unchanged.
​

每行字段:<call> 是 MoE 调用序号,<row> 是 batch 内的行号,<layer> 是层号,后面跟一串 <id>:<gate.4f> 表示这一行在这一层路由到的专家 id 和对应 gate(四位小数)。

<call> <row> <layer> <id>:<gate.4f> <id>:<gate.4f> ...
   0     0     12    47:0.2314  182:0.1583  9901:0.0945  ...
​

关键设计:字节级和旧 colibri.c 一致。这条流不是 route_trace.h 新发明的格式,而是把 colibri.c 之前的输出原样迁移过来。这样 tools/route_pairs.py 和 .coli_pairs 流水线无需任何修改就能继续消费——这是"engine-agnostic 设计让所有引擎发同样字节"的第一次实战:旧工具不用改,新引擎(kimi_k3.c、olmoe.c)只要 include route_trace.h 就自动产生兼容流。

ROUTE_TRACE 流的主要用途是离线分析路由行为:专家热度分布、batch 内并集大小、跨层路由相关性、PILOT 预取命中率回测。这些分析结果反过来指导热存策略和镜像规划。

.coli_pairs pipeline 是 ROUTE_TRACE 的下游消费链:它把流式 trace 聚合成 (前一层路由, 下一层路由) 的 pair 频次,直接量化"一层可预测性"这个数字。Colibrì 文档里的 71.6% 就是这样测出来的——不是凭感觉,而是用真实 trace 算出来的条件概率。这种"用数据为工程决策背书"的态度,是 Colibrì 整个 I/O 工程(PILOT 预取、batch-union、确定性哈希)能立得住的根本。

二、.coli_usage 每 turn 更新:PIN=auto 的燃料

.coli_usage 是引擎自己消费的历史文件,记录每个专家在每个层的累计访问计数(上一节讲的稀疏三元组格式)。它和 ROUTE_TRACE 流的区别在于:

ROUTE_TRACE 流  →  人类/工具消费,逐次推理的细粒度日志
.coli_usage     →  引擎自己消费,累计的专家热度排名
​

每个 turn(一次完整的对话回合)结束时,引擎把这一 turn 的路由计数合并写回 .coli_usage。这个累计排名就是 PIN=auto 的输入——启动时引擎读 .coli_usage,根据历史热度把最热的专家钉进热存(RAM 或 VRAM),剩余专家落盘按需流式。

这是"学习型缓存"的字面含义:越用越快。第一次跑某个工作负载时,热存按通用先验填充;跑过几个 turn 后,.coli_usage 积累了真实路由热度,下一次启动时热存按你的工作负载定制;工作负载越跑越多,热存命中率越高,decode 越快。

冷启动场景需要特别说明:第一次运行(没有 .coli_usage)时,热存按"均匀先验 + 路由模型先验"填充——比如某些层的专家总是被均匀路由,某些层的专家有偏置。这个先验不算精准,但比瞎选好。真正精准的热存来自积累几个 turn 后的真实 .coli_usage,所以"越用越快"的曲线在头几次推理后最陡,之后趋于平稳。

README 第 205-209 行用一句话点睛:

Between the tiers sits a learning cache: the engine records which experts your workload routes to (.coli_usage, updated every turn) and pins the hottest ones automatically — colibrì literally gets faster the more you use it.

三、expert atlas 专家热图:路由结构可缓存

学习型缓存能成立的根本前提是:路由有可测结构,结构可缓存。

如果是均匀随机路由(每个专家等概率被选),.coli_usage 的排名就毫无意义,热存选谁都不会比选别人更好。但真实 MoE 路由不是随机的——不同任务、不同 token 模式,会稳定地偏向某些专家。Colibrì 用 expert atlas 专家热图把这件事可视化:把 19456 个专家按层铺开,每个格子的颜色深浅代表该专家在历史工作负载里的热度。

热图呈现出来的不是均匀噪声,而是有结构的聚集:某些专家永远冷,某些专家稳定热,某些专家在某些任务下才热。这种结构正是 PILOT 路由预取"71.6% 一层可预测"的根本原因(第 5 章讲过),也是 .coli_usage 学习型缓存有效的根本原因。

这种结构有几种典型形态值得识别。全局热专家:跨所有工作负载都热,是模型的"骨架"专家,必须进热存。任务特异热专家:只在某类任务(coding、数学、多语言)下热,.coli_usage 必须匹配你的实际工作负载才有用。长尾冷专家:几乎从不被路由,放磁盘流式即可,完全不浪费热存空间。expert atlas 让这三种形态一眼可辨,是调试热存策略最直观的工具。

💡 深潜要点:"路由结构可缓存"是整个权重 JIT 的可行性基础。如果路由完全不可预测,流式加载就不可能提前预取,学习型缓存也不可能命中。Colibrì 之所以敢把 370GB 专家放磁盘按需流式,正是因为它知道路由不是随机的——可预测,所以可预取;有结构,所以可缓存。这两个性质撑起了整套多层级存储 + I/O 工程。

四、诚实假设:held-out 跨会话 A/B 防过拟合

学习型缓存有一个潜在风险:过拟合。如果 .coli_usage 只反映了某一种工作负载(比如全是 coding 任务),换到另一种工作负载(比如多语言)时,热存选的专家可能完全不对,缓存反而拖累。

Colibrì 对此态度非常诚实——不掩盖这个风险,而是用 held-out 跨会话 A/B 实测验证:

• coding workload 积累的 .coli_usage,在 held-out coding 上验证(应该加速)。
• 同一份 .coli_usage 拿到 chat / multilingual / long-context 工作负载上 cross-session A/B(验证是否泛化)。
• 如果某个工作负载的排名在另一个工作负载上反而变慢,说明过拟合,需要更通用的热存填充策略。

这种诚实假设是 Colibrì 工程文化的体现:不宣称"学习型缓存永远更快",而是承认它依赖工作负载相似性,用实验而不是口号来划清边界。这也是为什么官方文档强调"run a few representative prompts first"——先用代表性 prompt 让 .coli_usage 反映真实工作负载,再开 PIN=auto 才会有正向收益。

五、engine-agnostic 设计:协同基础

把第 6 章两节串起来,route_trace.h 的 engine-agnostic 设计是 Colibrì 多引擎协同的基础:

所有引擎 → include route_trace.h → 发同样字节
                                ↓
        ROUTE_TRACE 流(工具消费,字节级兼容旧 colibri.c)
        .coli_usage(引擎消费,跨引擎格式一致)
                                ↓
        PIN=auto 学习型热存(越用越快)
        mirror plan/stage(基于 .coli_usage 规划部分镜像)
        PILOT 预取验证(71.6% 一层可预测)
​

每个引擎(GLM、deepseek_v4、inkling、kimi_k3、olmoe)只要知道自己输出的 layer/expert/gate 三个量,就能接入这条统一的遥测+学习管线。新引擎接入零额外成本——include 一个头文件,自动获得 ROUTE_TRACE 流、.coli_usage 持久化、PIN=auto 热存、mirror 规划的全部能力。

这是"机制深潜"教程反复出现的主题:约束驱动的极简设计。route_trace.h 拒绝共享引擎类型(因为会破坏多引擎兼容),只要求三个最小输入(layer/expert/gate),却撑起了一整条学习型缓存+遥测管线。少即是多。

本节要点回顾

1. ROUTE_TRACE 流每 (moe 调用, batch 行) 一行 <call> <row> <layer> <id>:<gate.4f> ...,字节级兼容旧 colibri.c,tools/route_pairs.py 原样消费。
2. .coli_usage 每 turn 更新,驱动 PIN=auto 把最热专家钉进热存,越用越快。
3. expert atlas 专家热图证明"路由有可测结构",这是结构可缓存+权重 JIT 的可行性基础。
4. 诚实假设:路由历史可能过拟合,用 held-out 跨会话 A/B(coding/chat/multilingual/long-context)验证。
5. engine-agnostic 设计让所有引擎 include 一个头文件就接入统一遥测+学习管线,新引擎零额外成本。

下一节:第 6 章的 MoE 路由与遥测讲完了。第 7 章我们深潜量化与压缩状态——KV 持久化、MLA 把 576 floats/token 压到 57×、KV 前缀共享,看清 Colibrì 如何做到"模型保真、状态压缩"。