第 1 章 · 03 per-token 五步路径与诚实研究风格

第 1 章 · 03 per-token 五步路径与诚实研究风格

本节摘要:本节把第 1 章收口。前两节讲了"为什么能跑"(稀疏性)和"用什么跑"(纯 C 一模型一 .c)。本节讲"怎么跑"——每个 token 的每一层都走相同的五步路径:route 路由 → union 联合 → place 放置 → overlap 重叠 → learn 学习,设计目标是放置只决定速度。本节还讲清 Colibrì 的"诚实研究"风格——它是推理引擎也是开放研究平台,对速度没有 SLA,对语义有硬保证;每个优化都是可证伪假设,必须受控端到端 A/B 验证;README 里挂着一张"开放假设表",六行假设 + 已有证据 + 待做实验,并欢迎贡献负结果。读完本节,你完成了第 1 章的全部认知地基。

内容来源:原项目源码 README.md("How it works"/"Core techniques"/"Open hypotheses" 段)、docs/media/token-path.png。

⚠️ 注意:"诚实研究"不是修辞,是 Colibrì 的工程方法论。它的默认策略宁可慢也要保证语义不变,任何一个优化要进默认路径,都得拿出受控 A/B 的端到端数据。本节那张"开放假设表"列的六项优化,有几项至今仍是"已实现但未默认开"的状态,因为还没攒够跨硬件的端到端验证。

学习目标

阅读完本节,你应当能够:

1. 复述 per-token 五步路径(route/union/place/overlap/learn)的每一步做什么。
2. 解释为什么"放置只决定速度、不改语义"是设计目标。
3. 理解 route 与 union 的差别(路由决策 vs 去重联合)。
4. 理解 overlap 与 learn 各自针对什么瓶颈。
5. 复述 Colibrì "对速度无 SLA、对语义有硬保证"的含义。
6. 读懂"开放假设表"的六行(路由历史/多 SSD/硬件规划/无损压缩/路由感知推测/CPU-GPU 重叠),知道每行的假设、证据、待做实验。
7. 理解为什么"一个受控的负结果比一个无法解释的快数字更有价值"。

一、per-token 五步路径

README.md "How it works" 段配图 images/token-path.png,展示每个 token 每层走的五步:

route  →  union  →  place  →  overlap  →  learn
路由     联合     放置      重叠        学习
​

README.md 原文:"Every layer of every token walks the same five steps. The design goal is that placement only ever decides speed — the router's decisions and the weights' precision are the same whether an expert answered from VRAM or from disk."

逐步拆开:

• route(路由):router(一个小型 gate 网络)看当前 token 的隐藏状态,算出本层要激活哪几个路由专家(top-k)。这一步只产生决策,不读权重——决策本身是几个整数索引。
• union(联合):把一个 batch 里所有 position、当前层路由到的专家去重合并。如果 batch 里两个 position 都路由到专家 #42,这个专家只读一次(README.md 叫 "batch-union")。这一步对抗的是"同一个专家被反复读"的浪费。
• place(放置):决定每个被联合出来的专家从哪一层存储应答——VRAM、RAM、还是 NVMe。这就是第 1 章 01 节讲的"放置只决定速度"的落地。命中缓存就直接用,未命中就从磁盘流式加载(第 3 章详讲 LRU/预取)。
• overlap(重叠):把"读磁盘"和"算 resident 专家"重叠起来。README.md:"a bounded async I/O pool (PIPE=1, default) loads missing experts while resident ones compute"——resident 专家在算的同时,异步 I/O 池在后台拉缺失的专家。还有 router-lookahead 线程(PILOT=1)提前一层预取(第 5 章详讲 io_uring/O_DIRECT)。
• learn(学习):把本 turn 的路由历史记下来(.coli_usage,每 turn 更新),供下次钉热专家、规划镜像、推测解码参考。这是 Colibrì "越用越快"的来源(第 6 章详讲 route_trace)。

💡 深潜要点:五步不是流水线的五个阶段,而是每一层、每一个 token 都完整走一遍的固定模式。route 算出决策 → union 去重 → place 决定存储层 → overlap 把 I/O 藏在 compute 后面 → learn 把路由历史沉淀下来。设计目标是"放置只决定速度"——也就是说,如果你把 place 这一步强制改成"全部从磁盘读",模型输出 token 应该完全一样,只是慢得多。这是 Colibrì 区别于"OOM 就 OOM"的引擎的根本。

五步每一步都对应后续一章的深潜对象,本教程的九章路径其实就是把五步展开:

读完本节你应该建立一个总览印象:全书后面 8 章都在反复落实这五步。理解了五步,就理解了 Colibrì 的全部优化都围绕"per-token 路径上的某个环节"做文章,没有逃出这个框架的"魔法优化"。

二、放置只决定速度

第 1 章 01 节讲过这条第一性原理,这里再从五步路径的角度强调:

route 决策 ─── 不受 place 影响(无论专家从 VRAM 还是磁盘应答,路由决策一样)
权重精度 ──── 不受 place 影响(int4 容器无论在哪层都是 int4)
place ─────── 只改变"什么时候拿到权重"——也就是速度
​

这条约束贯穿全书。它意味着 Colibrì 的所有存储优化(LRU 驱逐、一层前瞻预取、双 SSD 镜像、学习型热存)都不能改变模型输出——它们只能改变速度。如果一个优化会改变输出(比如为了快而跳过某个专家、或降低某个专家的精度),它就违反了第一性原理,必须默认关闭或拒绝。

README.md 在双 SSD 段也重申:"routing never changes tokens — both copies are byte-identical"——双 SSD 镜像两份模型,路由哪个盘读,token 输出都一样,因为两份是字节相同的。

这条原理还有一个工程后果:它让 Colibrì 的所有缓存策略都是"性能优化"而非"语义改变"。这一点很重要,因为它意味着你可以放心地调缓存参数(LRU 容量、预取窗口、pinned 集合大小)而不必担心改坏模型——最坏只是慢,不会错。这与很多"为了快而牺牲精度"的量化/蒸馏方案形成鲜明对比。README.md 的实测数据也印证这一点:6× RTX 5090 全驻留(5.8-6.8 tok/s)、128GB CPU-only 桌面(约 1.8 tok/s)、单 RTX 5070 Ti 笔记本(1.07 tok/s)、25GB 开发机(0.05-0.1 tok/s)——同一个引擎、同一个 int4 容器,只是 expert 住哪一层不同,速度差百倍但 token 输出一致。

⚠️ 注意:这条"放置只决定速度"的硬保证有一个前提——权重精度本身不变。Colibrì 默认 int4 容器就是 int4 容器,不会因为"内存不够"静默降到 int2。如果用户主动选了更低精度(如换 int2 容器),那是用户的显式决策,不是引擎的静默行为。区别在于"显式 vs 静默"——Colibrì 禁止的是静默改变,允许显式选择。

三、诚实研究风格:对速度无 SLA,对语义有硬保证

README.md 开头的 "research mission" 给 Colibrì 的定位:

Colibrì is an inference engine you can run today, and an open research platform. ... there is no SLA on speed, and a hard guarantee on semantics: experiments must earn their place through reproducible end-to-end measurements, and the default policy never silently changes model precision or router semantics. Insufficient fast memory may reduce speed; it must not quietly redefine the model.

关键三句:

1. 对速度无 SLA:Colibrì 不承诺"一定多快"。25GB 开发机能跑(0.05-0.1 tok/s),6× RTX 5090 全驻留也能跑(5.8-6.8 tok/s),都允许。
2. 对语义有硬保证:默认策略绝不静默改变模型精度或路由语义。int4 容器就是 int4 容器,不会因为"内存不够"偷偷降到 int2;路由器选 top-8 就是 top-8,不会因为"磁盘太慢"偷偷改成 top-4。
3. 高速内存不足可能降速,但不能静默重定义模型:这正是"放置只决定速度"的另一种表述。

这套哲学的方法论落到操作上就是:每个优化都是可证伪假设,必须受控端到端 A/B 验证才能进默认路径。

四、开放假设表

README.md "Open hypotheses" 段挂着一张表,把 Colibrì 当前的主要研究问题公开列出来。每行三个字段:假设 / 已有证据 / 还需要做的实验。这是 Colibrì 把"诚实研究"落到文字的关键载体。把六行提炼出来:

这张表有几个细节值得记住:

• 每行都是"假设"而不是"结论"。即便某项已实现(比如多 SSD、学习型钉热),只要还没攒够跨硬件端到端 A/B,就停留在假设阶段。
• "待做实验"列极其具体——指明硬件类别、对照变量、要记录的指标。这是为了让外部贡献者能直接照做并提交可复现结果。
• 几行明示了"可能失败"——比如学习型钉热"可能过拟合",MTP 推测"在 85% 命中率附近测得 32% 损失",CPU/GPU 重叠"快 CPU 加低驻留可能抹平胜场"。这是诚实研究风格的标志:主动暴露自家机制的失败模式。

五、欢迎贡献负结果

README.md "Open hypotheses" 段最后一句特别值得记住:

Want to help? Pick one row and publish the negative results too. ... A well-controlled failure is more valuable here than an unexplained fast number.

翻译:"一个受控的失败,在这里比一个无法解释的快数字更有价值。" 这句话是 Colibrì 整个研究文化的浓缩。它要求的实验记录清单也很具体:硬件、commit、模型/容器、精确命令、prompt、缓存状态、吞吐、TTFT、专家命中率、读取字节、质量检查——改一个变量,重跑,附原始日志。

这是为什么后续章节你会反复看到 > ⚠️ **注意** 标注"这个优化在某些硬件上可能负收益""这个机制是可证伪假设"——这不是教程作者在泼冷水,而是在忠实传递 Colibrì 的研究风格。本教程也按这个风格写:每个机制讲透它解决什么问题、怎么实现、源码在哪、有什么边界(包括失败模式),不夸大也不隐瞒。

💡 深潜要点:读完这张表,你就理解了为什么本教程叫"机制深潜式"——每个机制都是一个可证伪假设,讲它就是讲"它声称解决什么、源码怎么实现、边界在哪、有哪些已知失败模式、还差什么实验"。后续 8 章会反复回到这张表,把每一行展开成具体的源码精读。

本节要点回顾

1. per-token 五步:route 路由 → union 联合 → place 放置 → overlap 重叠 → learn 学习,每层每 token 都完整走一遍。
2. 放置只决定速度:route 决策与权重精度不受 place 影响,这是全书第一性原理。
3. 诚实研究风格:对速度无 SLA,对语义有硬保证;默认策略绝不静默改模型。
4. 每个优化都是可证伪假设,必须受控端到端 A/B 验证才能进默认路径。
5. 开放假设表六行:路由历史/多 SSD/硬件规划/无损压缩/路由感知推测/CPU-GPU 重叠,各有假设/证据/待做实验。
6. 负结果有价值:一个受控的失败比一个无法解释的快数字更宝贵;实验记录清单极其具体。

下一章,我们离开"全貌"层,深潜第一个具体机制——st.h 怎么读 safetensors、quant.h 怎么解码量化容器、FORMATS.md 怎么治理格式编号。