铃阅
❌

阅读视图

【轻量化复刻大模型 / KIMI K3】Multi-Token Prediction(MTP / EAGLE-3)

原创 罗西的思考 2026-11-16 21:36 北京

【轻量化复刻大模型 / KIMI K3】Multi-Token Prediction(MTP / EAGLE-3)

  • 0x00 概要

    • 0.1 主要内容

    • 0.2 注意说明

  • 0x01. 演进脉络与定位

    • 1.1 前身与谱系

    • 1.2 同期竞品方案

  • 0x02. 原理讲解

    • 2.1 直觉类比视角

    • 2.2 准专业水平视角

    • 2.3 专家视角

    • 2.4 关键信息完整性

    • 2.5 与 DeepSeek‑V4 MTP 的对比

  • 0x03. 子知识点拆解 / 架构

    • 3.1 MTP 层结构(本项目 `mtp/mtp_layer.py`)

    • 3.2 主模型集成(`model.py`)

    • 3.3 配置 `MTPConfig`(`config.py:118-147`)

    • 3.4 参数计数

    • 3.5 EAGLE-3 组件(`mtp/eagle3.py`)

    • 3.6 投机解码 verify 组件(`mtp/speculative.py`)

    • 3.7 边缘处理

    • 3.8 MTP 代码

  • 0x04 Eagle VS MTP

    • 4.1 K3 架构中 MTP 和 EAGLE 的角色

    • 4.2 完整链路:MTP → EAGLE‑3 → 投机解码

    • 4.3 MTP 层架构 (预训练期)

    • 4.4 EAGLE‑3 架构 (推理加速期)

    • 4.5 EAGLE-3 如何复用 MTP

    • 4.6 MTP 与 EAGLE‑3 的差异究竟在哪里?

  • 0x05 子知识点深度分析

    • 5.0 共享抽象与统一符号

    • 5.1 子知识点:MTP 层结构(融合 + 一层 backbone 镜像)

    • 5.2 子知识点:偏移对齐(h[t] + emb(x[t+1]) → logits[t]=x[t+2])

    • 5.3 子知识点:EAGLE-3 特征融合 `[0 0 I]`

    • 5.4 子知识点:LK 损失(EAGLE-3 训练目标)

    • 5.5 子知识点:EAGLE-3 draft 推理(草稿自回归)

    • 5.6 子知识点:投机解码 verify 与端到端循环

    • 5.7 探讨代码(`experiments\models\llm\kimi_k3\mtp\eagle3_demo.py`)

  • 附录 A:三方参考核对对照表(file:line 汇总)

  • 附录B. 实测数据 (来自项目实验)

    • B1: 联合损失 vs 纯 LM

    • B2: `[0 0 I]` 初始化的优势

    • B3: 接受率 → 加速比理论表

    • B4: 偏移对齐 sanity

  • 附录C. 代码位置索引

  • 附录D. 可视化与输出

    • D.1 可视化脚本

    • D.2 截图说明

    • D.3 实测数值回填

  • 0xFF 参考

0x00 概要

0.1 主要内容

K3 用一个 MTP 层(注意力骨架 = 骨干块镜像、默认 MLA、dense_ffn=False→稀疏 MoE)把训练从"一步一监督"升级为"一步两监督",训练结束把这层微调成 EAGLE-3 draft,用 [0 0 I] 特征融合 + LK 损失把"每个目标前向期望 token 数"推到理论上限附近。但"上限"只是理论——真正把草稿变成 token 需要 verify(接受/拒绝)环节,而这是kimi3-master也没给、由本项目 speculative.py 补上的部分。

另外,递归状态把候选 Token 混合在一起,不能像独立 KV 那样直接删除拒绝分支,因此必须保存状态快照或使用专门的恢复机制。

知识点:Multi-Token Prediction(多 token 预测)与 EAGLE-3 草稿模型 — K3 训练目标与投机解码加速组件

原始论文:

论文

出处

Kimi K3: Open Frontier Intelligence

(K3 技术报告,MTP 定义 §4.1.4、Table 1)

arXiv:2607.24653(2026-07-27);Kimi Team;Moonshot AI

EAGLE: Speculative Sampling Requires Rethinking Feature Uncertainty

(EAGLE-1,特征外推草稿家族鼻祖)

arXiv:2401.15077v2(2024-01);Tsinghua & MetEagle

EAGLE-3

(K3 采用的 draft 框架)

EAGLE 系列论文;K3 报告 §4.1.4 直接引用其训练协议

Block-Attention for Efficient Pre-training

(MTP 深度预测在 LLM 训练里的代表性工作)

同行文献;K3 报告 §4.1.4 引言所引的"多 token 预测"谱系

0.2 注意说明

  • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

  • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

  • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

  • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

  • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

  • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

  • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

  • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。

0x01. 演进脉络与定位

1.1 前身与谱系

阶段

代表

机制

问题/特色

单 token 预测(NTP)

GPT / LLaMA

每步预测 x[t+1]

每 token 最多一个监督信号,训练信息利用率低

多 token 预测(MTP)

DeepSeek-V3 MTP head、K3

每 step 同时监督多个未来 token

增加辅助头与额外骨干层

K3 MTP → EAGLE-3

K3 报告 §4.1.4

蒸馏后 draft 复用

"一鱼两吃":训练用 MTP、推理用 EAGLE-3

K3 MTP 谱系的一句话:把训练目标从"每一步只预测下一个 token"升级为"同时预测多步"。

MTP 是训练侧的辅助目标,可以让模型对训练目标有更深刻的理解;K3 只用一层 MTP,预测 x[t+2](主模型已预测 x[t+1])。

预训练完成后,这层变成 EAGLE-3 draft 的起点,然后被微调成 EAGLE-3 草稿模型(目标模型冻结,只训 draft 层 + 特征融合投影),转换到推理侧的投机解码加速推理——用"免费"的草稿层换取多次昂贵的目标模型前向的中和加速(训练用 MTP、推理用 EAGLE-3)。

1.2 同期竞品方案

方案

核心机制

优势

劣势

DeepSeek-V3 MTP head

额外 MTP 块预测 step-2 token

每 token 多一个监督

训练代价(一个块的前向)

EAGLE(早期)

特征融合 draft

接受率高

训练仍需 CE

EAGLE-3(K3)

融合 + LK 损失无 CE、7 步 unroll

直接优化接受率、推断 draft 内部一致

依赖 特征融合初值稳定

Medusa / MTP 草案头

多个并列 head 预测未来

简单

每个 head 独立参数、接受率低


0x02. 原理讲解

2.1 直觉类比视角

想象一个图书管理员(backbone 编码器)。平时他只干一件事:递给你一本书(token x[t]),告诉你"下一本是什么"(预测 x[t+1])。现在给他加一个问答助手(MTP 层):

  • 训练时,助手会拿到"上一本 + 你以为的下一本",要求说出"下下本"。于是管理员不仅要学会"这本书支持下一本",还要支持"下一本"本身的信息质量——同一隐藏态一下子要为两个问题服务。

  • 预训练完成后,这个助手被调教成一个"速读顾问"(EAGLE-3 draft):它能极快地连续猜出接下来 4~7 本书,主模型看到顾问的猜测只要做一次廉价核对(接受/拒绝),不接受的再亲自读。顾问猜得越准,实际读的书越少。

  • 核对这一步(verify)——主模型逐本(GPU上是并行)判断"顾问猜的对不对",猜对就照单全收,猜错就自己读一本、并退回上一本正确的地方。这正是投机解码的灵魂,现在由 speculative.py 补齐的部分。

其中有个细节:顾问起步时只信"最高层的摘要"(特征融合初值 [0 0 I]),再逐步学会参考"低层笔记"。这防止了起步时的突发扰动。

2.2 准专业水平视角

训练时(主模型 + MTP 联合前向)

    主模型: logits[t] = lm_head( norm(backbone(x)) )
            loss_lm = CE( logits[:,:-1], y[:,1:] )
    MTP 层:
       h = proj( cat( RMSNorm(hidden[:, :-1]), RMSNorm(emb(x[:,1:])) ), last=-1 )
       h = MTPBlock(h)                         # 注意力 + MoE(dense_ffn=False)
       mtp_logits = lm_head(h)                 # 共享 lm_head
       loss_mtp = CE( mtp_logits[:,:-1], y[:,2:] )


    总: loss = loss_lm + λ · loss_mtp
    • hidden[:, :-1]:backbone 最终隐藏态,丢掉最后一个位置(无目标)。

    • emb(x[:, 1:]):被预测 token 自己的嵌入(teacher-forced)——这是 MTP 与直接"多步展开"的区别。

    • 预测目标始终比主模型提前一位:主体在第 t 位预测 x[t+1],MTP 在第 t 位预测 x[t+2]。

    EAGLE-3(推断侧)

      特征融合: x_fused = W_E3( cat( low_1, mid_4, high_last ) )   # [0 0 I] 起
      单步 draft: logits = lm_head( MTPLayer( x_fused, emb(prev_draft) ) )
      投机采样 verify: 目标对草稿逐位置打分,u <= p(c)/q(c) 接受,否则残差重采

      2.3 专家视角

      • 为什么"先归一化再拼接"而非拼完再归一:MTP 层结构上是有 h_norm 和 e_norm 两个独立 RMSNorm 再 cat 的。若拼接后再整体归一,两个源之间尺度会互相污染(谁 ER 大谁主导);各归一化 → 两类特征在融合投影前的"音量"一致。

      • 为什么共享 lm_head:MTP 的 logits 直接走主模型 lm_head(model.py:362-411 对齐)。这样 MTP 层的预测空间与主模型一致,无需额外词表头。

      • EAGLE-3 的 LK 损失为何不用 KL:投机解码加速比 ∝ 接受率 Σ_x min(p,q)。对容量受限的 draft,KL 最小化不保证最大化接受率;K3 直接优化 L_LK = -log Σ_x min(p(x), q(x)),无 CE 项、温度 1。这是"优化和加速比直接相关的目标"而不是代理。

      • verify 的 lossless 本质:投机采样把"采样过程"拆成接受(保留草稿)+ 拒绝(从残差 max(p-q,0) 重采)。只要拒绝时从残差重采,最终分布与直接采目标分布 p逐 token 相同(这就是"lossless"的严格含义)。

      • [0 0 I] 初值的设计哲学:避免起步扰动——初始时融合输出 ≡ 高层特征(MTP 预训练输入),训练即等于从"纯高层"开始,逐步学低/中层。实验显示 [0 0 I] 起步 error=0 且不扰动,而随机/全零有初始扰动。

      2.4 关键信息完整性

      • SGLang 没有 K3 专属 MTP(test/registered/gb300/test_kimi_k25.py:29-31 声明 "No EAGLE/MTP support for Kimi-K2.5")。MTP 的三方核对以 kimi3-master × kimi-k3-pytorch 为主,SGLang 只做"散件核对"。

      • 重要: kimi3-master/serve/eagle3.py(140 行)经逐行核对,没有 verify 环节——只有 draft()、acceptance_rate、lk_loss、FeatureFusion、speedup_from_acceptance。因此本项目的 verify(speculative.py)是自研扩展而非移植。

      2.5 与 DeepSeek‑V4 MTP 的对比

      K3 MTPDeepSeek‑V4 MTP

      融合方式

      cat([h_norm(h), e_norm(e)]) → proj

      独立 RMSNorm → fc1 → SiLU → fc2 (mini MLP)

      是否用下一 token 嵌入

      ✅ emb(x[t+1]) 是显式输入

      ❌ 只用 hidden_states

      骨架块

      完整 Kimi3Block (attn + MoE)

      无 (只有 mini MLP)

      词表头

      共享主干 lm_head

      可选 tie_with_lm_head

      深度

      固定 1 层

      可配置 num_nextn_predict_layers

      后续用途

      微调成 EAGLE‑3 做投机解码

      无 EAGLE 变体

      K3 的 MTP 更 "重" (完整 Transformer 块),但也因此有更强的表达能力,微调成 EAGLE‑3 后能获得更高的接受率。


      0x03. 子知识点拆解 / 架构

        Multi-Token Prediction
        ├── 3.1 MTPLayer 结构(mtp_layer.py:61, 95-135)
        │    ├── h_norm / e_norm(各自 RMSNorm,:95-96)
        │    ├── proj(无 bias,2d→d,:97)
        │    ├── block(复用 Kimi3Block,:105;layer_kind 决定 KDA/MLA)
        │    └── norm(输出归一化,:135)
        ├── 3.2 Kimi3ForCausalLM 集成(model.py:300, 349, 362-413)
        │    ├── self.mtp = MTPLayer(...)(:300)
        │    ├── forward 里 loss = lm + λ·mtp(:349)
        │    └── _mtp_logits / _mtp_loss(:362 / :393,含 labels[:,2:] 对齐)
        ├── 3.3 MTPConfig(config.py:118-147 + 校验 :222-228)
        ├── 3.4 参数计数(计算见 doc,官方 config.py:609-612)
        │    └── per_mtp = attn_each + moe_total + 2d + 2d²
        ├── 3.5 EAGLE-3 系列(eagle3.py)
        │    ├── FeatureFusion [0 0 I](:73-100)
        │    ├── DraftConfig(:138-143)
        │    ├── Eagle3Draft(:146-191,draft 自回归 :174-191)
        │    ├── eagle3_feature_stack(:104-134,摊平不选择——V3 修复)
        │    ├── lk_loss / acceptance_rate(:58-70)
        │    └── speedup_from_acceptance(:194-198)
        └── 3.6 投机解码 verify 与端到端循环(speculative.py)
             ├── verify_tokens(:73-158)       纯函数接受判据
             ├── SpecDecodeStats(:163-216)    实测接受率 / tokens-per-forward
             ├── snapshot_caches / restore_caches(:221-261)  按类型快照/回滚
             ├── RecomputeBackend(:264)       无 cache 全序列重跑(oracle)
             ├── CacheRollbackBackend(:301)   增量打分
             └── SpeculativeDecoder(:329-475) 端到端循环(decode_recompute/:372、decode_rollback/:413)

        3.1 MTP 层结构(本项目 mtp/mtp_layer.py)

        子模块

        代码位置

        融合归一化 h_norm + e_norm + 无 bias 投影

        mtp_layer.py:95-97, 128-131

        骨架块(复用 Kimi3Block,KDA 或 MLA)

        mtp_layer.py:105-107

        顶层 RMSNorm → MTP 隐藏态

        mtp_layer.py:135

        缓存初始化(探 KDA/MLA 类型)

        mtp_layer.py:137-139

        3.2 主模型集成(model.py)

        组件

        代码

        构造可选 MTP 头

        model.py:302

        (self.mtp = MTPLayer(config) if config.model.mtp.enabled else None)

        forward 叠加 MTP 损失

        model.py:349-352

        (loss = loss + cfg.model.mtp.loss_weight * mtp_loss)

        MTP logits(x[t+2])

        model.py:364-393

        (_mtp_logits)

        MTP 损失(labels[:,2:] 对齐)

        model.py:395-415

        (_mtp_loss)

        解码缓存(include_mtp)

        model.py:417-448

        3.3 配置 MTPConfig(config.py:118-147)

        字段

        默认值

        说明

        enabled

        False

        (本项目)

        kimi3-master 默认 True;本项目默认关闭保持兼容(可开启)

        digit

        1

        K3 恰好 1 层(kimi3-master与 kimi-k 都硬约束)

        layer_kind

        "mla"

        "mla" 或 "kda"

        loss_weight

        0.3

        kimi-master 0.3;kimi-k-pytorch 默认 0.1

        normalize_inputs

        True

        h/e 各自 RMSNorm(对齐kimi3-master[0 0 I] 一致)

        校验(config.py:222-228):n_layers==1、layer_kind in (mla,kda)、loss_weight>=0。

        3.4 参数计数

        对齐 kimi3-masterconfig.py:609-612:

          attn_each = kda_each if layer_kind=="kda" else mla_each
          per_mtp = attn_each + moe_total + 2*dim + 2*dim*dim
          pc.mtp = per_mtp * n_layers

          本项目 mtp_param_count = 2d² + 3d(mtp_layer.py:145-156),test_mtp.py 用精确公式校验。完整骨架块参数随 Kimi3Block 规模计入总参数。

          3.5 EAGLE-3 组件(mtp/eagle3.py)

          K3 把预训练得到的 MTP 层微调为 EAGLE-3 风格的 draft model:目标模型保持冻结,只更新 draft layer 及其特征融合投影。按照 EAGLE-3 的训练时测试协议,训练时将 draft 展开 7 步;除第一步外,最新位置的目标模型特征不可用,draft 会使用自己在前几步的输出,从而复现推理时的递归起草过程。

          组件

          说明

          acceptance_rate(p,q)Σ_x min(p,q)

          ,加速 ∝ 该量

          lk_loss(p,q)-log(Σ min)

          ,温度1、无 CE

          FeatureFusion

          无 bias W_E3,初值 [0 0 I]

          eagle3_feature_stack

          摊平状态为完整出口列表(V3 修复,不再替 fuse() 做选择)

          DraftConfig

          unroll_steps=7、feature_blocks=(0,3,-1)

          Eagle3Draft

          用传入 MTP 层 + lm_head;draft() 自回归 :174-191

          speedup_from_acceptanceE[tokens] = (1-r^(L+1))/(1-r)

          3.6 投机解码 verify 组件(mtp/speculative.py)

          组件

          说明

          VerifyResult

          一轮 verify 结果(接受 token/长度/bonus/每位置比值)

          verify_tokenslossless 接受判据

          (纯函数,不碰模型)

          SpecDecodeStats

          实测接受率 / tokens-per-forward

          snapshot_caches

          深拷贝整组 cache

          restore_caches

          按类型原地回滚 cache

          RecomputeBackend

          无 cache 全序列重跑(参考 oracle)

          CacheRollbackBackend

          增量打分(配合快照回滚)

          SpeculativeDecoder

          端到端循环(两条打分路径)

          3.7 边缘处理

          • 序列太短(T<=2):_mtp_logits 返回 None,不报错(model.py:388)。

          • 多文档打包(doc_ids):_mtp_loss 用 doc_masks(doc_ids[:,:-1], T-1) 生成 MTP 的 reset/attn 掩码(model.py:381-386)。

          • ignore index:labels=-100 不参与(model.py:409)。

          3.8 MTP 代码

            class Kimi3ForCausalLM(nn.Module):
                """完整因果语言模型 = Kimi3Model + 共享权重 lm_head。


                - 解码路径核心接口:
                   ``init_caches(batch)`` 建每 block 缓存 → ``forward(tokens, caches)`` 增量前向
                   → ``generate(...)`` 生成新 token。
                """


                def __init__(self, config: Kimi3Config):
                    super().__init__()
                    self.model = Kimi3Model(config)
                    self.lm_head = nn.Linear(config.model.dim, config.model.vocab_size, bias=False)
                    # 用户后可结合的 Transformer 惯例:lm_head 通常权重与 token embedding 绑定。
                    # 本项目是独立权重(un-tied),注释备注以便后续可切换到绑。
                    self._gradient_checkpointing = False
                    # ---- Multi-Token Prediction 头(§4.1.4)---------------------------
                    # 官方 kimi3-master:`self.mtp = MTPLayer(model_cfg) if model_cfg.mtp.enabled else None`。
                    # MTP 层读 backbone 最终隐藏态 h[t] + emb(x[t+1]),预测 x[t+2];
                    # 预训练完成后即为 EAGLE-3 草稿模型的微调起点。
                    self.mtp = MTPLayer(config) if config.model.mtp.enabled else None


                @property
                def gradient_checkpointing(self) -> bool:
                    """梯度检查点开关(存储换算:前向丢弃中间激活,反向重算)。"""
                    return self._gradient_checkpointing


                def set_gradient_checkpointing(self, value: bool) -> None:
                    self._gradient_checkpointing = value


                def forward(
                    self,
                    tokens: Tensor,
                    doc_ids: Optional[Tensor] = None,
                    caches: Optional[list] = None,
                    labels: Optional[Tensor] = None,
                    return_hidden: bool = False,
                    return_mtp: bool = False,
                ):
                    """forward:核心逻辑在 ``Kimi3Model.forward``,这里只加输出头。


                    ``tokens`` 若是一次预填整段(prefill),输出是 ``(batch, seq, vocab)``;
                    若解码时逐 token 增量,则 ``tokens`` 形状 ``(batch, 1)``,输出相应为
                    ``(batch, 1, vocab)``——历史信息全都藏在 ``caches`` 里。


                    可选 MTP 训练(对齐 kimi3-master forward):传入 ``labels`` 时计算
                    LM 损失,并(若本模型配有 MTP 层)叠加 MTP 损失,最终返回一个
                    ``dict``(键 ``logits``/``loss``/``lm_loss``/``mtp_loss``/``hidden``)。
                    不传 ``labels`` 时行为与旧接口一致:只返回 logits 张量(避免破坏
                    现有调用方与测试)。


                    ``labels`` 语义:与 HF 相同,逐位置 ground truth token id;
                    ``-100`` 的位置不参与损失。主模型 logits 第 t 位预测 ``labels[:, 1:]``
                    第 t 位(shift 一位)。MTP 层的预测目标再次 shift:MTP logits 第 t 位
                    预测 ``tokens[t+2]``,对齐 ``labels[:, 2:]``。
                    """
                    h = self.model(tokens, doc_ids=doc_ids, caches=caches)
                    logits = self.lm_head(h)


                    if labels is not None:
                        b, t = tokens.shape
                        lm_loss = F.cross_entropy(
                            logits[:, :-1].reshape(-1, logits.shape[-1]).float(),
                            labels[:, 1:].reshape(-1),
                            ignore_index=-100,
                        )
                        loss = lm_loss
                        mtp_loss = None
                        if self.mtp is not None and t > 2:
                            mtp_loss = self._mtp_loss(h, tokens, labels, doc_ids)
                            loss = loss + self.model.config.model.mtp.loss_weight * mtp_loss
                        return {
                            "logits": logits,
                            "loss": loss,
                            "lm_loss": lm_loss,
                            "mtp_loss": mtp_loss,
                            "hidden": h if return_hidden else None,
                            "mtp_logits": self._mtp_logits(h, tokens, doc_ids) if return_mtp else None,
                        }


                    return logits


                def _mtp_logits(
                    self,
                    hidden: Tensor,
                    tokens: Tensor,
                    doc_ids: Optional[Tensor] = None,
                ) -> Optional[Tensor]:
                    """MTP 层前向,输出 ``x[t+2]`` 的 logits ``(batch, t-1, vocab)``。


                    对齐 kimi3-master ``model.py:_mtp_loss``:取 hidden[:, :-1]、
                    next_embeds = embed_tokens(tokens[:, 1:]),MTP 层内每位置融合
                    ``h[t] + emb(x[t+1])`` 预测 ``x[t+2]``,再经 lm_head 得到 logits。
                    若 MTP 层禁用(``self.mtp is None``)返回 None。


                    ``labels`` 的对应:MTP logits 第 t 位预测 ``x[t+2]``,所以训练目标
                    用 ``labels[:, 2:]``。shape: logits (B, T-1, V),labels2 = (B, T-2, V),
                    前者需再取 ``[:-1]`` 对齐(kimi3-master 正是这么做的)。
                    """
                    if self.mtp is None:
                        return None
                    b, t = hidden.shape[0], tokens.shape[1]
                    if t <= 2:
                        return None
                    reset_mask, attn_mask = doc_masks(
                        None if doc_ids is None else doc_ids[:, :-1], t - 1, hidden.device
                    )
                    next_embeds = self.model.tok_embed(tokens[:, 1:])
                    h = self.mtp(
                        hidden[:, :-1], next_embeds, reset_mask=reset_mask, attn_mask=attn_mask
                    )
                    return self.lm_head(h)


                def _mtp_loss(
                    self,
                    hidden: Tensor,
                    tokens: Tensor,
                    labels: Tensor,
                    doc_ids: Optional[Tensor] = None,
                ) -> Optional[Tensor]:
                    """MTP 损失(预测 x[t+2] 的交叉熵),供训练管线单独调用。


                    与 kimi3-master ``_mtp_loss`` 一致:
                    ``F.cross_entropy(mtp_logits[:, :-1], labels[:, 2:], ignore_index=-100)``。
                    返回 None 当 MTP 层禁用或序列过短。
                    """
                    logits = self._mtp_logits(hidden, tokens, doc_ids)
                    if logits is None:
                        return None
                    return F.cross_entropy(
                        logits[:, :-1].reshape(-1, logits.shape[-1]).float(),
                        labels[:, 2:].reshape(-1),
                        ignore_index=-100,
                    )

            0x04 Eagle VS MTP

            问题

            答案

            K3 先训 MTP 再后训 EAGLE?

            是

            。MTP 是预训练阶段的训练目标,EAGLE‑3 是预训练完成后从 MTP 层微调出的推理加速草稿模型

            EAGLE 和 MTP 架构相同?

            骨架相同,输入不同

            。EAGLE‑3 直接复用 MTP 层的 Kimi3Block,但增加了特征融合投影 W_E3, 输入从"骨干最终隐藏态"变为"低/中/高层特征融合"

            K3 架构中到底用 MTP 还是 EAGLE?

            两个都用,但阶段不同

            : 预训练用 MTP (训练目标),推理用 EAGLE‑3 (投机解码加速)。它们是同一条流水线的两个阶段

            4.1 K3 架构中 MTP 和 EAGLE 的角色

            一句话总结:MTP 是 K3 预训练的 "训练增强" (让骨干学得更好), EAGLE‑3 是 K3 推理的 "推理加速" (投机解码草稿模型)。两者共享同一套骨架权重,EAGLE‑3 从 MTP 毕业而来。

            4.1.1 预训练阶段: MTP 是训练目标

              # Kimi3ForCausalLM.forward() 中的 MTP 集成
              if self.mtp is not None and t > 2:
                  mtp_loss = self.mtp_loss(h, tokens, labels, doc_ids)
                  loss = lm_loss + 0.3 * mtp_loss  # 联合损失

              MTP 的作用不仅是 "多预测一个 token", 更重要的是:

              • 梯度反传进骨干: MTP 的梯度流回主干 Transformer, 相当于一种正则化

              • 让骨干学到更好的表示: 预测 x[t+2] 需要更深的上下文理解,迫使骨干编码更丰富的信息

              4.1.2 推理阶段: EAGLE‑3 是加速手段

                # 投机解码循环
                while n_new < max_new_tokens:
                    # 1. 目标模型前向 → 隐藏态 + AttnRes 特征
                    hidden = model.model(tokens)
                    # 2. EAGLE‑3 draft 起草 K 个候选 token
                    fused = draft.fuse(features)          # 特征融合
                    draft_tokens, draft_logits = draft.draft(fused, embed_fn, n_steps=K)
                    # 3. 目标模型 verify: 逐位置接受/拒绝
                    vr = verify_tokens(target_logits, draft_logits, draft_tokens)
                    # 4. 输出: 接受前缀 + bonus token
                    accepted = vr.accepted_tokens[:, :vr.n_accepted]
                    bonus = vr.bonus_token

                4.2 完整链路:MTP → EAGLE‑3 → 投机解码

                4.2.1 阶段 1: 预训练 (MTP)

                  主模型预测 x [t+1]      ← 主干 Transformer


                  MTP 层预测  x [t+2]    ← MTPLayer (骨干隐藏态,emb (x [t+1]))


                  损失 = CE_loss (x [t+1]) + λ・CE_loss (x [t+2])    λ = 0.3 (官方默认)


                  骨干 + MTP 层联合训练,MTP 梯度反传进骨干


                  ↓ 权重继承

                  4.2.2 阶段 2: EAGLE‑3 微调

                    骨干冻结,只训练:
                    - MTP 层 (现在叫 draft 层)
                    - Eagle3FeatureFusion 投影 W_E3 (新增)


                    损失 = LK_loss = -log Σ_x min (p (x), q (x))


                    直接最大化投机解码接受率,而非 KL 代理


                    训练时展开 7 步 (unroll_steps=7) , 草稿消费自己前步输出


                    ↓


                    4.2.3 阶段 3: 推理期投机解码

                    1. 目标模型前向 → 得到隐藏态 + AttnRes 特征

                    2. EAGLE‑3 draft 起草:特征融合 → 自回归生成 K 个候选 token

                    3. 目标模型 verify: 逐位置接受 / 拒绝

                    4. 接受前缀 + bonus token → 输出

                    加速比 ∝ 接受率 r, E [tokens/forward] = (1‑r^(K+1))/(1‑r)

                    4.3 MTP 层架构 (预训练期)

                    对应 K3 技术报告 §4.1.4 / Table 1。官方配置 (k3_2p8t.yaml):

                      mtp:
                        enabled: true
                        n_layers: 1        # 恰好 1 层, K3 强制校验
                        layer_kind: mla    # 内部用 GatedMLA 注意力
                        loss_weight: 0.3   # MTP 损失权重



                      4.3.1 架构细节

                      MTPLayer:

                        h_norm = RMSNorm(dim)                  # 归一化骨干隐藏态 h[t]
                        e_norm = RMSNorm(dim)                  # 归一化被预测 token 的嵌入 emb(x[t+1])
                        proj   = Linear(2*dim, dim, bias=False)# 拼接后投影回 dim
                        block  = Kimi3Block(...)               # 复用骨架块 (注意力 + MoE)
                        norm   = RMSNorm(dim)                  # 顶层输出归一化


                        forward(hidden[:, :-1], next_embeds):
                            h = proj( cat([ h_norm(hidden), e_norm(next_embeds) ], dim=-1) )
                            h = block(h)                       # x + attn(x) + ffn(x)
                            return norm(h)                     # → lm_head → x[t+2] logits



                        4.3.2 关键设计

                        1. 双输入融合: 骨干隐藏态 h[t] + 下一 token 嵌入 emb(x[t+1]), 各自 RMSNorm 后拼接投影

                        2. 分开归一再拼接: 若整体 RMSNorm, 两个来源的尺度会互相干扰;先各自归一化到单位 RMS, 拼接时两边贡献均衡

                        3. 复用完整骨架块: 内部是完整的 Kimi3Block (MLA 注意力 + StableLatentMoE) , 不是轻量 MLP

                        4. 共享词表头: MTP 输出再过主模型的 lm_head, 不单独建头

                        5. 偏移语义: 位置 t 的输出预测 x[t+2], 训练时用 labels[:, 2:] 对齐

                        4.4 EAGLE‑3 架构 (推理加速期)

                        4.4.1 与 MTP 的关系

                        EAGLE‑3 不是新架构, 而是 MTP 层 + 特征融合投影的组合:

                          class Eagle3Draft(nn.Module):
                              def __init__(self, mtp_layer, dim, lm_head, cfg):
                                  self.fusion = Eagle3FeatureFusion(dim, n_sources=3)  # 新增!
                                  self.layer = mtp_layer                                # 复用 MTP 层
                                  self.lm_head = lm_head                                # 共享词表头



                          4.4.2 创新 1: 特征融合 W_E3 (初值 [0 0 I])

                          MTP 预训练时只用骨干最终层隐藏态。EAGLE‑3 额外引入低 / 中 / 高层特征融合:

                          特征来源: Attention Residuals 的三个深度位置

                          • 第 1 个 AttnRes 块输出 → 低层特征 (局部模式)

                          • 第 4 个 AttnRes 块输出 → 中层特征 (组合模式)

                          • 最后一个 AttnRes 块输出 → 高层特征 (语义表示)

                          融合: W_E3 · [feat_low; feat_mid; feat_high]

                            W_E3` 初始化 = `[0 0 I]


                            初始融合输出 ≡ 高层特征 (= MTP 预训练时的输入) → 从 "只信高层" 逐步学到 "吸收低 / 中层特征" → 初始化不引入瞬间扰动,平滑过渡。

                              class Eagle3FeatureFusion(nn.Module):
                                  """无 bias 的 ``W_E3``,初始 ``[0 0 I]``(官方 FeatureFusion)。


                                  ``proj: (n_sources*dim) -> dim``,权重初值前 ``(n_sources-1)*dim`` 列全 0、
                                  末 ``dim`` 列单位阵。初始化后 ``fuse 输出 ≡ 高层特征``。
                                  """


                                  def __init__(self, dim: int, n_sources: int = 3):
                                      super().__init__()
                                      self.dim = dim
                                      self.n_sources = n_sources
                                      self.proj = nn.Linear(dim * n_sources, dim, bias=False)
                                      self.reset_parameters()


                                  def reset_parameters(self) -> None:
                                      with torch.no_grad():
                                          self.proj.weight.zero_()
                                          # [0 ... 0 I]:最后一个源(高层特征)恒等通过。
                                          self.proj.weight[:, -self.dim:] = torch.eye(self.dim)


                                  def forward(self, features: Sequence[Tensor]) -> Tensor:
                                      if len(features) != self.n_sources:
                                          raise ValueError(f"expected {self.n_sources} feature sources, got {len(features)}")
                                      return self.proj(torch.cat(list(features), dim=-1))


                              使用举例如下

                                    C = 64
                                    f = Eagle3FeatureFusion(C, 3)
                                    lo, mid, hi = (torch.randn(2, 3, C) for _ in range(3))
                                    out = f([lo, mid, hi])



                                4.4.3 创新 2: LK 损失 (直接优化接受率)

                                传统做法: KL 散度当代理 → 不能保证最大化接受率 (容量受限时 KL 最优 ≠ 接受率最优)

                                K3 做法: L_LK = -log Σ_x min(p(x), q(x))

                                • p = 目标模型分布,q = 草稿模型分布

                                • 直接优化决定加速比的量: acceptance_rate = Σ_x min(p(x), q(x))

                                训练时展开 7 步 (unroll_steps=7):除第一步外,草稿消费自己前一步输出 — 正是推理期 drafting 过程的镜像。

                                4.5 EAGLE-3 如何复用 MTP

                                4.5.1 整体关系图

                                整体关系图
                                整体关系图

                                4.5.2 复用点 1:整个 MTPLayer 直接作为 Eagle3Draft 的"骨架块"

                                代码:eagle3.py:154-180

                                  class Eagle3Draft(nn.Module):
                                      def __init__(self, mtp_layer: nn.Module, dim: int, lm_head: nn.Module, cfg):
                                          super().__init__()
                                          self.cfg = cfg or draft_config()
                                          self.fusion = Eagle3FeatureFusion(dim, n_sources=len(self.cfg.feature_blocks))
                                          self.layer = mtp_layer          # ★ 整个 MTPLayer 复用
                                          self.lm_head = lm_head          # ★ 共享主模型的 lm_head


                                      def forward(self, fused: Tensor, next_embeds: Tensor) -> Tensor:
                                          h = self.layer(fused, next_embeds)   # ★ 调用 MTPLayer.forward
                                          return self.lm_head(h)



                                  Eagle3Draft 本身没有新的"骨架块"——它只是给 MTPLayer 加了一个前置特征融合层(Eagle3FeatureFusion)。预训练好的 MTP 权重原封不动地被复用,训练时只微调 MTP 层 + 新加的 fusion。

                                  4.5.3 复用点 2:MTPLayer 内部的 4 个子组件

                                  代码:mtp_layer.py:94-108

                                    # MTPLayer 的内部结构
                                    self.h_norm = RMSNorm(dim, eps)              # 主干 hidden 归一化
                                    self.e_norm = RMSNorm(dim, eps)              # 未来 token embed 归一化
                                    self.proj = nn.Linear(2*dim, dim, bias=False)  # 拼接投影
                                    self.block = Kimi3Block(config, layer_idx=cfg.n_layers, use_kda=...)  # 骨架块
                                    self.norm = RMSNorm(dim, eps)                # 输出归一化



                                    EAGLE-3 完全继承这 5 个组件及其预训练权重:

                                    • h_norm / e_norm:继续用于"主干 hidden 归一化"和"下一 token embed 归一化"

                                    • proj:继续把 2C 拼接投影回 C

                                    • block(Kimi3Block):继续作为 attention + MoE 的骨架

                                    • norm:继续作为输出归一化

                                    0 个组件被替换——这就是"复用"的精确含义。

                                    4.5.4 复用点 3:forward 接口签名完全一致

                                    代码:mtp_layer.py:110-135

                                      def forward(self, hidden: Tensor, next_embeds: Tensor, ...) -> Tensor:
                                          h = self.proj(torch.cat([self.h_norm(hidden), self.e_norm(next_embeds)], dim=-1))
                                          h = self.block(h, ...)
                                          return self.norm(h)



                                      MTP 训练时(model.py 中):

                                        mtp_hidden = self.mtp_layer(
                                            hidden=backbone_hidden[:, :-1],      # 主干最后隐藏态(去尾)
                                            next_embeds=embed_tokens(x[:, 1:])   # 下一 token 嵌入
                                        )
                                        mtp_logits = lm_head(mtp_hidden)         # 预测 x[t+2]



                                        EAGLE-3 推理时(eagle3.py:178-180):

                                          def forward(self, fused: Tensor, next_embeds: Tensor) -> Tensor:
                                              h = self.layer(fused, next_embeds)   # ★ 同样的接口
                                              return self.lm_head(h)



                                          输入语义完全对应:

                                          MTP 训练时

                                          EAGLE-3 推理时

                                          来源

                                          hidden = backbone_hidden[:, :-1]fused

                                          (经 fusion 融合后)

                                          都是"上下文特征"

                                          next_embeds = emb(x[:, 1:])next_embeds = embed_fn(nxt)

                                          都是"下一 token 嵌入"

                                          4.5.5 新增的部分:Eagle3FeatureFusion

                                          EAGLE-3 唯一新增的组件是 Eagle3FeatureFusion(eagle3.py:73-96):

                                            class Eagle3FeatureFusion(nn.Module):
                                                def __init__(self, dim: int, n_sources: int = 3):
                                                    super().__init__()
                                                    self.proj = nn.Linear(dim * n_sources, dim, bias=False)
                                                    # 初始化 [0 ... 0 I]:最后一列是单位阵,等价于"只信高层特征"
                                                    self.proj.weight[:, -self.dim:] = torch.eye(self.dim)



                                            作用:把 AttnRes 状态的 3 个块表示(b_0, b_3, b_N,即第 1、4、最后块)融合成 1 个 C 维向量,作为 MTPLayer 的 hidden 输入。

                                            为什么初始化是 [0 0 I]:

                                            • MTP 预训练时只见过最终隐藏态(相当于"只用最后一个特征")

                                            • 如果初始 fusion 输出 = 随机混合,会让 MTP 层"瞬间看到陌生分布",训练不稳定

                                            • [0 0 I] 让初始 fusion 输出严格等于最后一个特征(b_N),MTP 层无缝衔接

                                            • 训练后 fusion 学到"吸收低/中层特征",平滑过渡

                                            在 Eagle3Draft.draft() 的循环里:

                                              state = fused                          # 初始 hidden(上下文特征)
                                              last = embed_fn(torch.zeros(...))      # 初始 next_embeds(起始符嵌入)
                                              for _ in range(n_steps):
                                                  logits = self.forward(state, last) # ★ 传入 state 和 last
                                                  nxt = logits[:, -1:].argmax(-1)
                                                  last = embed_fn(nxt)               # 下一步的 next_embeds = 刚起草的 token 嵌入
                                                  state = state[:, -1:]              # state 只保留最后一个位置(自回归)



                                              4.5.6 训练数据流(MTP 预训练 → EAGLE-3 微调)

                                              MTP 预训练(backbone 冻结,只训 MTP 层):

                                              MTP 预训练
                                              MTP 预训练

                                              EAGLE-3 微调(backbone 冻结,只训 MTP 层 + fusion):

                                              EAGLE-3 微调
                                              EAGLE-3 微调

                                              4.5.7 推理数据流(投机解码)

                                              • fused(hidden):固定的上下文特征,整个 draft 循环中不变(只在循环外由 backbone + fusion 算一次)

                                              • next_embeds:每步都变,是"上一步起草的 token 的嵌入"

                                              推理数据流
                                              推理数据流

                                              4.5.8 关键复用量化

                                              组件

                                              MTP 预训练

                                              EAGLE-3 微调

                                              是否复用

                                              MTPLayer.h_norm

                                              ✓

                                              ✓

                                              完全复用
                                              MTPLayer.e_norm

                                              ✓

                                              ✓

                                              完全复用
                                              MTPLayer.proj

                                              ✓

                                              ✓

                                              完全复用
                                              MTPLayer.block

                                               (Kimi3Block)

                                              ✓

                                              ✓

                                              完全复用
                                              MTPLayer.norm

                                              ✓

                                              ✓

                                              完全复用
                                              lm_head

                                              ✓

                                              ✓

                                              完全复用

                                              (共享主模型)

                                              Eagle3FeatureFusion

                                              ✗

                                              ✓

                                              新增

                                              (唯一)

                                              LK loss

                                              ✗

                                              ✓

                                              新增

                                              复用率:MTP 的 5/5 个组件全部复用,EAGLE-3 只新增 1 个 fusion 层。

                                              4.5.9 一句话总结

                                              EAGLE-3 不是"基于 MTP 的灵感重新设计",而是直接把预训练的 MTPLayer 当作草稿模型本体,只在前面加一个特征融合层把 AttnRes 的 3 层块表示融合成 MTP 层能消费的输入——预训练的 MTP 权重原封不动地被复用,训练时只微调 MTP 层 + 新加的 fusion,目标模型始终冻结。

                                              4.6 MTP 与 EAGLE‑3 的差异究竟在哪里?

                                              4.6.1 架构差异:极小 (只多一个线性层)

                                              MTP 层内部:

                                                h_norm → e_norm → cat → proj(2d→d) → Kimi3Block → norm


                                                EAGLE‑3 层内部:

                                                  W_E3(3d→d) → 同一个 MTP 层 → lm_head


                                                  EAGLE‑3 直接复用 MTP 层的 self.layer, 不新建任何 Transformer 块。唯一新增的是 Eagle3FeatureFusion: 一个 (3*dim, dim) 无 bias 线性层,初值 [0 0 I]。初始化时这个层等于恒等映射,EAGLE‑3 退化为 MTP 本身。

                                                  具体如下:

                                                  维度

                                                  MTPLayer

                                                  (预训练期)

                                                  Eagle3Draft

                                                  (推理 / 微调期)

                                                  输入来源hidden[:, :-1]

                                                   (骨干最终隐藏态) + emb(x[:, 1:]) (下一 token 嵌入)

                                                  fused

                                                   (特征融合后的低 / 中 / 高层混合特征) + next_embeds (上一步草稿 token 的嵌入)

                                                  融合方式h_norm(h)

                                                   + e_norm(e) → cat → proj(2d→d)

                                                  Eagle3FeatureFusion

                                                  : W_E3·[feat_low; feat_mid; feat_high], 初值 [0 0 I]

                                                  骨架块Kimi3Block

                                                   (MLA + MoE), layer_idx=n_layers 保证稀疏 MoE

                                                  复用同一个 MTP 层

                                                  的 self.layer, 不新建

                                                  输出头

                                                  隐藏态 → 外部 lm_head (共享主干词表头)

                                                  self.lm_head(h)

                                                   (同样是共享主干词表头)

                                                  训练目标cross_entropy(mtp_logits[:, :-1], labels[:, 2:])

                                                  , 权重 loss_weight=0.3

                                                  lk_loss = -log Σ min(p, q)

                                                   (直接最大化接受率)

                                                  训练方式

                                                  骨干 + MTP 层联合训练(MTP 梯度反传进骨干)

                                                  骨干冻结, 只训 draft 层 + 特征融合投影

                                                  推理行为

                                                  不直接用于推理

                                                  draft()

                                                   自回归起草:第一步后草稿消费自己前一步的输出

                                                  特征深度

                                                  只用骨干最终层隐藏态

                                                  取 AttnRes 第 1/4 / 末个块的输出 (低 / 中 / 高层三层特征)

                                                  初始化

                                                  标准 PyTorch 初始化

                                                  W_E3 = [0 0 I]

                                                  : 初始时融合输出 ≡ 高层特征 (= MTP 预训练输入), 平滑过渡

                                                  新增参数

                                                  无 (相对于主干)

                                                  Eagle3FeatureFusion

                                                  : W_E3 为 (3*dim, dim) 无 bias 线性层

                                                  结论:架构几乎相同,差异 ≈ 1 个线性投影层。

                                                  4.6.2 训练模式差异:中等

                                                  MTP

                                                  EAGLE‑3

                                                  骨干

                                                  联合训练

                                                  , 梯度反传进骨干

                                                  冻结

                                                  , 不动骨干

                                                  损失函数

                                                  cross_entropy

                                                   (标准 CE)

                                                  lk_loss = -log Σ min(p,q)

                                                   (直接优化接受率)

                                                  训练数据

                                                  正常预训练语料

                                                  目标模型的输出分布 (草稿展开多步自回归)

                                                  训练目标

                                                  让骨干学到更好的表示

                                                  让草稿分布逼近目标分布 (但用 LK 而非 KL)

                                                  结论: 训练方式完全不同,但这是 "同一套权重的两种用法", 不是两套独立架构。

                                                  4.6.3 思维差异:根本 (这是最核心的差异)

                                                  • MTP 的思维: 我是训练工具。我的存在是为了让骨干 Transformer 学到更好的表示 — 预测 x[t+2] 迫使模型编码更深的上下文,梯度反传回骨干相当于正则化。我预测得准不准不重要,重要的是我的梯度让骨干变强了。

                                                  • EAGLE‑3 的思维: 我是推理工具。骨干已经训练好了 (冻结), 我的任务是快速生成 "足够像目标模型" 的候选 token, 让目标模型批量验证而非逐个生成。我不需要完美,我需要接受率高— 每多一个被接受的 token, 就省一次目标模型前向。

                                                  用一句话说:MTP 是 "用多预测一个 token 来让骨干学得更好"。EAGLE‑3 是 "用骨干的多层特征来让自己猜得足够准以加速推理"。同一个层,两种哲学。

                                                  4.6.4 差异量级总结

                                                  • 架构差异:极小 (1 个线性层,初始化时退化为 MTP)

                                                  • 训练差异:中等 (冻结 vs 联合,CE vs LK,但权重共享)

                                                  • 思维差异:根本 (训练增强 vs 推理加速,完全不同的目标函数)

                                                  所以差异究竟在哪里 — 差异在思维。架构上它们几乎是同一个东西,这正是 K3 设计的精妙之处:一个 MTP 层,预训练时当正则化器用,推理时当草稿模型用,一鱼两吃。

                                                  0x05 子知识点深度分析

                                                  5.0 共享抽象与统一符号

                                                  关键符号:h = backbone 最终隐藏态 (B,T,d);V = 词表大小;MTP 融合输入来自 h[:, :-1] 与 emb(x[:, 1:])(均 (B,T-1,d));W_E3 为特征融合投影 (3d→d);p / q = 目标 / 草稿逐位置分布;r = 接受率;L = draft 草稿步数;λ = loss_weight。

                                                  为什么"预测 x[t+2]"而非 "x[t+1]":主模型已在第 t 位预测 x[t+1] 并拿到梯度;MTP 若也预测 x[t+1] 就与主模型重复且无信息增益。MTP 利用 x[t+1] 已知这个前提(teacher-forced),让 backbone 同一隐藏态"多出一个采样点",两个目标在共享隐藏状态上互相给梯度。

                                                  统一抽象:投机解码把"目标模型单步前向产 token"抽象成"草稿多步产候选 + 一次 verify 收敛为 1 个以上 token"。所有子知识点共享同一套验证链路:目标打分 → verify → 接受前缀 + bonus。

                                                  5.1 子知识点:MTP 层结构(融合 + 一层 backbone 镜像)

                                                  5.1.1 要解决的问题

                                                  MTP 想解决的,是 NTP 训练"每 token 只有一个监督信号"的信息利用率瓶颈。主干前向一次(93 层)却只为下一步产出 1 个 CE 监督,是昂贵的浪费。我们想在几乎不增加推理成本的前提下,让同一份主干计算同时服务多个未来 token 的预测,从而压榨每步前向的信息量。

                                                  5.1.2 技术难点

                                                  1. 不破坏主干:不能为了多预测一步而改动 backbone 本身(否则推理成本上升)。

                                                  2. 标签偏移对齐:多预测一步意味着目标的"相位"要整体后移,极易对错。

                                                  3. 额外的网络开销:加一个头就需要额外一层的前向/反向,训练吞吐会下降。

                                                  5.1.3 解决方案总体思路

                                                  加一个旁路 MTP 头:它镜像 backbone 的一个块(同样结构、独立参数),读取 h[t] 与 emb(x[t+1]),输出预测 x[t+2]。这样主干一个隐藏态被 loss_lm 和 loss_mtp 两个目标共同训练。训练完这个头不浪费——它是 EAGLE-3 draft 的微调起点。

                                                  5.1.4 思路背后的原理

                                                  • 直觉:管理员同时回答"下下本"。

                                                  • 准专业:h = proj(cat(RMSNorm(hidden[:-1]), e_norm(emb(x[1:])))) → 一层注意力+MoE 块 → 输出 norm。所有参数权重独立(Kimi3Block 从零训)。

                                                  • 专家:MTP layer 镜像骨干块(Kimi3Block(layer_kind)),让 draft 训练时"和 backbone 共享同一套注意算子先验",从而微调 EAGLE-3 时收敛快。dense_ffn=False → 稀疏 MoE,与主干浅层之后的分布一致。

                                                  5.1.5 架构与类依赖关系

                                                    MTPLayer (mtp_layer.py:61)
                                                     ├─ h_norm  RMSNorm(dim)          # :95 隐藏态归一
                                                     ├─ e_norm  RMSNorm(dim)          # :96 嵌入归一
                                                     ├─ proj    Linear(2d→d, bias=F)  # :97 融合投影
                                                     ├─ block   Kimi3Block(config, layer_idx=n_layers, use_kda=(kind=="kda"))  # :105
                                                     │           ├─ attn: KDA 或 MLA   # 依赖 layer_kind
                                                     │           └─ ffn: Dense/MoE     # layer_idx>=n_dense_layers → MoE
                                                     └─ norm    RMSNorm(dim)          # :135 输出归一
                                                    依赖:MTPLayer → Kimi3Block → {KimiDeltaAttention | GatedMLA, StableLatentMoE}
                                                          被 Kimi3ForCausalLM.__init__ 实例化(model.py:302)


                                                    5.1.6 数据流(张量形状逐步)

                                                      hidden (B,T,d)        next_embeds=emb(x[:,1:]) (B,T-1,d)
                                                         │  hidden[:, :-1] (B,T-1,d)     │  [1:] (B,T-1,d)
                                                         ▼ h_norm                        ▼ e_norm
                                                      cat ──────────────────────────►  (B,T-1,2d)
                                                         ▼ proj (2d→d)                 (B,T-1,d)
                                                         ▼ block (attn+ffn, 残差)       (B,T-1,d)
                                                         ▼ norm                        (B,T-1,d)  → 喂 lm_head


                                                      5.1.7 执行流(时序/调用链)

                                                        Kimi3ForCausalLM.forward (model.py:312)
                                                         └─ model.model(tokens) → hidden (B,T,d)
                                                         └─ [if mtp & T>2] self.mtp(hidden[:,:-1], next_embeds, reset_mask, attn_mask)
                                                              → mtp_layer.forward (mtp_layer.py:110)
                                                                 h_norm+e_norm → cat → proj → block → norm
                                                         └─ lm_head(h) → mtp_logits (B,T-1,V)


                                                        5.1.8 关键类/函数职责表

                                                        名称

                                                        file:line

                                                        输入 → 输出

                                                        职责

                                                        MTPLayer.__init__

                                                        mtp_layer.py:86-108

                                                        config → 子层

                                                        构建融合 + 骨架块

                                                        MTPLayer.forward

                                                        mtp_layer.py:110-135

                                                        (hidden, next_embeds) → (B,T-1,d)

                                                        融合 + 一层块变换

                                                        MTPLayer.init_cache

                                                        mtp_layer.py:137-139

                                                        batch → cache

                                                        探块内注意力类型建缓存

                                                        mtp_param_count

                                                        mtp_layer.py:145-156

                                                        dim → int

                                                        计算 MTP 额外参数

                                                        Kimi3ForCausalLM.__init__

                                                        model.py:302

                                                        config

                                                        条件实例化 self.mtp

                                                        5.1.9 代码

                                                          # -*- coding: utf-8 -*-
                                                          """Multi-Token Prediction(MTP)头:K3 的双 token 并行预测层。


                                                          MTP 对应 K3 技术报告 **§4.1.4(Multi-Token Prediction)** 与 **Table 1**。
                                                          主模型每个位置预测 ``x[t+1]``,MTP 层额外读上一步的隐藏态与下一步的嵌入,
                                                          预测 ``x[t+2]``,从而让一个训练步同时监督"两 token"。预训练完成后,这层
                                                          正是 EAGLE-3 草案模型(speculative decoding 草稿)的微调起点。


                                                          kimi3-master 结构(kimi3/model.py:237-265):


                                                              MTPLayer:
                                                                h_norm = RMSNorm(dim)            # 归一化 backbone 隐藏态 h[t]
                                                                e_norm = RMSNorm(dim)           # 归一化被预测 token 的嵌入 emb(x[t+1])
                                                                proj   = Linear(2*dim, dim, bias=False)   # 拼接后投影回 dim
                                                                block  = Kimi3Block(...)        # 复用骨架块(dense_ffn=False -> 稀疏 MoE)
                                                                norm   = RMSNorm(dim)           # 顶层输出归一化,喂给 lm_head


                                                            forward(hidden[:, :-1], next_embeds):
                                                                h  = proj( cat([ h_norm(hidden), e_norm(next_embeds) ], dim=-1) )
                                                                h  = h + block.attend(h)
                                                                h  = h + block.feed_forward(h).hidden
                                                                return norm(h)


                                                          本项目 ``Kimi3Block`` 的 forward 接口是 ``x + attn + ffn`` 一体化(紧
                                                          ``Kimi3Block.forward``),与官方的 ``attend(...)``/``feed_forward(...)`` 分离接口
                                                          等价:MTP 层直接复用 ``Kimi3Block(config, layer_idx, use_kda=...)`` 即可,
                                                          ``layer_idx >= n_dense_layers`` 保证 FFN 走稀疏 MoE(官方 ``dense_ffn=False``
                                                          语义)。


                                                          与训练相关的偏移语义(决定答案在哪一位):
                                                            - 输入 ``hidden`` 是 backbone 的最终隐藏态 ``(B, T, D)``,第 t 个位置刻画
                                                              输入 token ``x[t]`` 及其上文;
                                                            - 输入 ``next_embeds = embed_tokens(x[:, 1:])``(shift 一位的嵌入);
                                                            - 拼接投影后逐位置融合,经过一个骨架块,输出 ``(B, T-1, C)``,其第 t 个
                                                              位置预测 ``x[t+2]``(t+1 的嵌入已知,故天然快一拍)。
                                                            - ``Kimi3ForCausalLM._mtp_loss`` 里用 ``labels[:, 2:]`` 对齐这个输出
                                                              (见 model.py / mtp 集成)。


                                                          数值注意:kimi3-master 与 kimi-k3-pytorch 的 MTP 输出**都要再过一遍
                                                          ``lm_head``**(共享主模型词表头)。本模块只输出隐藏态;套 lm_head 的循环
                                                          由上层 ``Kimi3ForCausalLM`` 完成,与 vision 塔同样的"投影到骨干 dim 后由
                                                          主干头接管"的习惯。
                                                          """


                                                          class MTPLayer(nn.Module):
                                                              """K3 Multi-Token Prediction 层(对齐 kimi3-master ``MTPLayer``)。


                                                              一个"把第 t 个 backbone 隐藏态与第 t+1 个 token 嵌入融合、预测第 t+2 个
                                                              token"的轻量解码器层。结构与一个正常骨架块一致,但输入来自**拼接**:


                                                              - ``source_hidden``:主干最后一层输出 ``hidden[:, :-1]``
                                                                (``(B, T-1, C)``,丢掉最后一个位置);
                                                              - ``future_embeddings``:``embed_tokens(x[:, 1:])``
                                                                (``(B, T-1, C)``,下一 token 的嵌入)。


                                                              两个输入在**各自 RMSNorm**后拼接成 ``(B, T-1, 2C)``,经无 bias 的
                                                              投影融合回 ``C`` 维,再过一个骨架块(注意力 + MoE),最后再 RMSNorm,
                                                              得到 ``(B, T-1, C)`` 的 MTP 隐藏态。上层接 lm_head 得到 ``x[t+2]`` 的
                                                              logits。


                                                              为什么 h 与 e 要**分开归一化后再拼接**(而不是拼了再规范化):
                                                              拼接发生在 2C 维,若整体 RMSNorm,两个来源的尺度会互相干扰;先各自
                                                              归一化到单位 RMS,拼接时两边贡献均衡,这正是 kimi3-master
                                                              ``h_norm/e_norm`` 与 kimi-k3-pytorch ``KimiMTPFusion`` 的做法。


                                                              MTP 层可额外接收与骨架一致的 ``reset_mask``/``attn_mask``(在多文档
                                                              打包场景下用)——因为它内部就是 ``Kimi 3Block``,掩码语义自然继承。
                                                              """


                                                              def __init__(self, config: Kimi3Config, layer_kind: Optional[str] = None):
                                                                  super().__init__()
                                                                  from ..model import Kimi3Block  # 延迟导入,避免循环依赖
                                                                  cfg = config.model
                                                                  kind = layer_kind or cfg.mtp.layer_kind
                                                                  dim = cfg.dim
                                                                  eps = cfg.norm_eps


                                                                  # ---- 融合子层:各自归一化 + 无 bias 拼接投影 ---------------------
                                                                  self.h_norm = RMSNorm(dim, eps)
                                                                  self.e_norm = RMSNorm(dim, eps)
                                                                  self.proj = nn.Linear(2 * dim, dim, bias=False)


                                                                  self.layer_kind = kind
                                                                  # ---- 骨架块:复用主干 Kimi3Block --------------------------------
                                                                  # layer_idx 越大越能避开 early dense FFN 分支:传 cfg.n_layers 保证
                                                                  # “layer_idx >= n_dense_layers”,从而走进 StableLatentMoE 分支
                                                                  # (官方 dense_ffn=False -> 稀疏 MoE)。
                                                                  # use_kda 由 layer_kind 决定: "kda" -> KDA 注意力,“mla” -> GatedMLA。
                                                                  self.block = Kimi3Block(
                                                                      config, layer_idx=cfg.n_layers, use_kda=(kind == "kda")
                                                                  )
                                                                  self.norm = RMSNorm(dim, eps)


                                                              def forward(
                                                                  self,
                                                                  hidden: Tensor,
                                                                  next_embeds: Tensor,
                                                                  *,
                                                                  reset_mask: Optional[Tensor] = None,
                                                                  attn_mask: Optional[Tensor] = None,
                                                              ) -> Tensor:
                                                                  """输入 ``hidden``/``next_embeds`` 均为 ``(B, T, C)``,输出 ``(B, T, C)``。


                                                                  ``hidden`` 常为主干最终隐藏态 ``h[:, :-1]``,``next_embeds`` 常为
                                                                  ``emb(x[:, 1:])``,二者必须等长(commit)。
                                                                  """
                                                                  b, t, c = hidden.shape
                                                                  if next_embeds.shape[:2] != (b, t) or next_embeds.shape[2] != c:
                                                                      raise ValueError(
                                                                          f"hidden/next_embeds must share shape (B, T, C); got "
                                                                          f"{tuple(hidden.shape)} vs {tuple(next_embeds.shape)}"
                                                                      )
                                                                  if self.h_norm is not None:
                                                                      h = self.proj(torch.cat([self.h_norm(hidden), self.e_norm(next_embeds)], dim=-1))
                                                                  else:
                                                                      h = self.proj(torch.cat([hidden, next_embeds], dim=-1))
                                                                  # 骨架块:x + attn(x) + ffn(x)。reset_mask/attn_mask 透传(打包场景)。
                                                                  h = self.block(h, reset_mask=reset_mask, attn_mask=attn_mask)
                                                                  return self.norm(h)


                                                              def init_cache(self, batch: int, *, device=None, dtype=torch.float32):
                                                                  """增量推理 cache:取决于 MTP 块内注意力类型(KDA/MLA)。"""
                                                                  return self.block.attn.init_cache(batch, device=device, dtype=dtype)


                                                              def extra_repr(self) -> str:
                                                                  return f"layer_kind={self.layer_kind}, proj_bias=False"


                                                          def mtp_param_count(config: Kimi3Config) -> int:
                                                              """MTP 层参数量的解析公式(对齐 kimi3-master config.py kda/mla_each)。


                                                              仅计 MTP 层自身的参数(不含主干):3×RMSNorm → ~3*(C+C+C)=3C,
                                                              proj 无 bias 投影 → 2C*C,骨架块(一个 KDA 或一个 MLA + 一个 MoE)。
                                                              精确数字因骨架结构而异,这里给的是一个便于 demo/t 断言的下界:
                                                              proj 一项就是 2C^2。
                                                              """
                                                              cfg = config.model
                                                              dim = cfg.dim
                                                              # proj 占大头 2*dim*dim(无 bias);加上 3 个 RMSNorm gain。
                                                              return 2 * dim * dim + 3 * dim


                                                          def mtp_layer_weight_names(config: Kimi3Config) -> list[str]:
                                                              """MTP 层的可学习权重名前缀(用于文档核对与测试断言)。"""
                                                              return [
                                                                  "h_norm.weight", "e_norm.weight", "proj.weight",
                                                                  "block.attn_norm.weight", "block.ffn_norm.weight", "norm.weight",
                                                              ]


                                                          5.1.10 对比基线与实测数据

                                                          • 无 MTP(纯 NTP):每 token 一个监督。

                                                          • MTP:主模型 + 辅助一层,每 token 两个监督。

                                                          • 收益:同一隐藏态被两个目标训练,隐含正则化;lambda_mtp*mtp 公式即 ntp + λ·mtp。代价:每 step 多一次 MTP 层前向/反向。

                                                          • 与外 ev 对比(kimi3-master vs kimi-k-pytorch):

                                                          构型

                                                          kimi3-master

                                                          kimi-k3-pytorch

                                                          本项目

                                                          MTP 交叉层

                                                          单块,KDA/MLA(默认 mla)

                                                          独立"整组 3×KDA+1×Gated-MLA"

                                                          单块(可切 kda/mla)

                                                          偏置

                                                          全无 bias

                                                          fusion_bias=False

                                                          无 bias

                                                          FFN

                                                          dense_ffn=False

                                                          →MoE

                                                          use_dense_ffn=False

                                                          →StableLatentMoE

                                                          MoE

                                                          loss_weight

                                                          0.3

                                                          0.1

                                                          0.3

                                                          5.1.11 反方辩手 / 边界条件

                                                          • a) 最强反对:训练开销大,多 token 预测可能无边际收益。

                                                          • b) 若失败,最可能错:窄模型/少数据上信号饱和,MTP 无额外信息。

                                                          • c) 胜出:数据量大、backbone 容量高(K3 2.8T);失败:超小型任务(教学场景)。

                                                          • d) 更稳健:以极小的 loss_weight(0.1~0.3)起步。

                                                          • e) 受影响方:训练吞吐(每步多一箭)。


                                                          5.2 子知识点:偏移对齐(h[t] + emb(x[t+1]) → logits[t]=x[t+2])

                                                          5.2.1 要解决的问题

                                                          MTP 的输入是"当前隐藏态 + 未来 token 嵌入",输出要预测"更未来的 token"。如果偏移对错,模型会去学错误的目标(比如重复主模型的 x[t+1]),整个 MTP 头形同虚设。

                                                          5.2.2 技术难点

                                                          1. 输入侧双 shift:hidden[:, :-1] 与 emb(x[:, 1:]) 要严格错开一位,让"当前位置"恰好看到 x[t+1]。

                                                          2. 输出侧再 shift:logits 与 labels 也要对齐(logits[:, :-1] ↔ labels[:, 2:]),三维形状要逐一核对。

                                                          3. Teacher-forcing 泄漏:直接给模型真实 x[t+1],可能让模型学会"复制"而非"预测"。

                                                          5.2.3 解决方案总体思路

                                                          利用 teacher-forcing 的"已知 x[t+1]"作为前提:MTP 前向输入 hidden[:, :-1](丢弃最后位置)+ next_emb = emb(x[:,1:])。两层 shift 后,输出第 t 个位置对应"输入第 t 个 backbone 隐藏态 + 第 t+1 个 token 嵌入",因此它已经知道 x[t+1],预测目标 x[t+2]。对齐:logits[:, :-1] ↔ labels[:, 2:]。

                                                          5.2.4 思路背后的原理

                                                          • 直觉:告诉助手"我读到了上一本(x[t])和下一本(x[t+1])是什么",让他猜下下本(x[t+2])。

                                                          • 准专业:维度——MTP logits (B,T-1,V),labels2 (B,T-2),前者截掉末尾一位对齐。若错误用 x[t] 的嵌入(无 shift),退化成"预测 x[t+1]",与主模型重复。

                                                          • 专家:这本质是"多步展开 vs teacher-forced 一步"的权衡。多步展开会累积误差且无法并行;teacher-forced 借用真实 token 作为条件,使每个位置的监督互不干扰,是训练期的高效形态(计算形态通识)。

                                                          5.2.5 架构与类依赖

                                                          无独立类;逻辑在 Kimi3ForCausalLM._mtp_logits(model.py)内完成 shift 与拼接。

                                                          5.2.6 数据流

                                                            tokens (B,T)         hidden (B,T,d)
                                                               │ x[:,1:]               │ [:, :-1]
                                                               ▼ tok_embed (B,T-1,d)   ▼ (B,T-1,d)
                                                               └──→ MTPLayer ──► (B,T-1,d) ──► lm_head ──► mtp_logits (B,T-1,V)
                                                            labels (B,T) → [:,2:] (B,T-2)  对齐 logits[:, :-1] (B,T-2,V)


                                                            5.2.7 执行流

                                                              model.forward (model.py:341, 当 labels 且 T>2)
                                                               └─ mtp_loss = self._mtp_loss(hidden, tokens, labels, doc_ids)   # :351
                                                                    └─ logits = self._mtp_logits(hidden, tokens, doc_ids)      # :408
                                                                    └─ CE(logits[:, :-1], labels[:, 2:], ignore_index=-100)    # :411-415


                                                              5.2.8 关键函数职责表

                                                              名称

                                                              file:line

                                                              输入 → 输出

                                                              职责

                                                              _mtp_logits

                                                              model.py:364-393

                                                              (hidden,tokens,doc_ids) → (B,T-1,V)/None

                                                              shift + 融合 + 前向 + lm_head

                                                              _mtp_loss

                                                              model.py:395-415

                                                              (hidden,tokens,labels,doc_ids) → loss/None

                                                              用 labels[:,2:] 算 CE

                                                              doc_masks

                                                              model.py:24-53

                                                              doc_ids → reset/attn mask

                                                              多文档打包掩码

                                                              5.2.9 代码

                                                                class Kimi3ForCausalLM(nn.Module):
                                                                    """完整因果语言模型 = Kimi3Model + 共享权重 lm_head。


                                                                    - 解码路径核心接口:
                                                                       ``init_caches(batch)`` 建每 block 缓存 → ``forward(tokens, caches)`` 增量前向
                                                                       → ``generate(...)`` 生成新 token。
                                                                    """


                                                                    def __init__(self, config: Kimi3Config):
                                                                        super().__init__()
                                                                        self.model = Kimi3Model(config)
                                                                        self.lm_head = nn.Linear(config.model.dim, config.model.vocab_size, bias=False)
                                                                        # 用户后可结合的 Transformer 惯例:lm_head 通常权重与 token embedding 绑定。
                                                                        # 本项目是独立权重(un-tied),注释备注以便后续可切换到绑。
                                                                        self._gradient_checkpointing = False
                                                                        # ---- Multi-Token Prediction 头---------------------------
                                                                        # 官方 kimi3-master:`self.mtp = MTPLayer(model_cfg) if model_cfg.mtp.enabled else None`。
                                                                        # MTP 层读 backbone 最终隐藏态 h[t] + emb(x[t+1]),预测 x[t+2];
                                                                        # 预训练完成后即为 EAGLE-3 草稿模型的微调起点。
                                                                        self.mtp = MTPLayer(config) if config.model.mtp.enabled else None


                                                                    def forward(
                                                                        self,
                                                                        tokens: Tensor,
                                                                        doc_ids: Optional[Tensor] = None,
                                                                        caches: Optional[list] = None,
                                                                        labels: Optional[Tensor] = None,
                                                                        return_hidden: bool = False,
                                                                        return_mtp: bool = False,
                                                                    ):
                                                                        """forward:核心逻辑在 ``Kimi3Model.forward``,这里只加输出头。


                                                                        ``tokens`` 若是一次预填整段(prefill),输出是 ``(batch, seq, vocab)``;
                                                                        若解码时逐 token 增量,则 ``tokens`` 形状 ``(batch, 1)``,输出相应为
                                                                        ``(batch, 1, vocab)``——历史信息全都藏在 ``caches`` 里。


                                                                        可选 MTP 训练(对齐 kimi3-master forward):传入 ``labels`` 时计算
                                                                        LM 损失,并(若本模型配有 MTP 层)叠加 MTP 损失,最终返回一个
                                                                        ``dict``(键 ``logits``/``loss``/``lm_loss``/``mtp_loss``/``hidden``)。
                                                                        不传 ``labels`` 时行为与旧接口一致:只返回 logits 张量(避免破坏
                                                                        现有调用方与测试)。


                                                                        ``labels`` 语义:与 HF 相同,逐位置 ground truth token id;
                                                                        ``-100`` 的位置不参与损失。主模型 logits 第 t 位预测 ``labels[:, 1:]``
                                                                        第 t 位(shift 一位)。MTP 层的预测目标再次 shift:MTP logits 第 t 位
                                                                        预测 ``tokens[t+2]``,对齐 ``labels[:, 2:]``。
                                                                        """
                                                                        h = self.model(tokens, doc_ids=doc_ids, caches=caches)
                                                                        logits = self.lm_head(h)


                                                                        if labels is not None:
                                                                            b, t = tokens.shape
                                                                            lm_loss = F.cross_entropy(
                                                                                logits[:, :-1].reshape(-1, logits.shape[-1]).float(),
                                                                                labels[:, 1:].reshape(-1),
                                                                                ignore_index=-100,
                                                                            )
                                                                            loss = lm_loss
                                                                            mtp_loss = None
                                                                            if self.mtp is not None and t > 2:
                                                                                mtp_loss = self._mtp_loss(h, tokens, labels, doc_ids)
                                                                                loss = loss + self.model.config.model.mtp.loss_weight * mtp_loss
                                                                            return {
                                                                                "logits": logits,
                                                                                "loss": loss,
                                                                                "lm_loss": lm_loss,
                                                                                "mtp_loss": mtp_loss,
                                                                                "hidden": h if return_hidden else None,
                                                                                "mtp_logits": self._mtp_logits(h, tokens, doc_ids) if return_mtp else None,
                                                                            }


                                                                        return logits


                                                                    def _mtp_logits(
                                                                        self,
                                                                        hidden: Tensor,
                                                                        tokens: Tensor,
                                                                        doc_ids: Optional[Tensor] = None,
                                                                    ) -> Optional[Tensor]:
                                                                        """MTP 层前向,输出 ``x[t+2]`` 的 logits ``(batch, t-1, vocab)``。


                                                                        对齐 kimi3-master ``model.py:_mtp_loss``:取 hidden[:, :-1]、
                                                                        next_embeds = embed_tokens(tokens[:, 1:]),MTP 层内每位置融合
                                                                        ``h[t] + emb(x[t+1])`` 预测 ``x[t+2]``,再经 lm_head 得到 logits。
                                                                        若 MTP 层禁用(``self.mtp is None``)返回 None。


                                                                        ``labels`` 的对应:MTP logits 第 t 位预测 ``x[t+2]``,所以训练目标
                                                                        用 ``labels[:, 2:]``。shape: logits (B, T-1, V),labels2 = (B, T-2, V),
                                                                        前者需再取 ``[:-1]`` 对齐(kimi3-master 正是这么做的)。
                                                                        """
                                                                        if self.mtp is None:
                                                                            return None
                                                                        b, t = hidden.shape[0], tokens.shape[1]
                                                                        if t <= 2:
                                                                            return None
                                                                        reset_mask, attn_mask = doc_masks(
                                                                            None if doc_ids is None else doc_ids[:, :-1], t - 1, hidden.device
                                                                        )
                                                                        next_embeds = self.model.tok_embed(tokens[:, 1:])
                                                                        h = self.mtp(
                                                                            hidden[:, :-1], next_embeds, reset_mask=reset_mask, attn_mask=attn_mask
                                                                        )
                                                                        return self.lm_head(h)


                                                                    def _mtp_loss(
                                                                        self,
                                                                        hidden: Tensor,
                                                                        tokens: Tensor,
                                                                        labels: Tensor,
                                                                        doc_ids: Optional[Tensor] = None,
                                                                    ) -> Optional[Tensor]:
                                                                        """MTP 损失(预测 x[t+2] 的交叉熵),供训练管线单独调用。


                                                                        与 kimi3-master ``_mtp_loss`` 一致:
                                                                        ``F.cross_entropy(mtp_logits[:, :-1], labels[:, 2:], ignore_index=-100)``。
                                                                        返回 None 当 MTP 层禁用或序列过短。
                                                                        """
                                                                        logits = self._mtp_logits(hidden, tokens, doc_ids)
                                                                        if logits is None:
                                                                            return None
                                                                        return F.cross_entropy(
                                                                            logits[:, :-1].reshape(-1, logits.shape[-1]).float(),
                                                                            labels[:, 2:].reshape(-1),
                                                                            ignore_index=-100,
                                                                        )              


                                                                5.2.10 对比基线与实测数据

                                                                model.py:362-411 + discussion.py:E4 验证:更换 next_emb 为不对齐的嵌入,MTP logits 平均 |Δ|=0.5494(对 x[t+1] 极敏感),确认对齐语义无误;输出形状 (B=2, T-1=7, V=64)(实测)。

                                                                5.2.11 反方辩手 / 边界条件

                                                                • a) 最强反对:teacher-forcing 泄漏——x[t+1] 的正确性直接炒作结果,无需真的"下一步"全模型。

                                                                • b) 失败点:模型可能只学"复制 x[t+1] 到 x[t+2]"而非语义预测。

                                                                • c) 胜出:若 x[t+1] 嵌入携带大量语义上下文;失败:训练只有大量不相干位置。

                                                                • d) 更稳健:MTP 的输入可与 X 后对换正则(未来 research)。

                                                                • 完成度:已实现并运行通过(E4 实测回填)。

                                                                5.3 子知识点:EAGLE-3 特征融合 [0 0 I]

                                                                • "特征融合"= 把目标模型低/中/高三层隐藏表示拼起压回 d 维作为草稿输入。

                                                                • [0 0 I] 是 W_E3 初值:W_E3=[0|0|I] → 初始 fused=high(MTP 预训练输入),避免微调起步扰动。

                                                                • "选三个"现在唯一在 Eagle3Draft.fuse(),由 DraftConfig.feature_blocks=(0,3,-1) 驱动;eagle3_feature_stack 只摊平不选择。

                                                                • 实测(E2):[0 0 I] 初值 error=0 且恒 0;随机/全零有初始扰动后收敛。

                                                                5.3.1 要解决的问题

                                                                草稿模型要"猜得快且像"目标。它需要的输入,比目标 lm_head 消费的 high(最终隐藏态)信息更完整——high 为了预测下一 token 已高度压缩,丢掉了拼写、常见搭配、格式模板等表层线索。这些线索在低/中层还活着。所以草稿需要一个"多深度融合"的视图。

                                                                5.3.2 技术难点

                                                                1. 选哪些层:93 层骨干可选出口很多,选多了冗余、选少了缺信息。

                                                                2. 融合初值:草稿是从预训练 MTP 层微调来的,MTP 层只见过 high 这个输入分布。若 W_E3 随机初始化,EAGLE-3 微调第一步草稿就收到从未见过的输入,预训练学到的东西瞬间失效。

                                                                3. 层间尺度:不同深度特征的尺度差异大,直接拼接会被大尺度者主导。

                                                                5.3.3 解决方案总体思路

                                                                取低/中/高三个出口(第 1 / 第 4 / 末个 AttnRes 块,feature_blocks=(0,3,-1)),cat 后过无 bias 投影 W_E3: 3d→d。W_E3 初值设为 [0 0 I]:最后 d 列单位阵、前 2d 全零 → 初始时 fuse 输出 ≡ 高层特征,即 MTP 预训练时的输入。训练逐步学用低/中,避免起步扰动。

                                                                5.3.4 思路背后的原理

                                                                • 直觉:顾问起步只信"最高层摘要",再学会翻"低层笔记",而不是上来就乱翻把所有笔记搅在一起。

                                                                • 准专业:W_E3 = [ 0_{d×d} | 0_{d×d} | I_{d×d} ] → fused = W_E3·[low;mid;high] = high。训练后低/中列学到非零值,融合才开始吸收低/中信息。

                                                                • 专家:这是"平滑扩展模型输入"的通用技巧(同类思想:ControlNet 的零卷积、LoRA 的 B=0 初始化、K3 MTP 的 residual 结构)。[0 0 I] 保证微调第 0 步完全无扰动,由梯度自己决定"要不要、以多大权重"把低/中掺进来。

                                                                5.3.5 架构与类依赖

                                                                  Eagle3FeatureFusion (eagle3.py:73)
                                                                   ├─ proj Linear(dim*n_sources → dim, bias=False)   # :84
                                                                   └─ reset_parameters()   # :87-91  权重置零,末 dim 列置单位阵
                                                                  依赖:被 Eagle3Draft.fusion 持有;Eagle3Draft.fuse (eagle3.py:167-168)
                                                                        按 DraftConfig.feature_blocks 选源 → fusion
                                                                        源由 eagle3_feature_stack (eagle3.py:104) 摊平 AttnResState 提供


                                                                  5.3.6 数据流

                                                                    AttnResState → eagle3_feature_stack(state) → [b0,b1,...,bN]   # 摊平全部
                                                                         ↓ DraftConfig.feature_blocks=(0,3,-1)
                                                                    Eagle3Draft.fuse → [b0, b3, bN] → cat (B,T,3d) → W_E3 (B,T,d)




                                                                    5.3.7 执行流

                                                                      SpeculativeDecoder._features (speculative.py:347-349)
                                                                       └─ state = model.model._attn_res_state      # 仅 attn_res.enabled 时有
                                                                       └─ _extract_features (speculative.py:281-296)
                                                                            ├─ AttnRes 有: eagle3_feature_stack(state, picks=None)  # 摊平
                                                                            └─ 无: [hidden]*5   # 教学回退
                                                                       └─ _fused → draft.fuse(feats)   # 选 (0,3,-1) + W_E3




                                                                      5.3.8 关键类/函数职责表

                                                                      名称

                                                                      file:line

                                                                      输入 → 输出

                                                                      职责

                                                                      Eagle3FeatureFusion.reset_parameters

                                                                      eagle3.py:87-91

                                                                      —

                                                                      置 [0 0 I] 初值

                                                                      Eagle3FeatureFusion.forward

                                                                      eagle3.py:93-96

                                                                      features → (B,T,d)

                                                                      cat + 投影

                                                                      eagle3_feature_stack

                                                                      eagle3.py:104-134

                                                                      state, picks=None → list

                                                                      摊平不选择

                                                                      (V3 修复)

                                                                      Eagle3Draft.fuse

                                                                      eagle3.py:167-168

                                                                      block_features → (B,T,d)

                                                                      唯一选择点 + 融合

                                                                      _extract_features

                                                                      speculative.py:281-296

                                                                      (model,hidden,state) → list

                                                                      AttnRes 摊平 / 回退

                                                                      5.3.9 代码

                                                                        class FeatureFusion(nn.Module):
                                                                            """Bias-free ``W_E3``, initialised ``[0 0 I]``."""


                                                                            def __init__(self, dim: int, n_sources: int = 3):
                                                                                super().__init__()
                                                                                self.dim = dim
                                                                                self.n_sources = n_sources
                                                                                self.proj = nn.Linear(dim * n_sources, dim, bias=False)
                                                                                self.reset_parameters()


                                                                            def reset_parameters(self) -> None:
                                                                                with torch.no_grad():
                                                                                    self.proj.weight.zero_()
                                                                                    # [0 ... 0 I]: the last source (the high-level feature) passes through.
                                                                                    self.proj.weight[:, -self.dim:] = torch.eye(self.dim)


                                                                            def forward(self, features: list[Tensor]) -> Tensor:
                                                                                if len(features) != self.n_sources:
                                                                                    raise ValueError(f"expected {self.n_sources} feature sources")
                                                                                return self.proj(torch.cat(features, dim=-1))


                                                                        @dataclass
                                                                        class DraftConfig:
                                                                            #: Training-time unroll length (the paper's test protocol).
                                                                            unroll_steps: int = 7
                                                                            #: AttnRes blocks the fused features are taken from.
                                                                            feature_blocks: tuple[int, int, int] = (0, 3, -1)
                                                                            #: MoE expert weights in MXFP4 with MXFP8 input activations (section 4.1.4).
                                                                            qat: bool = True


                                                                        class Eagle3Draft(nn.Module):
                                                                            """Draft model fine-tuned from the pre-trained MTP layer."""


                                                                            def __init__(self, mtp_layer: nn.Module, dim: int, lm_head: nn.Module,
                                                                                         cfg: DraftConfig | None = None):
                                                                                super().__init__()
                                                                                self.cfg = cfg or DraftConfig()
                                                                                self.fusion = FeatureFusion(dim, n_sources=len(self.cfg.feature_blocks))
                                                                                self.layer = mtp_layer
                                                                                self.lm_head = lm_head


                                                                            def fuse(self, block_features: list[Tensor]) -> Tensor:
                                                                                picked = [block_features[i] for i in self.cfg.feature_blocks]
                                                                                return self.fusion(picked)


                                                                            def forward(self, fused: Tensor, next_embeds: Tensor) -> Tensor:
                                                                                h = self.layer(fused, next_embeds)
                                                                                return self.lm_head(h)


                                                                            @torch.no_grad()
                                                                            def draft(
                                                                                self, fused: Tensor, embed_fn, *, n_steps: int | None = None
                                                                            ) -> tuple[Tensor, Tensor]:
                                                                                """Autoregressive drafting: after the first step the draft consumes its
                                                                                own outputs, exactly as at inference."""
                                                                                n_steps = n_steps or self.cfg.unroll_steps
                                                                                tokens, logits_out = [], []
                                                                                state = fused
                                                                                last = embed_fn(torch.zeros(fused.shape[:2], dtype=torch.long, device=fused.device))
                                                                                for _ in range(n_steps):
                                                                                    logits = self.forward(state, last)
                                                                                    nxt = logits[:, -1:].argmax(-1)
                                                                                    tokens.append(nxt)
                                                                                    logits_out.append(logits[:, -1:])
                                                                                    last = embed_fn(nxt)
                                                                                    state = state[:, -1:]
                                                                                return torch.cat(tokens, dim=1), torch.cat(logits_out, dim=1)


                                                                        def speedup_from_acceptance(rate: float, draft_len: int) -> float:
                                                                            """Expected tokens per target forward under lossless speculative sampling."""
                                                                            if rate >= 1.0:
                                                                                return float(draft_len + 1)
                                                                            return (1.0 - rate ** (draft_len + 1)) / (1.0 - rate)





                                                                        Q1. 有 Kimi3ForCausalLM × Eagle3Draft 协作的 demo 吗?verify 代码在哪?

                                                                        现在有:

                                                                        • src/models/llm/kimi_k3/mtp/speculative.py:verify_tokens(判据)、SpeculativeDecoder(端到端循环)、RecomputeBackend/CacheRollbackBackend(两打分路径)。

                                                                        • experiments/mtp/eagle3_demo.py:跑真实模型循环,实测接受率与 tokens/forward。

                                                                        • tests/mtp/test_speculative.py:10 项,含"Recompute vs Rollback 逐 token 一致"的回滚正确性证明。

                                                                        • 设计动机:kimi3-master/serve/eagle3.py 没有 verify,故自研扩展。实测 lossless 接受率 0.13、tokens/forward 1.389。

                                                                        Q2. 如何获取出那三层?

                                                                        [0 0 I] 是 Eagle3FeatureFusion.proj(一个无 bias 的 W_E3: 3d → d)的初始权重,作用是初始化时让融合输出恒等于高层特征 h_h。

                                                                        具体含义如下:

                                                                        W_E3 ∈ ℝ^{d×3d} 被分块成 [W_low | W_mid | W_high],初始化令:

                                                                        • W_low = 0

                                                                        • W_mid = 0

                                                                        • W_high = I(单位阵)→ eagle3.py:91

                                                                        因此初始前向:

                                                                          fuse([h_l, h_m, h_h]) = [0 0 I] @ [h_l; h_m; h_h] = h_h

                                                                          即 忽略低/中层特征,只透传高层特征——这正是 MTP 预训练时的输入分布,所以微调起步无扰动,之后模型再逐步学习吸收低/中层。

                                                                          这三个特征从哪来 / 怎么生成

                                                                          由 eagle3_feature_stack (eagle3.py:103) 配合 DraftConfig.feature_blocks=(0, 3, -1) 提供:

                                                                          1. 生成来源:主干 Kimi3ForCausalLM 前向期间,AttentionResiduals 每完成一个块就把输出折叠进 AttnResState.blocks,sources() 摊平成 [embedding, block_1, ..., block_N]。

                                                                          2. 选择:Eagle3Draft.fuse() (eagle3.py:175) 按 (0, 3, -1) 从该列表挑三块——第 1 块、第 4 块、最后一块 AttnRes 输出,分别对应低/中/高层语义。

                                                                          3. FeatureFusion 获取:三个 (B,T,d) 张量沿最后一维 cat 成 (B,T,3d),经 W_E3 投影回 (B,T,d),作为草稿层 MTPLayer 的输入(eagle3.py:178)。

                                                                          一句话:[0 0 I] 让 EAGLE-3 起步时等价于"只用目标模型最后一层特征"的 MTP,之后通过 LK 损失学习把 W_low/W_mid 从 0 调整为非零。

                                                                          Q3. AttentionResiduals 如何生成?

                                                                          在 Kimi3Model 的前向传播中,会用 self.attn_res.add_output(self._attn_res_state, h) 往self._attn_res_state 中增加模型每层生成的中间状态。

                                                                            state = model.model._attn_res_state  # AttnResState 对象
                                                                            feats_all = eagle3_feature_stack(state, picks=None)   # speculative.py:291



                                                                            Q4. 给出一个真实样例

                                                                            真实调用链(来自 speculative.py:355 和 test_eagle3_integration.py)

                                                                              # ============ 1) 目标模型前向,副作用产生 AttnResState ============
                                                                              model = Kimi3ForCausalLM(cfg)        # 主干
                                                                              out = model(input_ids)               # 前向时 AttentionResiduals 在内部
                                                                                                                   # 维护 model.model._attn_res_state


                                                                              # ============ 2) 从 AttnResState 摊平成"可读源列表" ============
                                                                              state = model.model._attn_res_state  # AttnResState 对象
                                                                              feats_all = eagle3_feature_stack(state, picks=None)   # speculative.py:291
                                                                              # feats_all 是 List[Tensor],长度 = n_blocks + 1
                                                                              # feats_all[0] = token embedding
                                                                              # feats_all[1] = 第 1 个 AttnRes 块完成时的塌缩表示
                                                                              # feats_all[2] = 第 2 个 AttnRes 块塌缩
                                                                              # ...
                                                                              # feats_all[N] = 最后一个块(高层语义)
                                                                              # 每项 shape = (B, T, d)


                                                                              # ============ 3) 按 (0, 3, -1) 选三块 ============
                                                                              draft = Eagle3Draft(model.mtp, dim=cfg.model.dim, lm_head=model.lm_head)
                                                                              # DraftConfig.feature_blocks = (0, 3, -1)
                                                                              h_l = feats_all[0]    # 低层:第 0 块 = token embedding
                                                                              h_m = feats_all[3]    # 中层:第 3 块
                                                                              h_h = feats_all[-1]   # 高层:最后一块
                                                                              # 这三个就是 [h_l; h_m; h_h],每个 shape (B, T, d)


                                                                              # ============ 4) Eagle3FeatureFusion.forward 收到什么 ============
                                                                              # draft.fuse(feats_all) 内部:
                                                                              #   selected = [feats_all[0], feats_all[3], feats_all[-1]]     # eagle3.py:176
                                                                              #   return self.fusion(selected)
                                                                              # fusion.forward 里:
                                                                              #   cat([h_l, h_m, h_h], dim=-1)  -> shape (B, T, 3d)
                                                                              #   self.proj(...)                -> Linear(3d -> d, bias=False)
                                                                              #   输出 fused (B, T, d)



                                                                              一个真实测试例(test_eagle3_integration.py:60-71)

                                                                                fusion = Eagle3FeatureFusion(C=64, n_sources=3)
                                                                                feats  = [torch.randn(2, 3, 64) for _ in range(3)]
                                                                                #        ↑ h_l (2,3,64)   ↑ h_m (2,3,64)   ↑ h_h (2,3,64)
                                                                                fused  = fusion(feats)
                                                                                # 内部:torch.cat(feats, dim=-1) -> (2,3,192)
                                                                                #       proj: Linear(192 -> 64, bias=False)
                                                                                #       初始 W = [0_{64×64} | 0_{64×64} | I_{64×64}]
                                                                                #       故 fused == feats[2] == h_h
                                                                                assert torch.allclose(fused, feats[2])     # 通过 —— 这就是 [0 0 I] 的效果




                                                                                端到端(带真实模型,见 test_eagle3_integration.py:74)

                                                                                  cfg   = small_cfg(mtp=MTPConfig(enabled=True, layer_kind="mla"))
                                                                                  model = Kimi3ForCausalLM(cfg)
                                                                                  draft = Eagle3Draft(model.mtp, cfg.model.dim, model.lm_head)


                                                                                  # 模拟 AttnRes 攒了 5 个块
                                                                                  feats = [torch.randn(2, 4, 64) for _ in range(5)]
                                                                                  fused = draft.fuse(feats)              # 内部挑 [0],[3],[4],cat 成 (2,4,192)
                                                                                                                         # proj -> (2,4,64)
                                                                                  # fused 喂给 MTP 层做草稿自回归
                                                                                  toks, logits = draft.draft(fused, model.model.tok_embed, n_steps=3)




                                                                                  关键点

                                                                                  • h_l / h_m / h_h 不是三层隐藏状态——是 AttnResState.blocks 列表里索引 0、3、-1 的"块塌缩表示"(每个块是若干子层输出的累加和,attn_res.py:189-194)。

                                                                                  • blocks[0] 永远是 token embedding(attn_res.py:155),所以"低层"实际就是词嵌入。

                                                                                  • 生成方式:主干前向时,每完成一个 AttnRes 块,add_output 把 partial 追加进 blocks——这是前向的副作用,无需额外计算。

                                                                                  • FeatureFusion 拿到的输入:三个 (B,T,d) 张量的列表,forward 里 torch.cat(dim=-1) 拼成 (B,T,3d) 一次性过 Linear(3d→d, bias=False)。

                                                                                  5.3.10 对比基线与实测数据

                                                                                  • 直接只用高层特征:简单、无扰动,但不用低层信息。

                                                                                  • [0 0 I] 融合:在"零扰动起点"和"可用多层信息"之间平滑过渡。

                                                                                  • discussion.py:E2 实测:[0 0 I] 起步 error=0 且保持 0;随机起步初始 error 1.3484 → 0.0010;全零起步 1.0393 → 0.0007(训练目标=高层恒等,60 步 Adam)。证明零扰动优势。

                                                                                  5.3.11 反方辩手 / 边界条件

                                                                                  • a) 反对:低/中层特征到底有没有用未知,可能就是噪音,白加参数。

                                                                                  • b) 若失败:低中层特征与高层冗余或与预测不相关。

                                                                                  • c) 胜出:draft 需要在"已见上下文"处更细粒度;失败:浅层特征与目标无关。

                                                                                  • d) 更稳健:学到的 W_E3 若趋于 [0 0 I],则模型自己选择只用高层=自动关闭低层。

                                                                                  • 完成度:已实现并运行通过(E2 实测回填)。


                                                                                  5.4 子知识点:LK 损失(EAGLE-3 训练目标)

                                                                                  5.4.1 要解决的问题

                                                                                  投机解码的加速比 ∝ 逐 token 接受率 Σ_x min(p,q)。草稿模型的训练目标应该直接最大化这个接受率,而不是用一个"看起来相关但实际脱节"的代理。

                                                                                  5.4.2 技术难点

                                                                                  1. 代理失效:常规的 KL 最小化对容量受限的草稿模型,不保证最大化接受率——它可能让草稿越来越"保守"而不是越来越像 p 的峰值。

                                                                                  2. 梯度稀疏:log Σ min 这类目标在高置信处梯度可能很稀,收敛慢。

                                                                                  5.4.3 解决方案总体思路

                                                                                  直接优化 L_LK = -log Σ_x min(p(x), q(x)),温度 1、无 CE 辅助项。它正是接受率的负对数——优化目标与推理加速的度量直接对齐,而非代理。

                                                                                  paper-LK-loss
                                                                                  paper-LK-loss

                                                                                  5.4.4 思路背后的原理

                                                                                  • 直觉:与其学"一个像样的分布",不如直接学"猜中被接受的概率最大"。

                                                                                  • 准专业:p=目标分布、q=草稿分布;Σ_x min(p,q) 是两分布的"重叠量"(acceptance)。取其负对数作为损失,最小化它即最大化重叠。

                                                                                  • 专家:论文指出,对容量受限 draft,KL 最小化不能保证最大化接受率;LK 损失把"优化目标"和"推理加速比"绑定,是"端到端对齐"的体现。

                                                                                  5.4.5 详细分析原理

                                                                                  KL 散度(标准正向 KL:是 mode-seeking(寻找目标分布峰值);但当草稿模型q容量受限(参数量 / 表达能力不足,没法完整拟合真实分布p),最小化正向 KL 会出现保守效应:q会避开所有p有概率但q没法建模的区域,宁愿压低整体分布、只在少数安全区域输出概率,而不是去对齐p的高概率峰值,最终投机解码(speculative decoding)的 token 接受率上不去。

                                                                                   

                                                                                  符号约定: p:大目标模型(Target,真实分布) q:容量受限的草稿模型(Draft)

                                                                                  ”
                                                                                  正向 KL 最小化的数学行为

                                                                                  正向 KL: 损失最小化等价于:惩罚 q 在 q 自己采样出来的位置上,和 p 不一致。

                                                                                  • 如果q某个位置分配概率,但p在这里概率很低 → 损失暴涨,模型会把这个位置的概率压到接近 0。

                                                                                  • 但反过来:p 有很高概率、q 没有能力建模的区域,KL 不会惩罚。 也就是:(p(x)\gg0),但(q(x)=0),这一项在 KL 求和里直接消失,没有损失。

                                                                                  👉 后果:容量不够时,q发现自己无法覆盖p全部高概率区域,最优解就是切掉所有拿不准的候选 token,只保留极少数它非常确定的 token。 也就是变保守:输出分布很尖,但候选集合太小,很多p真正想要的峰值 token 被直接置零;草稿模型采样出来的 token,即便 q 很自信,也不是 p 的完整峰值集合,投机接受率无法最大化。

                                                                                  和反向 KL 对比(方便理解)

                                                                                  反向 KL: 最小化反向 KL:惩罚 p 高概率区域里 q 低估的地方。 只要(p(x))大,就强制(q(x))不能太小。

                                                                                   

                                                                                  反向 KL 是 mode-covering,会强制 q 去拟合 p 的所有峰值;代价是容易在 p 低概率处分配多余概率(产生幻觉候选)。

                                                                                  ”
                                                                                  放到投机解码(草稿模型)场景

                                                                                  投机解码目标:最大化草稿 token 被大模型接受的概率。 要最大化接受率,理想草稿q应该满足:q的高概率集合,尽量覆盖p的高概率峰值集合。

                                                                                  但用正向 KL 训练受限容量草稿模型:

                                                                                  1. 草稿容量不足,没办法同时建模 p 所有峰值;

                                                                                  2. 最小正向 KL 的最优策略:放弃一部分 p 的峰值,直接把这些 token 概率归零;

                                                                                  3. 草稿只保留一小部分最稳妥 token,分布变得保守;

                                                                                  4. 虽然 q 在自己保留的 token 上和 p 很接近,但漏掉了大量 p 的峰值候选;

                                                                                  5. 采样出来的草稿序列,命中 p 接受 token 的概率并不会最高。

                                                                                   

                                                                                  关键点区分: 正向 KL 最小化 ≠ 最大化接受率。 正向 KL 优化目标是分布距离;投机接受率是另一个非对称的离散指标,二者目标空间不一致。当模型有表达瓶颈时,目标函数会走捷径,走向保守,而不是对齐 p 峰值。

                                                                                  ”
                                                                                  简单例子(token-level)

                                                                                  假设下一个 token 真实分布p:A:0.5, B:0.4, C:0.1 草稿模型容量有限,最多只能表达 2 个 token。

                                                                                  • 正向 KL 最小化:最优策略是删掉 B,输出A:0.99, C:0.01。避开 B,因为模型学不好 B,B 会带来巨大 KL 损失。分布保守,采样几乎只有 A。但 p 有 40% 概率选 B,草稿永远不会生成 B,大量机会丢失 → 接受率上不去。

                                                                                  • 如果是反向 KL:会强制 q 覆盖 A、B 两个高概率峰,输出A:0.55, B:0.45。草稿会采样 A/B,恰好是 p 的两个主峰,投机接受率更高。

                                                                                  一句话总结这个现象

                                                                                  容量受限下最小正向 KL,草稿模型会主动舍弃目标分布里难以建模的高概率峰,消除风险项来降低 KL 损失,表现为输出分布保守;但投机接受率依赖草稿能覆盖目标分布主峰,所以正向 KL 优化无法保证最大化接受率。

                                                                                  5.4.6 架构与类依赖

                                                                                  无独立类;lk_loss(eagle3.py:63-70)与 acceptance_rate(eagle3.py:58-60)为纯函数,被训练管线调用。

                                                                                  5.4.7 数据流

                                                                                    target_logits (B,T,V)  draft_logits (B,T,V)
                                                                                       ▼ softmax                ▼ softmax
                                                                                     p (B,T,V)               q (B,T,V)
                                                                                       └─→ min(p,q) → sum(-1) → -log → mean   # lk_loss (eagle3.py:63-70)





                                                                                    5.4.8 执行流

                                                                                      训练: loss = lk_loss(target_logits, draft_logits)
                                                                                        └─ p=softmax(target); q=softmax(draft)
                                                                                        └─ return -log(acceptance_rate(p,q).clamp_min(1e-9)).mean()





                                                                                      5.4.9 关键函数职责表

                                                                                      名称

                                                                                      file:line

                                                                                      输入 → 输出

                                                                                      职责

                                                                                      acceptance_rate

                                                                                      eagle3.py:58-60

                                                                                      (p,q) → (B,)

                                                                                      Σ_x min(p,q)
                                                                                      lk_loss

                                                                                      eagle3.py:63-70

                                                                                      (target,draft logits) → scalar

                                                                                      -log Σ min

                                                                                      5.4.10 代码

                                                                                        def acceptance_rate(p: Tensor, q: Tensor) -> Tensor:
                                                                                            """``sum_x min(p(x), q(x))`` -- the quantity speculative decoding's speedup
                                                                                            is proportional to."""
                                                                                            return torch.minimum(p, q).sum(-1)



                                                                                        def lk_loss(target_logits: Tensor, draft_logits: Tensor) -> Tensor:
                                                                                            """Eq. 16, at temperature 1.


                                                                                            Directly the negative log acceptance rate, with no ground-truth
                                                                                            cross-entropy term -- optimising the thing that actually determines the
                                                                                            speedup instead of a surrogate for it.
                                                                                            """
                                                                                            p = torch.softmax(target_logits.float(), dim=-1)
                                                                                            q = torch.softmax(draft_logits.float(), dim=-1)
                                                                                            return -torch.log(acceptance_rate(p, q).clamp_min(1e-9)).mean()




                                                                                        5.4.11 对比基线与实测数据

                                                                                        • KL(f ‖ q)(surrogate):最小化边际奖励,可越来越"保守"而非越像 p 的峰值。

                                                                                        • L_K(直接接受率):优化目标和推理加速的正比关系直接对齐。

                                                                                        • test_mtp.py 中 lk_loss(p,q)=0 当 p=q,且随分布分歧单调上升(E2 sanity)。

                                                                                        5.4.12 反方辩手 / 边界条件

                                                                                        • 反对:log Σ min 损失在高分处梯度稀疏,收敛慢?

                                                                                        • 回应:论文测试(Unroll 7)在真实 K3 draft 上已可训练至收敛;本项目 lk_loss 在 p=q 时为 0、随分布疏离单调上升。

                                                                                        • 完成度:已实现并运行通过(E2 sanity)。

                                                                                        5.5 子知识点:EAGLE-3 draft 推理(草稿自回归)

                                                                                        5.5.1 要解决的问题

                                                                                        目标模型 93 层每 token 一前向太贵。投机解码想用"每步只花一层"的草稿模型先快速猜 L 个 token,再用一次目标前向核对——省下昂贵的目标前向次数。草稿自回归就是"连续猜 L 个"的实现。

                                                                                        5.5.2 技术难点

                                                                                        1. 草稿没有目标特征:从第 2 步起,草稿不再有"目标侧特征"可用(最新位置的目标特征要等目标前向才有),只能吃自己上一步的输出——这是递归起草。

                                                                                        2. 融合输入只来自一步:draft() 每步把 state 缩到最后一位 state[:, -1:],模拟推理时"只有当前位置可用"。

                                                                                        3. 与 verify 接续:草稿猜完必须交给目标核对,否则没有意义。

                                                                                        5.5.3 解决方案总体思路

                                                                                        草稿自回归 L 步,每步只走一个 MTP 层(很便宜):第 1 步用融合特征 fused + 占位嵌入,之后每步把上一步 argmax token 嵌入作为输入,state 缩到 [:, -1:]。目标 = 一次 93 层前向 verify L+1 个候选。

                                                                                        5.5.4 思路背后的原理

                                                                                        • 直觉:速读顾问连翻几页,每翻一页只花"一层"的力气,翻完交给主模型一次性核对。

                                                                                        • 准专业:draft() 循环 L 次,logits = forward(state, last),nxt = argmax,last = embed(nxt),state = state[:, -1:]。

                                                                                        • 专家:这是"推理期递推形态":草稿从全序列前向(训练)切换为单步递推(推理),因为只有当前位置的分布需要。

                                                                                        5.5.5 架构与类依赖

                                                                                          Eagle3Draft (eagle3.py:146)
                                                                                           ├─ fusion  Eagle3FeatureFusion
                                                                                           ├─ layer   MTPLayer(复用)
                                                                                           ├─ lm_head 目标共享词表头
                                                                                           └─ draft() (eagle3.py:174-191)   # 自回归
                                                                                          依赖:被 SpeculativeDecoder._run_round 调用(speculative.py:363)




                                                                                          5.5.6 数据流

                                                                                            fused (B,T,d) → 取最后一位
                                                                                            loop L 次:
                                                                                               forward(state, last) → logits (B,1,V)
                                                                                               nxt = argmax → (B,1)
                                                                                               last = embed(nxt); state = state[:, -1:]
                                                                                            返回 tokens (B,L), logits (B,L,V)




                                                                                            5.5.7 执行流

                                                                                              SpeculativeDecoder._run_round (speculative.py:363-370)
                                                                                               └─ fused = self._fused(hidden)
                                                                                               └─ draft_tokens, draft_logits = draft.draft(fused, tok_embed, n_steps=L)
                                                                                                    └─ Eagle3Draft.draft (eagle3.py:174-191)




                                                                                              5.5.8 关键函数职责表

                                                                                              名称

                                                                                              file:line

                                                                                              输入 → 输出

                                                                                              职责

                                                                                              Eagle3Draft.forward

                                                                                              eagle3.py:170-172

                                                                                              (fused,next_embeds) → logits

                                                                                              单步草稿前向

                                                                                              Eagle3Draft.draft

                                                                                              eagle3.py:174-191

                                                                                              (fused, embed_fn, n_steps) → (tokens,logits)

                                                                                              递归起草 L 步

                                                                                              5.5.9 代码

                                                                                                # -*- coding: utf-8 -*-
                                                                                                """EAGLE-3 草稿模型:从 MTP 层微调出的投机解码 draft(K3 报告 §4.1.4)。


                                                                                                EAGLE-3(extension-3 of the speculative decoding literature)把预训练的 MTP
                                                                                                层当作起点,微调成一个单解码器层式的草稿模型。目标模型冻结,只训草稿层与
                                                                                                特征融合投影。两个关键机制(对齐 kimi3-master ``serve/eagle3.py`` 全文):


                                                                                                1. **特征融合 ``FeatureFusion``**:输入是低/中/高三层特征的拼接(分别取自
                                                                                                   第 1、4、最终 Attention Residuals 块的输出——一个 93 层骨干只有这 3 处
                                                                                                   “深度方向混合”出入口),经一个**无 bias** 的 ``W_E3: 3d -> d`` 投影
                                                                                                   融合。``W_E3`` 初值 ``[0 0 I]``:最后一列是单位阵,于是初始融合输出
                                                                                                   **完全等于高层特征 h_h**——正是 MTP 预训练时的输入;模型从“只信高层”
                                                                                                   逐步学到“吸收低/中层特征”,初始化不引入瞬间扰动。


                                                                                                2. **LK 损失**:投机解码的加速比正比于逐 token 接受率 ``sum_x min(p,q)``
                                                                                                   (p 目标、q 草稿)。用减法 KL 当代理**不能保证**最大化接受率(容量受限的
                                                                                                   草稿模型),故 K3 直接优化权重似然 LK 损失
                                                                                                   ::


                                                                                                       L_LK = -log sum_x min(p(x), q(x))


                                                                                                   温度 1,无 ground-truth CE 项。训练时把草稿展开 7 步:除第一步外(最先前
                                                                                                   位置的“目标侧特征”不可得),草稿消费自己早前步的输出——正是推理期
                                                                                                   循环起草(drafting)的过程的镜像。


                                                                                                特征栈语义(在 main 侧由 ``AttentionResiduals`` 每块输出收集):
                                                                                                - ``eagle3_feature_stack(attn_res_state)``:从 AttnRes 状态缓存里按
                                                                                                  ``(0, 3, -1)``(第 1、第 4、最后)三个 unit 的输出取特征。
                                                                                                  本项目 AttnRes 状态语义:``n_units = 2*n_layers``(每 block 两个 sublayer
                                                                                                  unit)。kimi3-master 里 ``feature_blocks=(0,3,-1)`` 指第 1 / 4 / 末个
                                                                                                  **Attention Residuals 块**的输出。实现上本项目直接给一个通用的
                                                                                                  ``eagle3_feature_stack(state, picks)``:默认 picks 视 n_layers 归一。
                                                                                                """
                                                                                                class Eagle3FeatureFusion(nn.Module):
                                                                                                    """无 bias 的 ``W_E3``,初始 ``[0 0 I]``(官方 FeatureFusion)。


                                                                                                    ``proj: (n_sources*dim) -> dim``,权重初值前 ``(n_sources-1)*dim`` 列全 0、
                                                                                                    末 ``dim`` 列单位阵。初始化后 ``fuse 输出 ≡ 高层特征``。
                                                                                                    """


                                                                                                    def __init__(self, dim: int, n_sources: int = 3):
                                                                                                        super().__init__()
                                                                                                        self.dim = dim
                                                                                                        self.n_sources = n_sources
                                                                                                        self.proj = nn.Linear(dim * n_sources, dim, bias=False)
                                                                                                        self.reset_parameters()


                                                                                                    def reset_parameters(self) -> None:
                                                                                                        with torch.no_grad():
                                                                                                            self.proj.weight.zero_()
                                                                                                            # [0 ... 0 I]:最后一个源(高层特征)恒等通过。
                                                                                                            self.proj.weight[:, -self.dim:] = torch.eye(self.dim)


                                                                                                    def forward(self, features: Sequence[Tensor]) -> Tensor:
                                                                                                        if len(features) != self.n_sources:
                                                                                                            raise ValueError(f"expected {self.n_sources} feature sources, got {len(features)}")
                                                                                                        return self.proj(torch.cat(list(features), dim=-1))


                                                                                                # 兼容官方命名:FeatureFusion 即 Eagle3FeatureFusion。
                                                                                                FeatureFusion = Eagle3FeatureFusion


                                                                                                @torch.no_grad()
                                                                                                def eagle3_feature_stack(
                                                                                                    state,
                                                                                                    picks: Optional[Sequence[int]] = None,
                                                                                                ) -> list[Tensor]:
                                                                                                    """从本项目 AttentionResiduals 状态里摊平 EAGLE-3 可读的特征源列表。


                                                                                                    ``state`` 是 ``Kimi3ForCausalLM`` 前向期间 ``AttentionResiduals`` 的残差
                                                                                                    容器(``modules/attn_res.py::AttnResState``)。本项目 AttnRes 以块(block)
                                                                                                    为单位维持低级表示:``init_state`` 把 token embedding 置为 ``blocks[0]``,
                                                                                                    随后每完成一个块就折叠进 ``blocks``(``add_output``),``sources()`` 返回
                                                                                                    "embedding + 各已完成块表示 + 当前块 partial" 的可读源列表。


                                                                                                    **职责划分(修复 V2 Q5 的重复选择缺陷)**:本函数只负责"把状态对象摊平
                                                                                                    成完整的出口列表",**不做"选哪三层"**;选择唯一保留在
                                                                                                    ``Eagle3Draft.fuse()``(由 ``DraftConfig.feature_blocks`` 单一来源驱动),
                                                                                                    与官方 ``kimi3-master/serve/eagle3.py::fuse`` 一致。因此:


                                                                                                    - ``picks=None``(默认):返回**全部**可读源 ``[b_0, b_1, ..., b_N]``,
                                                                                                      供上层自行选择(推荐用法:先摊平,再按 ``feature_blocks`` 挑)。
                                                                                                    - ``picks`` 非空:为向后兼容仍可在此直接按索引挑选(已弃用,新代码
                                                                                                      不要用,避免与 ``fuse()`` 的选择逻辑互斥串联而越界)。


                                                                                                    返回:特征张量列表,每个形状 ``(B, T, C)``。
                                                                                                    """
                                                                                                    if hasattr(state, "outputs"):  # 通用兼容:直接给输出列表的对象
                                                                                                        seq = list(state.outputs)
                                                                                                    elif hasattr(state, "sources"):
                                                                                                        seq = state.sources()
                                                                                                    elif isinstance(state, (list, tuple)):
                                                                                                        seq = list(state)
                                                                                                    else:
                                                                                                        raise TypeError(f"cannot read feature sources from {type(state)}")
                                                                                                    if picks is None:
                                                                                                        return seq
                                                                                                    n = len(seq)
                                                                                                    idx = [i if i >= 0 else n + i for i in picks]
                                                                                                    if any(i >= n for i in idx) or any(i < 0 for i in idx):
                                                                                                        raise IndexError(f"feature picks {picks} out of range for {n} sources")
                                                                                                    return [seq[i] for i in idx]


                                                                                                class Eagle3Draft(nn.Module):
                                                                                                    """从预训练 MTP 层微调出的草稿模型。


                                                                                                    ``mtp_layer`` 是 MTPLayer(其内部 ``block`` 就是草案层),``lm_head`` 是
                                                                                                    目标模型共享词表头。推理期:每步从目标模型取 ``fused``(特征融合)输入,
                                                                                                    草稿输出 logits [B,1,V],再与目标做接受/拒绝。
                                                                                                    """


                                                                                                    def __init__(
                                                                                                        self,
                                                                                                        mtp_layer: nn.Module,
                                                                                                        dim: int,
                                                                                                        lm_head: nn.Module,
                                                                                                        cfg: DraftConfig | None = None,
                                                                                                    ):
                                                                                                        super().__init__()
                                                                                                        self.cfg = cfg or draft_config()
                                                                                                        self.fusion = Eagle3FeatureFusion(dim, n_sources=len(self.cfg.feature_blocks))
                                                                                                        self.layer = mtp_layer
                                                                                                        self.lm_head = lm_head


                                                                                                    def fuse(self, block_features: Sequence[Tensor]) -> Tensor:
                                                                                                        return self.fusion([block_features[i] for i in self.cfg.feature_blocks])


                                                                                                    def forward(self, fused: Tensor, next_embeds: Tensor) -> Tensor:
                                                                                                        h = self.layer(fused, next_embeds)
                                                                                                        return self.lm_head(h)


                                                                                                    @torch.no_grad()
                                                                                                    def draft(
                                                                                                        self, fused: Tensor, embed_fn: Callable[[Tensor], Tensor],
                                                                                                        *, n_steps: int | None = None,
                                                                                                    ) -> tuple[Tensor, Tensor]:
                                                                                                        """自动回归起草:第一步后草稿吃自己的输出——推理期 draft 的原样。"""
                                                                                                        n_steps = n_steps or self.cfg.unroll_steps
                                                                                                        tokens, logits_out = [], []
                                                                                                        state = fused
                                                                                                        last = embed_fn(torch.zeros(fused.shape[:2], dtype=torch.long, device=fused.device))
                                                                                                        for _ in range(n_steps):
                                                                                                            logits = self.forward(state, last)
                                                                                                            nxt = logits[:, -1:].argmax(-1)
                                                                                                            tokens.append(nxt)
                                                                                                            logits_out.append(logits[:, -1:])
                                                                                                            last = embed_fn(nxt)
                                                                                                            state = state[:, -1:]
                                                                                                        return torch.cat(tokens, dim=1), torch.cat(logits_out, dim=1)



                                                                                                5.5.10 对比基线与实测数据

                                                                                                • 无投机:每 token 一个目标前向。

                                                                                                • EAGLE-3:每目标前向平均 1~6+ token(依赖接受率)。

                                                                                                • speedup_from_acceptance(r=0.8, L=7) = 4.16(理论,E3 表格)。

                                                                                                • 注意:这是理论上限。草稿猜得对不对要 verify 才算数(§4.6 给实测)。

                                                                                                5.5.11 反方辩手 / 边界条件

                                                                                                • 反对:草稿本身要训练、要保存模型文件、QAT 复杂。

                                                                                                • 成功条件:高接受率(r≈0.8+)。

                                                                                                • 失败条件:草稿未训练好、接受率低,加速比趋近 1。

                                                                                                • 完成度:已实现并运行通过(draft 全链路测试)。


                                                                                                5.6 子知识点:投机解码 verify 与端到端循环

                                                                                                5.6.1 要解决的问题

                                                                                                草稿 draft() 只是"猜了一串 token",没有任何机制判断这些 token 是否值得接受。没有 verify,投机解码就是空谈——你无法知道该照单全收、部分收、还是全拒。真实加速比也因此无法实测。

                                                                                                5.6.2 技术难点

                                                                                                1. 接受/拒绝判据:如何在"保留草稿"与"纠正错误"之间无损地权衡(必须保证最终分布 = 目标分布,即 lossless)。

                                                                                                2. 目标并行打分:目标模型要能一次前向对 L+1 个草稿位置打分,而不是 L+1 次前向。

                                                                                                3. KDA 状态回滚:KDA 的递推状态 S 被拒绝后无法像 KV cache 那样随意截断——这是 serve/decode.py 那套投影重演机制存在的原因,但两者此前没接起来。

                                                                                                4. 残差重采样:拒绝时要从残差分布重采 1 个 token,保证无损。

                                                                                                5.6.3 greedy vs lossless

                                                                                                投机采样分为两大阶段:

                                                                                                1. 小模型(draft model)生成一串候选 draft token;

                                                                                                2. 大目标模型(target model)做 verify 校验:逐个验证 draft token 是否接受;verify 有两种主流模式:greedy(贪心校验)、lossless(无损校验,也叫 strict 无损)。

                                                                                                核心本质区别
                                                                                                • greedy verify(贪心校验):校验时,target 模型输出贪心 next token,和 draft 的 token 做比对。只要 draft token 等于 target 贪心输出,就接受该 token;一旦不相等,丢弃后面所有 draft,直接输出 target 的贪心 token,结束本轮 verify。

                                                                                                • lossless verify(无损校验):严格复现原始论文无损投机采样数学逻辑,不拿贪心输出做比对;直接拿 target 完整概率分布,做概率层面的校验,保证输出分布和原生直接解码完全等价,输出结果 100% 和直接跑 target 模型一模一样,没有任何分布偏移。

                                                                                                token 接受判断逻辑

                                                                                                greedy verify

                                                                                                  draft_token_i == target.greedy_token




                                                                                                  只对比 target 取 argmax 的那个 token。

                                                                                                   

                                                                                                  风险:target 概率分布里,draft token 不是最大概率,但依然是合法高概率候选;greedy 模式会直接拒绝这个 token,造成不必要截断,引入分布偏差,不是无损。

                                                                                                  ”

                                                                                                  lossless verify

                                                                                                  依据原始投机采样概率接受准则:

                                                                                                  按这个概率做随机采样决定是否接受 draft token。

                                                                                                  • 只要满足概率条件就接纳 draft token;

                                                                                                  • 不强制要求 draft token 必须是 target 的 top‑1 贪心 token;

                                                                                                  • 拒绝时,从修正后的 target 分布重新采样下一个 token。

                                                                                                  输出一致性
                                                                                                  • greedy verify:❌ 非无损。最终生成文本 ≠ target 原生 greedy 解码。会发生不该截断的时候强行截断,改变输出。速度更快,但结果会偏移。

                                                                                                  • lossless verify:✅ 严格无损。整体生成分布完全等价于直接用 target 模型解码,不会改变模型输出行为,是论文标准。

                                                                                                  速度与吞吐量
                                                                                                  1. greedy verify:实现简单,每一步只拿 argmax,很多框架实现不用取出完整概率分布;截断发生更早,平均接受 token 数量更少。

                                                                                                  2. lossless verify:需要拿到 target 完整 token 概率,做比值 + 随机采样;可以接受更多 draft token,单轮 verify 能吞更长 draft 序列,理论上限速度更高;但需要访问完整 logits,算力开销略大。

                                                                                                   

                                                                                                  现实工程:vLLM/SGLang 里投机采样,speculative_algorithm=greedy / lossless。

                                                                                                  ”
                                                                                                  终止行为
                                                                                                  • greedy verify:只要某一个 draft token≠target 贪心 token,立刻全部丢弃后续 draft tokens,输出 target 贪心 token,本轮 verify 结束。

                                                                                                  • lossless verify:某一个 draft token 被概率拒绝,仅丢弃该位置及之后所有 draft,从 target 校正分布采样 1 个 token,本轮结束;前面已经通过的 token 全部保留。

                                                                                                  适用场景

                                                                                                  greedy verify

                                                                                                  • 只追求加速,对输出分布一致性没有强要求;

                                                                                                  • 业务本身就是 greedy 解码场景,追求简单、低开销;

                                                                                                   

                                                                                                  注意:即便你外层开启 greedy 解码,投机 verify 用 greedy 模式依然会带来输出不一致。

                                                                                                  ”

                                                                                                  lossless verify

                                                                                                  • 需要严格保证大模型原有输出效果,不能因为投机采样改变生成内容;

                                                                                                  • 开启 temperature、top‑p 采样场景;

                                                                                                  • 学术复现、对正确性敏感业务。

                                                                                                  通俗一句话总结
                                                                                                  • greedy verify:只看大模型最想要的那个 token,draft 对上就收,对不上全部扔掉,快但会改结果。

                                                                                                  • lossless verify:看完整概率,按数学规则随机接纳,不改变大模型原本输出,但计算开销略高,可以接纳更多 draft token。

                                                                                                  5.6.4 解决方案总体思路

                                                                                                  本项目 speculative.py 提供两层:

                                                                                                  • 纯函数 verify_tokens(speculative.py:73):实现 lossless 判据——u <= p(c)/q(c) 接受,否则从 norm(max(p-q,0)) 重采 bonus 并截断。不碰模型,独立可测。

                                                                                                  • SpeculativeDecoder 端到端循环(speculative.py:329),下挂两条打分后端:

                                                                                                    • RecomputeBackend:每轮无 cache 全序列重跑打分(正确性由构造保证,作 oracle)。

                                                                                                    • CacheRollbackBackend:快照 cache、增量打分,部分接受时恢复快照并重放已接受前缀,CacheRollback 是"真正的"工业形态(增量 + 回滚)。

                                                                                                  5.6.5 思路背后的原理

                                                                                                  • 直觉:主模型逐本核对顾问的猜测——猜对收下,猜错自己读一本并退回上一本对的地方。

                                                                                                  • 准专业(lossless 判据):草稿在位置 i 提出 c_i(分布 q_i),目标分布 p_i。采 u~U(0,1):

                                                                                                    • 若 u <= p_i(c_i)/q_i(c_i):接受 c_i;

                                                                                                    • 否则:拒绝,从 norm(max(p_i - q_i, 0)) 重采 1 个 token,截断。每轮产出 = 接受前缀长度 + 1。

                                                                                                  • 专家(为什么 lossless):把"直接从 p 采样"拆成"先看草稿 q 是否给对 + 错了从残差补"两步。只要拒绝分支的重采样分布是 max(p-q,0)/Z,两个分支的加权混合就精确等于 p,逐 token 分布不变——所以叫 lossless。这也是 speedup_from_acceptance 公式成立的严格前提。

                                                                                                  • 为什么两种后端:Recompute 数值正确但 O(T²)(教学 oracle);CacheRollback 是"真正的"工业形态(增量 + 回滚)。两者在固定 seed 下逐 token 一致,正好是回滚正确性的数值证明。

                                                                                                  5.6.6 架构与类依赖关系

                                                                                                    SpeculativeDecoder (speculative.py:329)
                                                                                                     ├─ draft  Eagle3Draft
                                                                                                     ├─ _run_round (speculative.py:363)      → draft
                                                                                                     ├─ decode_recompute (speculative.py:372)  → RecomputeBackend → 全序列打分
                                                                                                     ├─ decode_rollback (speculative.py:413)   → CacheRollbackBackend + snapshot/restore
                                                                                                     └─ verify_tokens (speculative.py:73)      → 纯函数判据


                                                                                                    打分后端:
                                                                                                     RecomputeBackend (speculative.py:264)      model(seq) 全序列
                                                                                                     CacheRollbackBackend (speculative.py:301)  model(tok, caches) 增量 + snapshot/restore


                                                                                                    cache 快照(按类型分派,duck-typing):
                                                                                                     snapshot_caches (speculative.py:221) → clone
                                                                                                     restore_caches (speculative.py:237) → KDA/MLA 原地回滚



                                                                                                    5.6.7 数据流(张量形状逐步)

                                                                                                      tokens (B,T0)
                                                                                                         ▼ model.model(tokens) → hidden (B,T,d)
                                                                                                         ▼ _fused → draft.fuse → fused (B,T,d)
                                                                                                         ▼ draft.draft → draft_tokens (B,L), draft_logits (B,L,V)
                                                                                                         ▼ 目标打分
                                                                                                            Recompute: cand=cat([tokens,draft_tokens]) (B,T+L) → model → logits (B,T+L,V)
                                                                                                                       取 [:, T:T+L] → tgt_draft (B,L,V)
                                                                                                            Rollback:  逐 token score_token → tgt_draft (B,L,V)
                                                                                                         ▼ verify_tokens(tgt_draft, draft_logits, draft_tokens) → VerifyResult
                                                                                                             n_accepted (B,), bonus_token (B,1), per_pos_ratios (B,L)
                                                                                                         ▼ 并入 tokens:  accepted[:na] + bonus





                                                                                                      5.6.8 执行流(时序/调用链)

                                                                                                      decode_recompute —— 参考 oracle 路径(无 cache 全序列重跑)

                                                                                                      每轮前向次数:目标 2 次全序列(:386 取 hidden + :391 打分)+ 草稿 L 次小步。

                                                                                                      decode_recompute
                                                                                                      decode_recompute
                                                                                                      decode_rollback —— 快照-回滚路径(增量打分)

                                                                                                      每轮前向次数:目标 1 次全序列(:443 取 hidden)+ L 次增量打分(:453)+ na+1 次重放(:467, :469)+ 草稿 L 次小步。

                                                                                                      decode_rollback
                                                                                                      decode_rollback
                                                                                                      两条路径并排对照
                                                                                                      两条路径并排对照
                                                                                                      两条路径并排对照
                                                                                                      关键差异表

                                                                                                      维度

                                                                                                      decode_recomputedecode_rollback

                                                                                                      打分方式

                                                                                                      拼接后全序列重跑(:390-391)

                                                                                                      逐 token 增量

                                                                                                      前向(:451-453)

                                                                                                      打分复杂度

                                                                                                      每轮 O(T²)(:267)

                                                                                                      每轮 L 次小步

                                                                                                      cache

                                                                                                      完全不用init_caches

                                                                                                       + 预填 + 快照/回滚/重放

                                                                                                      快照

                                                                                                      无

                                                                                                      snapshot_caches

                                                                                                      (:450)

                                                                                                      回滚

                                                                                                      无

                                                                                                      restore_caches

                                                                                                      (:464)

                                                                                                      重放

                                                                                                      无

                                                                                                      na

                                                                                                       次 accepted + 1 次 bonus(:465-469)

                                                                                                      目标全序列前向/轮

                                                                                                      2 次

                                                                                                      (:386 hidden + :391 打分)

                                                                                                      1 次

                                                                                                      (:443 hidden)

                                                                                                      定位

                                                                                                      参考 oracle,正确性由构造保证(:268)

                                                                                                      生产路径,正确性需靠 oracle 校验

                                                                                                      三个容易读错的点

                                                                                                      ① decode_rollback 并没有完全摆脱全序列重跑。:443hidden = self.model.model(tokens) 仍然是无 cache 全序列前向。源码 :440-442 专门注释了理由:特征提取要与 Recompute 路径逐位一致,否则两条路径的 token 流对不上;cache 只服务于草稿位置的增量打分,"二者正交"。所以它省掉的是打分那次全序列重跑(:391),不是特征那次。

                                                                                                      ② 回滚是"整体丢弃 + 重放",不是"部分撤销"。backend.score_token(accepted[j:j + 1].unsqueeze(0)) # (1,1) 先把 cache 恢复到草稿开始前(丢弃全部 L 个草稿的副作用),再用 :465-467 把 na 个已接受 token 重新喂一遍。之所以不做"只撤销 L-na 个",是因为 KDA 的 state 是不可逆的递推更新(:243, :247-251 覆盖 state 与三个卷积窗口)——线性注意力的固定大小状态矩阵没有"回退一格"的操作,只能从快照重建。这正是 snapshot_caches 必须存在的根本原因。

                                                                                                      ③ bonus token 必须消费进 cache。:468-469 注释:"被拒绝位置重采的 token 也要消费进 cache(它成为新历史)"。漏掉这一步,cache 会停在 accepted 末尾而 tokens 已多出 bonus,下一轮增量打分的上下文就错位了。这是回滚路径最容易埋 bug 的地方。

                                                                                                      decode_rollback 增量打分机制解析
                                                                                                      • 增量只发生在草稿窗内的 draft_len 次小步前向(这是真正省算力的地方)。

                                                                                                      • 重跑只为取 EAGLE-3 多层特征,是为了让 decode_rollback 与 decode_recompute 严格对齐、便于数值校验而保留的设计,不是技术做不到。

                                                                                                      增量打分如何实现

                                                                                                      关键路径在 speculative.py:448-455:

                                                                                                        step_caches_snap = snapshot_caches(caches)    # ① 打分前快照
                                                                                                        for j inrange(draft_len):
                                                                                                            tok = draft_tokens[:, j:j+1]              # ② 每步只喂 1 个 token
                                                                                                            lg = backend.score_token(tok)             # ③ 走 caches 的增量前向
                                                                                                            tgt_logits_list.append(lg[:, -1:])




                                                                                                        之所以"增量",是因为 CacheRollbackBackend.score_token 把 self.caches 传给 model(tok, caches=...):

                                                                                                        • MLA:只对当前 token 算一次 q·kv_latent,kv_latent 增 1 格(O(1) 追加)。

                                                                                                        • KDA:state 矩阵 S 按 delta rule 推进一步,conv 窗口滑 1 格。

                                                                                                        • 每步代价 = O(draft_len × d),而非 O(T²)。

                                                                                                        随后 restore_caches + 重放(speculative.py:464-469)把 cache 精确停在"已接受前缀末尾"——这是投机解码正确性的关键:被拒绝后缀的 cache 必须丢弃。

                                                                                                        为何没有摆脱全序列重跑

                                                                                                        speculative.py:443 每轮仍在做:

                                                                                                          hidden = self.model.model(tokens)   # 无 cache,全序列前向




                                                                                                          原因有三(见 speculative.py:441-442 注释):

                                                                                                          1. EAGLE-3 特征融合需要全序列 hiddendraft() 的输入是 fuse(features),其中 features 是低/中/高三层 AttnRes 出口堆叠。这些特征不能从增量 cache 直接读出——KDA 的 state 是压缩递推态,不含逐位置 hidden;MLA 的 kv_latent 是压缩 K/V,也不是 hidden。要拿到 (B, T, d) 的 hidden,必须跑一次完整 forward。

                                                                                                          2. 与 RecomputeBackend 严格对齐 注释明说:"与 Recompute 路径完全一致(保证两种后端特征相同)"。本文件的首要目的是用逐 token 一致来证明 rollback 正确性,不是追求性能。所以故意让两条路径的 draft 输入完全同源。

                                                                                                          3. 职责拆分 cache 只服务于"对草稿位置打分"这一段(speculative.py:451-455),与特征提取正交。生产实现里通常会用 last_hidden 增量递推 + AttnRes 快照来避免重跑,但那是性能优化层,不属于本文件的"回滚正确性证明"目标。

                                                                                                          函数细节

                                                                                                            decode_recompute (speculative.py:372) 每轮:
                                                                                                              1 hidden = model.model(tokens)                    # 全序列隐藏态
                                                                                                              2 draft_tokens, draft_logits = _run_round(hidden) # 草稿 L 步
                                                                                                              3 tgt = model(cat([tokens, draft_tokens]))        # 一次前向并行打分
                                                                                                              4 vr = verify_tokens(tgt[:, T:T+L], draft_logits, draft_tokens)
                                                                                                              5 tokens = cat([tokens, accepted[:na], bonus])
                                                                                                              6 stats.record(na, L)


                                                                                                            decode_rollback (speculative.py:413) 每轮:
                                                                                                              1 hidden = model.model(tokens)                    # 特征(无 cache)
                                                                                                              2 draft ...                                       # 草稿 L 步
                                                                                                              3 snap = snapshot_caches(caches)                  # 快照
                                                                                                              4 for j in L: score_token(draft_tokens[:,j])      # 增量打分
                                                                                                              5 vr = verify_tokens(...)
                                                                                                              6 restore_caches(caches, snap)                    # 回滚
                                                                                                              7 重放 accepted[:na] + bonus 进 cache             # cache 停在被接受末尾
                                                                                                              8 tokens = cat([...]); stats.record(na, L)




                                                                                                            5.6.9 关键类/函数职责表

                                                                                                            名称

                                                                                                            file:line

                                                                                                            输入 → 输出

                                                                                                            职责

                                                                                                            verify_tokens

                                                                                                            speculative.py:73-158

                                                                                                            (tgt,draft logits, draft tokens) → VerifyResult

                                                                                                            lossless 接受判据

                                                                                                            SpecDecodeStats.record

                                                                                                            speculative.py:181-183

                                                                                                            (n_accepted, draft_len)

                                                                                                            记录每轮

                                                                                                            SpecDecodeStats.measured_acceptance

                                                                                                            speculative.py:207

                                                                                                            — → float

                                                                                                            实测接受率

                                                                                                            SpecDecodeStats.tokens_per_forward

                                                                                                            speculative.py:215

                                                                                                            — → float

                                                                                                            每目标前向 token 数

                                                                                                            snapshot_caches

                                                                                                            speculative.py:221-235

                                                                                                            caches → snap

                                                                                                            深拷贝 cache

                                                                                                            restore_caches

                                                                                                            speculative.py:237-261

                                                                                                            (caches, snap)

                                                                                                            原地回滚

                                                                                                            RecomputeBackend.score_sequence

                                                                                                            speculative.py:274-278

                                                                                                            seq → (B,T,V)

                                                                                                            全序列打分

                                                                                                            CacheRollbackBackend.score_token

                                                                                                            speculative.py:306-314

                                                                                                            tok → (B,1,V)

                                                                                                            增量打分

                                                                                                            SpeculativeDecoder.decode_recompute

                                                                                                            speculative.py:372

                                                                                                            prompt → (tokens,stats)

                                                                                                            重跑路径循环

                                                                                                            SpeculativeDecoder.decode_rollback

                                                                                                            speculative.py:413

                                                                                                            prompt → (tokens,stats)

                                                                                                            快照-回滚路径循环

                                                                                                            5.6.10 代码

                                                                                                            验证结果

                                                                                                              @dataclass
                                                                                                              class VerifyResult:
                                                                                                                  """一轮 verify 的结果。


                                                                                                                  - ``accepted_tokens``:被接受的草稿 token ``(B, n_accepted)``。
                                                                                                                  - ``n_accepted``:接受前缀长度(每 batch 元素一个标量)。
                                                                                                                  - ``bonus_token``:被拒绝位置重采的 1 个 token ``(B, 1)``(即使全部接受
                                                                                                                    也重采 1 个,保证每轮净增 = 接受数 + 1,符合投机解码约定)。
                                                                                                                  - ``per_pos_ratios``:每个草稿位置的接受概率 ``p_i(c_i)/q_i(c_i)``。
                                                                                                                  """


                                                                                                                  accepted_tokens: Tensor
                                                                                                                  n_accepted: Tensor          # (B,)
                                                                                                                  bonus_token: Tensor         # (B, 1)
                                                                                                                  per_pos_ratios: Tensor      # (B, L)


                                                                                                              def verify_tokens(
                                                                                                                  target_logits: Tensor,
                                                                                                                  draft_logits: Tensor,
                                                                                                                  draft_tokens: Tensor,
                                                                                                                  *,
                                                                                                                  greedy: bool = False,
                                                                                                                  generator: Optional[torch.Generator] = None,
                                                                                                              ) -> VerifyResult:
                                                                                                                  """lossless 接受判据(纯函数,不碰模型)。


                                                                                                                  参数:
                                                                                                                  - ``target_logits`` ``(B, L, V)``:目标模型对 L 个草稿候选位置的分布。
                                                                                                                  - ``draft_logits``   ``(B, L, V)``:草稿模型自己的分布。
                                                                                                                  - ``draft_tokens``   ``(B, L)``:草稿在每位置提出的 token id。
                                                                                                                  - ``greedy``:True 走 argmax 确定性匹配(测试用);False 走 lossless
                                                                                                                    随机接受(u <= p(c)/q(c))。
                                                                                                                  - ``generator``:随机源(可复现测试)。


                                                                                                                  返回 ``VerifyResult``。语义:逐位置判定,一旦拒绝立即截断,并在拒绝位置
                                                                                                                  重采 1 个 bonus token。
                                                                                                                  """
                                                                                                                  B, L, _ = target_logits.shape
                                                                                                                  # softmax 得概率分布 p(目标)与 q(草稿)。
                                                                                                                  p = torch.softmax(target_logits.float(), dim=-1)
                                                                                                                  q = torch.softmax(draft_logits.float(), dim=-1)
                                                                                                                  # 每个草稿位置提出 token 的被接受概率 p_i(c_i) / q_i(c_i)。
                                                                                                                  p_c = p.gather(-1, draft_tokens.unsqueeze(-1)).squeeze(-1)   # (B, L)
                                                                                                                  q_c = q.gather(-1, draft_tokens.unsqueeze(-1)).squeeze(-1)   # (B, L)
                                                                                                                  ratio = (p_c / q_c.clamp_min(1e-9)).clamp_max(1.0)          # (B, L)
                                                                                                                  # ratio 上限 clamp 到 1:当 q_i(c_i) 极小导致比值 >1 时按 1 算,即"该位置
                                                                                                                  # 无条件接受",与 lossless 采样惯例一致(接受概率不可能 >1)。


                                                                                                                  if greedy:
                                                                                                                      # 确定性路径:草稿 token == 目标 argmax 才算接受。
                                                                                                                      target_arg = target_logits.argmax(-1)                    # (B, L)
                                                                                                                      accepted = (draft_tokens == target_arg)
                                                                                                                  else:
                                                                                                                      # lossless 随机路径:采 u,u <= ratio 则接受。
                                                                                                                      u = torch.rand(
                                                                                                                          (B, L), dtype=torch.float32, device=target_logits.device, generator=generator
                                                                                                                      )
                                                                                                                      accepted = (u <= ratio)


                                                                                                                  # 逐 batch 求"连续接受前缀"长度:第一个 False 之前的 True 个数。
                                                                                                                  n_accepted_list = []
                                                                                                                  for b in range(B):
                                                                                                                      n = 0
                                                                                                                      for flag in accepted[b].tolist():
                                                                                                                          if flag:
                                                                                                                              n += 1
                                                                                                                          else:
                                                                                                                              break
                                                                                                                      n_accepted_list.append(n)
                                                                                                                  n_accepted = torch.tensor(n_accepted_list, device=target_logits.device)  # (B,)


                                                                                                                  # 接受前缀的 token;长度取所有 batch 中最大接受数(不足由调用方按 n_accepted 截)。
                                                                                                                  max_acc = int(n_accepted.max().item()) if B else 0
                                                                                                                  if max_acc > 0:
                                                                                                                      accepted_tokens = draft_tokens[:, :max_acc]
                                                                                                                  else:
                                                                                                                      accepted_tokens = draft_tokens.new_zeros(B, 0)


                                                                                                                  # bonus token:在"被拒绝的位置"(= 接受前缀末尾)重采。
                                                                                                                  # 分布 = norm(max(p - q, 0))。若全部接受,则在最后一个草稿位置重采,
                                                                                                                  # 分布取 p(目标)在该位置的分布。
                                                                                                                  bonus_token = torch.zeros(B, 1, dtype=torch.long, device=target_logits.device)
                                                                                                                  for b in range(B):
                                                                                                                      nb = int(n_accepted[b].item())
                                                                                                                      if nb < L:
                                                                                                                          pos = nb
                                                                                                                          residual = torch.clamp(p[b, pos] - q[b, pos], min=0.0)   # (V,)
                                                                                                                      else:
                                                                                                                          pos = L - 1
                                                                                                                          residual = p[b, pos]                                      # 全部接受
                                                                                                                      total = residual.sum().clamp_min(1e-9)
                                                                                                                      probs = residual / total
                                                                                                                      if greedy:
                                                                                                                          bonus_token[b, 0] = probs.argmax()
                                                                                                                      else:
                                                                                                                          bonus_token[b, 0] = torch.multinomial(probs, 1, generator=generator).item()


                                                                                                                  return VerifyResult(
                                                                                                                      accepted_tokens=accepted_tokens,
                                                                                                                      n_accepted=n_accepted,
                                                                                                                      bonus_token=bonus_token,
                                                                                                                      per_pos_ratios=ratio,
                                                                                                                  )




                                                                                                              cache 快照 / 恢复

                                                                                                                # ---------------------------------------------------------------------------
                                                                                                                # cache 快照 / 恢复(按 cache 类型分派)
                                                                                                                # ---------------------------------------------------------------------------


                                                                                                                def _is_kda(c) -> bool:
                                                                                                                    # 用鸭子类型判断(避免 src 与 models 两个模块命名空间导致的 isinstance 失效)。
                                                                                                                    return hasattr(c, "state") and hasattr(c, "conv_q")


                                                                                                                def _is_mla(c) -> bool:
                                                                                                                    return hasattr(c, "kv_latent") and hasattr(c, "length")


                                                                                                                def snapshot_caches(caches: list) -> list:
                                                                                                                    """深拷贝整组 cache(投机解码开始前的状态)。


                                                                                                                    返回与 ``caches`` 等长的副本列表。KDA 用 ``KDACache.clone``,MLA 用
                                                                                                                    ``MLACache.clone``,其他对象(MTP 层 cache)回退到 ``copy.deepcopy``。
                                                                                                                    """
                                                                                                                    import copy
                                                                                                                    snap = []
                                                                                                                    for c in caches:
                                                                                                                        if _is_kda(c) or _is_mla(c):
                                                                                                                            snap.append(c.clone())
                                                                                                                        else:
                                                                                                                            snap.append(copy.deepcopy(c))
                                                                                                                    return snap


                                                                                                                def restore_caches(caches: list, snap: list) -> None:
                                                                                                                    """把 ``caches`` 原地恢复成 ``snap`` 的快照(回滚未验证的续写)。


                                                                                                                    投机部分接受后,草稿被拒绝位置对应的状态必须丢弃。恢复策略:
                                                                                                                    - MLA:latent 被增量前向追加了草稿 latent,需把 ``kv_latent`` 切回快照
                                                                                                                      长度并恢复数值基线;
                                                                                                                    - KDA:直接覆盖 ``state`` 与三个卷积窗口;
                                                                                                                    - 未知类型:逐属性覆盖(投机不深挖内部)。
                                                                                                                    """
                                                                                                                    for c, s in zip(caches, snap):
                                                                                                                        if _is_kda(c):
                                                                                                                            c.state = s.state.clone()
                                                                                                                            c.conv_q = s.conv_q.clone()
                                                                                                                            c.conv_k = s.conv_k.clone()
                                                                                                                            c.conv_v = s.conv_v.clone()
                                                                                                                        elif _is_mla(c):
                                                                                                                            c.kv_latent = s.kv_latent.clone()
                                                                                                                            c.length = s.length
                                                                                                                        else:
                                                                                                                            for k, v in vars(s).items():
                                                                                                                                setattr(c, k, v)


                                                                                                                # ---------------------------------------------------------------------------
                                                                                                                # 打分后端:Recompute(参考 oracle)与 CacheRollback(快照-回滚)
                                                                                                                # ---------------------------------------------------------------------------


                                                                                                                class RecomputeBackend:
                                                                                                                    """重跑后端:每轮用**无 cache 的全序列 forward** 打分。


                                                                                                                    正确性由构造保证(重跑即重新计算所有位置),代价是每轮 O(T²)。
                                                                                                                    作为参考 oracle,用于校验 Rollback 后端的正确性。
                                                                                                                    """


                                                                                                                    def __init__(self, model):
                                                                                                                        self.model = model


                                                                                                                    def score_sequence(self, seq: Tensor) -> Tensor:
                                                                                                                        out = self.model(seq)          # 无 cache,全序列
                                                                                                                        if isinstance(out, dict):
                                                                                                                            out = out["logits"]
                                                                                                                        return out


                                                                                                                def _extract_features(model, hidden: Tensor, attn_res_state) -> list:
                                                                                                                    """从目标模型取出 EAGLE-3 特征融合用的完整出口列表。


                                                                                                                    - AttnRes 启用时:从 ``attn_res_state`` 取**全部**可读 sources(不做选择,
                                                                                                                      选择统一交给 ``Eagle3Draft.fuse()``,见 A3 职责划分)。
                                                                                                                    - AttnRes 关闭时:无状态可读,退化为"重复 hidden"作为单源(教学回退)。
                                                                                                                      文档会注明:真实 EAGLE-3 需要 AttnRes 特征;这里保证 demo 可跑通。
                                                                                                                    """
                                                                                                                    if attn_res_state is not None:
                                                                                                                        try:
                                                                                                                            feats = eagle3_feature_stack(attn_res_state, picks=None)  # 摊平全部
                                                                                                                            if len(feats) >= 3:
                                                                                                                                return feats
                                                                                                                        except (TypeError, IndexError):
                                                                                                                            pass
                                                                                                                    # 回退:单源 hidden 重复 5 次(教学用),使 feature_blocks=(0,3,-1) 能取到
                                                                                                                    # 低/中/高,且 fuse 仍是 W_E3·[h;h;h;h;h]。
                                                                                                                    return [hidden] * 5


                                                                                                                class CacheRollbackBackend:
                                                                                                                    """快照-回滚后端:增量打分 + 部分接受时恢复快照。


                                                                                                                    与 RecomputeBackend 的差异:它持有**增量 cache**,逐 token 前向打分,
                                                                                                                    而每轮 verify 之后由 ``SpeculativeDecoder.decode_rollback`` 负责恢复
                                                                                                                    cache 到已接受前缀末尾。两类后端须产出逐 token 一致的 token 流。
                                                                                                                    """


                                                                                                                    def __init__(self, model):
                                                                                                                        self.model = model
                                                                                                                        # 增量 cache(由 decode_rollback 维护并传入)。
                                                                                                                        self.caches = None


                                                                                                                    def score_token(self, tok: Tensor) -> Tensor:
                                                                                                                        """对单个新 token ``(B, 1)`` 增量前向,返回 ``(B, 1, V)`` 分布。


                                                                                                                        使用 ``self.caches`` 累积历史;注意返回后 cache 已被推进一格。
                                                                                                                        """
                                                                                                                        out = self.model(tok, caches=self.caches)
                                                                                                                        if isinstance(out, dict):
                                                                                                                            out = out["logits"]
                                                                                                                        return out




                                                                                                                端到端投机解码循环

                                                                                                                  class SpeculativeDecoder:
                                                                                                                      """端到端投机解码循环:Kimi3ForCausalLM × Eagle3Draft。


                                                                                                                      提供两条**语义等价的打分路径**,用于验证回滚正确性:
                                                                                                                      - ``decode_recompute``:每轮无 cache 全序列重跑(参考 oracle)。
                                                                                                                      - ``decode_rollback``  :快照 cache、增量打分、部分接受时回滚。
                                                                                                                      两者在固定 seed 下产出的 token 流逐 token 一致。


                                                                                                                      特征提取统一走 ``_extract_features``:AttnRes 启用取真实低/中/高特征,
                                                                                                                      否则回退到 hidden 重复(教学用)。
                                                                                                                      """


                                                                                                                      def __init__(
                                                                                                                          self,
                                                                                                                          model,
                                                                                                                          draft: Eagle3Draft,
                                                                                                                          *,
                                                                                                                          greedy: bool = False,
                                                                                                                          generator: Optional[torch.Generator] = None,
                                                                                                                      ):
                                                                                                                          self.model = model
                                                                                                                          self.draft = draft
                                                                                                                          self.greedy = greedy
                                                                                                                          self.generator = generator


                                                                                                                      # ---- 特征与融合 --------------------------------------------------------
                                                                                                                      def _features(self, hidden: Tensor) -> list:
                                                                                                                          state = getattr(self.model.model, "_attn_res_state", None)
                                                                                                                          return _extract_features(self.model, hidden, state)


                                                                                                                      def _fused(self, hidden: Tensor) -> Tensor:
                                                                                                                          return self.draft.fuse(self._features(hidden))


                                                                                                                      # ---- 公共:从目标打分 + verify 一个草稿窗口 -----------------------------
                                                                                                                      def _run_round(self, hidden: Tensor, draft_len: int):
                                                                                                                          """给定当前目标隐藏态,draft L 步并返回草稿 token/logits。"""
                                                                                                                          fused = self._fused(hidden)
                                                                                                                          draft_tokens, draft_logits = self.draft.draft(
                                                                                                                              fused, self.model.model.tok_embed, n_steps=draft_len
                                                                                                                          )
                                                                                                                          return draft_tokens, draft_logits


                                                                                                                      @torch.no_grad()
                                                                                                                      def decode_recompute(
                                                                                                                          self,
                                                                                                                          prompt: Tensor,
                                                                                                                          *,
                                                                                                                          max_new_tokens: int,
                                                                                                                          draft_len: int,
                                                                                                                      ) -> tuple[Tensor, SpecDecodeStats]:
                                                                                                                          """重跑路径:每轮全序列打分(参考 oracle)。"""
                                                                                                                          tokens = prompt.clone()
                                                                                                                          stats = SpecDecodeStats()
                                                                                                                          B = prompt.shape[0]
                                                                                                                          # 打分后端:与 decode_rollback 的 CacheRollbackBackend 对称。
                                                                                                                          # 该后端无状态(不持 cache),每轮用无 cache 全序列 forward 打分。
                                                                                                                          backend = RecomputeBackend(self.model)
                                                                                                                          n_new = 0
                                                                                                                          while n_new < max_new_tokens:
                                                                                                                              # 目标前向(全序列),取隐藏态(model.model 是去掉 lm_head 的骨架)。
                                                                                                                              hidden = self.model.model(tokens)
                                                                                                                              # draft
                                                                                                                              draft_tokens, draft_logits = self._run_round(hidden, draft_len)
                                                                                                                              # 目标对"草稿位置"打分:拼接后全序列重跑
                                                                                                                              cand = torch.cat([tokens, draft_tokens], dim=1)
                                                                                                                              tgt = backend.score_sequence(cand)
                                                                                                                              cur = tokens.shape[1]
                                                                                                                              tgt_draft = tgt[:, cur:cur + draft_len]
                                                                                                                              vr = verify_tokens(
                                                                                                                                  tgt_draft, draft_logits, draft_tokens,
                                                                                                                                  greedy=self.greedy, generator=self.generator,
                                                                                                                              )
                                                                                                                              na = int(vr.n_accepted[0].item())
                                                                                                                              stats.record(na, draft_len)
                                                                                                                              accepted = vr.accepted_tokens[0][:na]
                                                                                                                              new_chunk = torch.cat([accepted, vr.bonus_token[0]], dim=0)
                                                                                                                              tokens = torch.cat([tokens, new_chunk.unsqueeze(0)], dim=1)
                                                                                                                              n_new += int(new_chunk.shape[0])
                                                                                                                              # 全部拒绝时只剩 bonus token,下一轮 draft→verify 纯属浪费,提前退出。
                                                                                                                              if na == 0:
                                                                                                                                  break            
                                                                                                                          return tokens, stats


                                                                                                                      def _score_candidates(self, seq: Tensor) -> Tensor:
                                                                                                                          out = self.model(seq)
                                                                                                                          if isinstance(out, dict):
                                                                                                                              out = out["logits"]
                                                                                                                          return out


                                                                                                                      @torch.no_grad()
                                                                                                                      def decode_rollback(
                                                                                                                          self,
                                                                                                                          prompt: Tensor,
                                                                                                                          *,
                                                                                                                          max_new_tokens: int,
                                                                                                                          draft_len: int,
                                                                                                                      ) -> tuple[Tensor, SpecDecodeStats]:
                                                                                                                          """快照-回滚路径:增量打分,部分接受时恢复 cache 并重放。


                                                                                                                          这是把 ``serve/decode.py`` 的回滚动机真正接到 EAGLE-3 的实现:
                                                                                                                          - 每一轮开始前**快照** cache;
                                                                                                                          - 逐草稿位置**增量**前向打分(只有 1 次小步前向,而非全序列重跑);
                                                                                                                          - verify 后,被拒绝的后缀丢弃:恢复快照,再重放已接受前缀。
                                                                                                                          """
                                                                                                                          tokens = prompt.clone()
                                                                                                                          stats = SpecDecodeStats()
                                                                                                                          B = prompt.shape[0]
                                                                                                                          device = prompt.device
                                                                                                                          # 初始化增量 cache,并把 prompt 预填进去。
                                                                                                                          backend = CacheRollbackBackend(self.model)
                                                                                                                          caches = self.model.init_caches(B, device=device, dtype=torch.float32)
                                                                                                                          # 预填:把整个 prompt 一次性前向,让 cache 记录历史。
                                                                                                                          self.model(tokens, caches=caches)
                                                                                                                          backend.caches = caches
                                                                                                                          n_new = 0


                                                                                                                          while n_new < max_new_tokens:
                                                                                                                              # 特征/融合:对"当前已接受序列"做一次**无 cache 全序列重跑**,
                                                                                                                              # 与 Recompute 路径完全一致(保证两种后端特征相同)。
                                                                                                                              # cache 只用于下方对草稿位置的增量打分,二者正交。
                                                                                                                              hidden = self.model.model(tokens)
                                                                                                                              fused = self._fused(hidden)                 # (B, T, d)
                                                                                                                              draft_tokens, draft_logits = self.draft.draft(
                                                                                                                                  fused, self.model.model.tok_embed, n_steps=draft_len
                                                                                                                              )
                                                                                                                              # 逐草稿位置增量打分,收集目标分布
                                                                                                                              tgt_logits_list = []
                                                                                                                              step_caches_snap = snapshot_caches(caches)
                                                                                                                              for j in range(draft_len):
                                                                                                                                  tok = draft_tokens[:, j:j + 1]
                                                                                                                                  lg = backend.score_token(tok)
                                                                                                                                  tgt_logits_list.append(lg[:, -1:])
                                                                                                                              tgt_draft = torch.cat(tgt_logits_list, dim=1)   # (B, L, V)
                                                                                                                              vr = verify_tokens(
                                                                                                                                  tgt_draft, draft_logits, draft_tokens,
                                                                                                                                  greedy=self.greedy, generator=self.generator,
                                                                                                                              )
                                                                                                                              na = int(vr.n_accepted[0].item())
                                                                                                                              stats.record(na, draft_len)


                                                                                                                              # 回滚:恢复快照,再重放已接受前缀,使 cache 停在被接受末尾。
                                                                                                                              restore_caches(caches, step_caches_snap)
                                                                                                                              accepted = vr.accepted_tokens[0][:na]      # (na,)
                                                                                                                              for j in range(na):
                                                                                                                                  backend.score_token(accepted[j:j + 1].unsqueeze(0))  # (1,1)
                                                                                                                              # bonus:被拒绝位置重采的 token 也要消费进 cache(它成为新历史)。
                                                                                                                              backend.score_token(vr.bonus_token[0:1])   # (1,1)
                                                                                                                              new_chunk = torch.cat([accepted, vr.bonus_token[0]], dim=0)
                                                                                                                              tokens = torch.cat([tokens, new_chunk.unsqueeze(0)], dim=1)
                                                                                                                              n_new += int(new_chunk.shape[0])
                                                                                                                              # 全部拒绝时只剩 bonus token,下一轮 draft→verify 纯属浪费,提前退出。
                                                                                                                              if na == 0:
                                                                                                                                  break            
                                                                                                                          return tokens, stats




                                                                                                                  5.6.11 对比基线与实测数据(回填自 eagle3_demo.py)

                                                                                                                  CPU 小模型(dim=64, n_layers=2, vocab=100),greedy 与 lossless 两路实测:

                                                                                                                  指标

                                                                                                                  无投机(基线)

                                                                                                                  greedy(随机草稿)

                                                                                                                  lossless(随机草稿)

                                                                                                                  实测接受率

                                                                                                                  —

                                                                                                                  0.0000

                                                                                                                  0.1296

                                                                                                                  tokens/forward

                                                                                                                  1.0

                                                                                                                  1.000

                                                                                                                  1.389

                                                                                                                  理论 E[tokens/target](同 r,L=3)

                                                                                                                  1.0

                                                                                                                  1.000

                                                                                                                  1.149

                                                                                                                  Recompute vs Rollback 一致

                                                                                                                  —

                                                                                                                  True

                                                                                                                  —

                                                                                                                  关键读数(eagle3_demo.py 输出):

                                                                                                                  • 两路径 token 流逐 token 一致(greedy):Recompute 与 Rollback 输出完全相等 → 回滚正确性的数值证明。

                                                                                                                  • lossless 实测接受率 0.13、tokens/forward 1.389,显著 > 无投机基线 1.0。

                                                                                                                  • 有趣现象:实测 tokens/forward(1.389)> 理论(1.149)。原因:每轮"bonus token"是接受公式之外的额外净增(即使全拒也 +1),而 speedup_from_acceptance 只算接受带来的增益。这是教学上的诚实观察——真实收益比纯接受率公式更高(但受草稿质量上限约束)。

                                                                                                                  5.6.12 反方辩手 / 边界条件

                                                                                                                  • a) 最强反对:草稿质量决定一切。若草稿接受率 ≈ 0(如上表 greedy 随机草稿),投机解码退化为"每轮净增 1 token"+ 额外草稿开销,反而更慢。真实加速依赖训练好的草稿(r≈0.8+)。

                                                                                                                  • b) 若失败,最可能错:KDA 状态回滚的假设——本实现的 Rollback 用"快照恢复 + 重放";工业上 serve/decode.py 用投影重演(零快照)。若快照成本高于重演,大 draft 长序列下不划算。

                                                                                                                  • c) 胜出:目标模型深(93 层)、草稿接受率高、draft 短;失败:草稿未训练、目标浅、序列短。

                                                                                                                  • d) 更稳健:Recompute 后端永远正确(慢但无损),可作任何回滚实现的对照基准——本项目的"两后端一致"测试正是这个思想。

                                                                                                                  • e) 受影响方:推理方(收益)、训练方(需额外训草稿、QAT)、草稿保存与加载方(多一套模型文件)。

                                                                                                                  5.7 探讨代码(experiments\models\llm\kimi_k3\mtp\eagle3_demo.py)

                                                                                                                  实验

                                                                                                                  内容

                                                                                                                  实测结论(回填)

                                                                                                                  E1

                                                                                                                  纯 LM vs LM+0.5·MTP 的 lm_loss(30 步,同权重起步)

                                                                                                                  纯 LM 4.225→3.470;LM+MTP 4.192→4.024。窄模型+小数据下 MTP 未显著更优

                                                                                                                  E2

                                                                                                                  融合初值 [0 0 I] vs 随机 vs 全零(目标=高层恒等,60 步)

                                                                                                                  [0 0 I]

                                                                                                                   error 0→0(零扰动);随机 1.3584→0.0010;全零 1.0393→0.0007

                                                                                                                  E3

                                                                                                                  接受率→加速比理论扫曲线(L=1/2/4/7)

                                                                                                                  r=0.8,L=7 → 4.16 token/次目标前向(表格见下)

                                                                                                                  E4

                                                                                                                  偏移对齐 sanity(T=16)

                                                                                                                  MTP 输出形状 (B,T-1,V)=(2,7,64);换掉 next_emb → logits avg

                                                                                                                  E3 加速比实测表(speedup_from_acceptance)

                                                                                                                     r     L=1     L=2     L=4     L=7
                                                                                                                    0.20   1.20    1.24    1.25    1.25
                                                                                                                    0.50   1.50    1.75    1.94    1.99
                                                                                                                    0.70   1.70    2.19    2.77    3.14
                                                                                                                    0.80   1.80    2.44    3.36    4.16
                                                                                                                    0.90   1.90    2.71    4.10    5.70
                                                                                                                    0.95   1.95    2.85    4.52    6.73



                                                                                                                    附录


                                                                                                                    附录 A:三方参考核对对照表(file:line 汇总)

                                                                                                                    项

                                                                                                                    kimi3-master

                                                                                                                    kimi-k3-pytorch

                                                                                                                    本项目

                                                                                                                    融合层

                                                                                                                    model.py:262fusion.py:44-47mtp_layer.py:128-131

                                                                                                                    proj bias

                                                                                                                    model.py:250

                                                                                                                    (无)

                                                                                                                    fusion.py:23

                                                                                                                    (无)

                                                                                                                    mtp_layer.py:97

                                                                                                                    (无)

                                                                                                                    骨架块

                                                                                                                    model.py:251

                                                                                                                    (Kimi3Block,dense_ffn=False)

                                                                                                                    block.py:25-48

                                                                                                                    (Hybrid 组)

                                                                                                                    mtp_layer.py:105-107

                                                                                                                    (Kimi3Block, MoE)

                                                                                                                    目标

                                                                                                                    model.py:346-347

                                                                                                                    (labels[:,2:])

                                                                                                                    alignment.py:87-89model.py:409-410

                                                                                                                    loss_weight

                                                                                                                    0.3(config.py:160)

                                                                                                                    0.1(config.py:26)

                                                                                                                    0.3(config.py:146)

                                                                                                                    EAGLE-3 初值

                                                                                                                    eagle3.py:75-79

                                                                                                                    —(fusion 随机)

                                                                                                                    eagle3.py:87-91

                                                                                                                    LK 损失

                                                                                                                    eagle3.py:53-62

                                                                                                                    —(kimi-k 主用 CE_aux)

                                                                                                                    eagle3.py:63-70

                                                                                                                    Draft

                                                                                                                    eagle3.py:97-133head.py:295-339

                                                                                                                    (单步)

                                                                                                                    eagle3.py:146-191
                                                                                                                    verify/端到端无

                                                                                                                    (官方也没有)

                                                                                                                    —

                                                                                                                    speculative.py:73-475(自研扩展)
                                                                                                                     

                                                                                                                    口径一致性结论:三方预测 x[t+2] 语义一致;loss_weight 默认 0.3 vs 0.1 差异已在配置层显式化。verify 环节kimi3-master缺失,本项目补齐。

                                                                                                                    ”

                                                                                                                    附录B. 实测数据 (来自项目实验)

                                                                                                                    B1: 联合损失 vs 纯 LM

                                                                                                                      纯 LM    : lm_loss 4.225 → 3.470  (Δ0.755)
                                                                                                                      LM+MTP(0.5) : lm_loss 4.192 → 4.024  (Δ0.168)
                                                                                                                      终结差距: +0.554 (联合目标下 lm 更低)



                                                                                                                       

                                                                                                                      在小模型上 MTP 的正则化收益需要更大规模才能充分体现。

                                                                                                                      ”

                                                                                                                      B2: [0 0 I] 初始化的优势

                                                                                                                        [0 0 I] 初始化: 初始误差 0.0000 → 最终 ~0.0000
                                                                                                                        随机初始化   : 初始误差 1.3484 → 最终 ~0.0010
                                                                                                                        He 初始化    : 初始误差 1.0393 → 最终 ~0.0007



                                                                                                                         

                                                                                                                        [0 0 I] 从零误差起步 (= MTP 预训练的已知好点), 避免了随机初始化带来的初期反向传播噪声。

                                                                                                                        ”

                                                                                                                        B3: 接受率 → 加速比理论表

                                                                                                                        接受率 r

                                                                                                                        L=1

                                                                                                                        L=2

                                                                                                                        L=4

                                                                                                                        L=7

                                                                                                                        0.5

                                                                                                                        1.50

                                                                                                                        1.75

                                                                                                                        1.94

                                                                                                                        1.99

                                                                                                                        0.7

                                                                                                                        1.70

                                                                                                                        2.19

                                                                                                                        2.77

                                                                                                                        3.14

                                                                                                                        0.8

                                                                                                                        1.80

                                                                                                                        2.44

                                                                                                                        3.36

                                                                                                                        4.16

                                                                                                                        0.9

                                                                                                                        1.90

                                                                                                                        2.71

                                                                                                                        4.10

                                                                                                                        5.70

                                                                                                                        0.95

                                                                                                                        1.95

                                                                                                                        2.85

                                                                                                                        4.52

                                                                                                                        6.73

                                                                                                                         

                                                                                                                        r=0.8 + L=7 时,每个目标前向产出约 4.16 个 token— 即 MTP 预训练 + 特征融合训练的那一层所贡献的推理加速上限。

                                                                                                                        ”

                                                                                                                        B4: 偏移对齐 sanity

                                                                                                                          MTP 输出形状: (2, 7, 64) (B=2, T‑1=7, V=64)
                                                                                                                          打乱 next_emb 后 logits 变化 |Δ| = 0.5494
                                                                                                                          → MTP 确实用上了 x[t+1] 的嵌入信息
                                                                                                                          _mtp_loss(labels[:,2:] 对齐) = 4.3158




                                                                                                                          附录C. 代码位置索引

                                                                                                                          文件

                                                                                                                          内容

                                                                                                                          src/models/llm/kimi_k3/mtp/mtp_layer.py

                                                                                                                          MTP 层本体 (双 token 并行预测层)

                                                                                                                          src/models/llm/kimi_k3/mtp/eagle3.py

                                                                                                                          EAGLE‑3 草稿模型 (特征融合 + LK 损失 + draft 自回归)

                                                                                                                          src/models/llm/kimi_k3/mtp/speculative.py

                                                                                                                          投机解码 verify + 端到端循环 (Recompute/Rollback 两条路径)

                                                                                                                          src/models/llm/kimi_k3/mtp/__init__.py

                                                                                                                          包导出 + MTP⇨EAGLE 谱系文档

                                                                                                                          src/models/llm/kimi_k3/config.pyMTPConfig

                                                                                                                           + Kimi3Config (含 MTP 配置与校验 n_layers==1)

                                                                                                                          src/models/llm/kimi_k3/model.pyKimi3ForCausalLM

                                                                                                                           (MTP 集成 + _mtp_logits + _mtp_loss)

                                                                                                                          src/server/decode.py

                                                                                                                          KDA 投机回滚 (投影缓存 + verify_and_replay)

                                                                                                                          experiments/mtp/discussion.py

                                                                                                                          E1‑E4 四组探讨实验

                                                                                                                          experiments/mtp/eagle3_demo.py

                                                                                                                          EAGLE‑3 投机解码端到端 demo

                                                                                                                          experiments/mtp/plot_mtp.py

                                                                                                                          MTP/EAGLE‑3 可视化

                                                                                                                          附录D. 可视化与输出

                                                                                                                          D.1 可视化脚本

                                                                                                                          • experiments/mtp/plot_mtp.py:plot_mtp_offset.png、plot_e1_joint_loss.png、plot_e2_init_curve.png、plot_e3_speedup.png。

                                                                                                                          • experiments/mtp/eagle3_demo.py:plot_e5_measured_speedup.png(实测点 vs 理论)。

                                                                                                                          D.2 截图说明

                                                                                                                          • plot_mtp_offset.png:token 流示意,LM(h[t]→x[t+1])与 MTP(h[t]⊕emb(x[t+1])→x[t+2])两条监督路径。

                                                                                                                            plot_mtp_offset
                                                                                                                            plot_mtp_offset
                                                                                                                          • plot_e1_joint_loss.png:干 LM vs 联合目标 lm_loss 曲线;教学尺度下联合未显著占优。

                                                                                                                            plot_e1_joint_loss
                                                                                                                            plot_e1_joint_loss
                                                                                                                          • plot_e2_init_curve.png:三条初值误差曲线([0 0 I] 恒 0、随机/全零收敛)。

                                                                                                                            plot_e2_init_curve
                                                                                                                            plot_e2_init_curve
                                                                                                                          • plot_e3_speedup.png:4 条理论加速比曲线 + 星标(r=0.8,L=7→4.16)。

                                                                                                                            plot_e3_speedup
                                                                                                                            plot_e3_speedup
                                                                                                                          • plot_e5_measured_speedup.png(V3 新增):理论曲线 + 红色实测星标(lossless 实际接受率/加速点),展示"理论上限 vs 实际"。

                                                                                                                            plot_e5_measured_speedup
                                                                                                                            plot_e5_measured_speedup

                                                                                                                          D.3 实测数值回填

                                                                                                                          图

                                                                                                                          关键读数

                                                                                                                          关键推论

                                                                                                                          plot_mtp_offset

                                                                                                                          概念示意

                                                                                                                          双监督路径

                                                                                                                          plot_e1_joint_loss

                                                                                                                          干 LM 4.225→3.470;联合 4.192→4.024

                                                                                                                          窄配置下联合未占优(教学诚实)

                                                                                                                          plot_e2_init_curve

                                                                                                                          [0 0 I]=0

                                                                                                                          ;随机=1.33→收敛

                                                                                                                          [0 0 I]

                                                                                                                           零扰动守护 MTP 预训练输入

                                                                                                                          plot_e3_speedup

                                                                                                                          r=0.8,L=7 → 4.16

                                                                                                                          草稿接受率直接转加速(理论上限)

                                                                                                                          plot_e5_measured_speedup

                                                                                                                          lossless 实测 r=0.13, tokens/forward=1.389

                                                                                                                          实测点验证了"接受率→加速"机制

                                                                                                                          ,且因 bonus 每轮净增,实测略高于纯接受率公式


                                                                                                                          TransFormer-封面
                                                                                                                          TransFormer-封面

                                                                                                                          0xFF 参考

                                                                                                                          阅读原文

                                                                                                                          跳转微信打开

                                                                                                                          •  

                                                                                                                          【轻量化复刻大模型 / KIMI K3】MoonEP 源码深度解读

                                                                                                                          原创 罗西的思考 2026-11-15 15:17 北京

                                                                                                                          【轻量化复刻大模型 / KIMI K3】MoonEP 源码深度解读

                                                                                                                          • 0x00 概要
                                                                                                                            • 0.1 主要内容
                                                                                                                            • 0.2 注意说明
                                                                                                                          • 0x01 演进脉络与定位
                                                                                                                            • 1.1 前身:标准 EP 的三重痛点
                                                                                                                            • 1.2 同期竞品
                                                                                                                            • 1.3 定位一句话
                                                                                                                            • 1.4 MoonEP vs DeepEP
                                                                                                                          • 0x02 原理讲解
                                                                                                                            • 2.1 直觉类比
                                                                                                                            • 2.2 准专业水平视角
                                                                                                                            • 2.3 专家视角
                                                                                                                            • 2.4 负载均衡的数学保证
                                                                                                                            • 2.5 拷贝权重
                                                                                                                          • 0x03 子知识点拆解
                                                                                                                            • 3.1 子知识点树状结构
                                                                                                                            • 3.2 官方代码位置标注
                                                                                                                            • 3.3 本项目复现
                                                                                                                          • 0x04 子知识点深度分析
                                                                                                                            • 4.0 共享抽象与设计动机
                                                                                                                            • 4.1 Buffer API 与 NVL 共享内存管理
                                                                                                                            • 4.2 Planning Kernel(4-phase 贪婪规划)
                                                                                                                            • 4.3 Dispatch Kernel(warp-specialized 派发)
                                                                                                                            • 4.4 Dispatch Epilogue(in-place 重复展开)
                                                                                                                            • 4.5 Combine Kernel(3-stage fp32 累加)
                                                                                                                            • 4.6 Prefetch + GradReduce(权重预取 + 梯度归约)
                                                                                                                            • 4.7 跨 rank 同步基础设施
                                                                                                                          • 0x05 本项目的实现 & 参考 & 讨论
                                                                                                                            • 5.1 具体代码
                                                                                                                            • 5.2 MoonEP-master 中的"决定拷贝哪些"与"实际拷贝"
                                                                                                                            • 5.3 本项目 `src/parallel/moonep.py` 中的对应位置
                                                                                                                            • 5.4 MoonEP 如何解决静态 shape 问题?
                                                                                                                          • 0xFF 参考

                                                                                                                          0x00 概要

                                                                                                                          0.1 主要内容

                                                                                                                          定位:MoonEP 是 Moonshot AI(Kimi 团队)开源的 Expert Parallelism 通信库,通过动态冗余专家实现完美负载均衡。本文基于 MoonEP-master/ 官方源码,逐模块拆解其设计与实现。

                                                                                                                          原始来源:MoonEP 没有正式的 arXiv 论文,以 GitHub 开源仓库形式发布:

                                                                                                                          • 标题:MoonEP: A Perfectly Balanced Expert Parallelism Library via Dynamic Redundant Experts

                                                                                                                          • 作者:Yutian Chen, Cong Li, Yucheng Wang, Ming Wei

                                                                                                                          • 机构:Moonshot AI(Kimi)

                                                                                                                          • 年份:2026

                                                                                                                          • 仓库:https://github.com/MoonshotAI/MoonEP

                                                                                                                          致谢与灵感来源:README 第 196-201 行列出灵感来源:

                                                                                                                          • DeepEP(DeepSeek):EP 通信库先驱

                                                                                                                          • Echo(arXiv:2603.07685):冗余专家调度理论

                                                                                                                          • UltraEP(Dots-Infra):EP 优化实现

                                                                                                                          • AcclEP(阿里巴巴):EP 通信库

                                                                                                                          符号约定:S = 每 rank 输入 token 数,K = 路由 top-k,E = EP 组内总路由专家数,R = EP rank 数,B = 每 rank 权重预取槽数,NvS = 每 rank 派发 token 槽位数(S*K real tokens + padding),H = 隐藏维度,H' = 专家 FFN 中间维度。

                                                                                                                          0.2 注意说明

                                                                                                                          • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

                                                                                                                          • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

                                                                                                                          • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

                                                                                                                          • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

                                                                                                                          • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

                                                                                                                          • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

                                                                                                                          • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                          • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。


                                                                                                                          0x01 演进脉络与定位

                                                                                                                          1.1 前身:标准 EP 的三重痛点

                                                                                                                          标准专家并行(如 Megatron-LM 的 EP)的做法是:每个 rank 持有 E/R 个专家,路由后直接把 token 发到对应 rank。这带来三个致命问题:

                                                                                                                          痛点

                                                                                                                          具体表现

                                                                                                                          根因

                                                                                                                          负载不均

                                                                                                                          Hot rank 的 token 数远超平均,拖慢整次同步

                                                                                                                          Top-K 路由的随机性

                                                                                                                          显存碎片

                                                                                                                          每步每层的激活 shape 不同,无法预分配固定缓冲

                                                                                                                          路由结果动态变化

                                                                                                                          Host 同步停滞

                                                                                                                          每层都要 host-device 同步才知道该分配多大显存

                                                                                                                          形状未知

                                                                                                                          1.2 同期竞品

                                                                                                                          方案

                                                                                                                          核心机制

                                                                                                                          优势

                                                                                                                          劣势

                                                                                                                          DeepEP v2

                                                                                                                          固定 EP + 动态 token 分配

                                                                                                                          简单,无冗余开销

                                                                                                                          负载不均时性能退化,显存碎片

                                                                                                                          Echo

                                                                                                                          冗余专家理论证明

                                                                                                                          理论基础扎实

                                                                                                                          无工程实现

                                                                                                                          UltraEP

                                                                                                                          EP 通信优化

                                                                                                                          低延迟

                                                                                                                          仍受负载不均影响

                                                                                                                          MoonEP

                                                                                                                          动态冗余专家 + GPU planning

                                                                                                                          完美均衡,零碎片

                                                                                                                          需要 NVLink 共享内存

                                                                                                                          1.3 定位一句话

                                                                                                                          不同于 DeepEP v2 的"固定分配 + 动态适应"做法,MoonEP 通过在线规划动态冗余专家实现了完美负载均衡——每个 rank 始终恰好计算 S×K 个 token,彻底消除 hot rank、显存碎片和 host 同步。

                                                                                                                          1.4 MoonEP vs DeepEP

                                                                                                                          我们首先比对下这两个方案。

                                                                                                                          • DeepEP:固定专家计算位置,优化数据搬运路径

                                                                                                                          • MoonEP:先调整专家计算位置,再按照新调度方案驱动数据流转

                                                                                                                          • MoonEP:本质是内置调度器的完整 MoE 执行运行时

                                                                                                                          • DeepEP:本质是面向对称显存、多 GPU 构建的 MoE 专用并行通信底座

                                                                                                                          • MoonEP:会先做一层调度判断:倘若专家归属关系(原始专家归属)造成部分 rank 负载过热,不必强制把全部 token 送往原归属 rank。它会将本轮部分专家的计算任务临时迁移至空闲 rank,再基于新的执行位置编排后续通信。

                                                                                                                          • DeepEP:EP 直接接收路由器输出的专家归属关系。专家驻留在哪一张 GPU rank,对应的 token 就必须发送至该 rank;库的核心目标是以最小化 SM 占用、HBM 拷贝、网络往返开销,将 all‑to‑all 通信压榨至硬件带宽极限。

                                                                                                                          • MoonEP plan:改写输出目标 rank,再为 GEMM 计算分配最终执行槽位。

                                                                                                                          • DeepEP layout:针对已经确定的目标 rank,分配通信槽位。

                                                                                                                          • MoonEP:允许专家参数的计算位置临时漂移。前向传播需要预取 gate/up/down 权重;反向传播中,冗余槽位产出的 fp32 梯度不能直接交付优化器,必须通过reduce_grad归并回原始主参数。对接上层框架时,需要同步修改权重 VMM、共享预取池、临时梯度 buffer、优化器执行时序等多处逻辑。

                                                                                                                          • DeepEP:遵循「token 去往参数所在位置」范式,原生适配标准 autograd 链路。dispatch 的反向为 combine,combine 的反向复用缓存 dispatch;专家参数始终仅在归属 home rank 完成计算,参数位置不会发生漂移。


                                                                                                                          0x02 原理讲解

                                                                                                                          2.1 直觉类比

                                                                                                                          想象一个快递站有 8 个分拣员(rank),每个分拣员专门负责一类包裹(专家)。传统做法是包裹来了就分给对应的分拣员,但如果某类包裹特别多,那个分拣员就会忙死,其他人闲着。

                                                                                                                          MoonEP 的做法是:先让调度员(planning kernel)看一眼当前所有包裹的分布,然后临时借调几个分拣员去帮忙处理那类特别多的包裹。借调的分拣员不是随便找的,而是从包裹最少的分拣员那里借——这样最后每个分拣员手里的包裹数完全一样。借调的分拣员需要先预习(prefetch)那类包裹的处理方法(权重),处理完后再把结果归还(reduce_grad)给原来的分拣员。

                                                                                                                          2.2 准专业水平视角

                                                                                                                          备注:此处符号参见后文 “符号与 shape 约定"。

                                                                                                                          输入输出 shape:

                                                                                                                            输入:
                                                                                                                              hidden_sh:        [S, H]      bf16  — 本 rank 的 S 个 token
                                                                                                                              route_weights_sk: [S, K]      fp32  — 每 token 的 K 个路由权重
                                                                                                                              topk_experts_sk:  [S, K]      int32 — 每 token 的 K 个路由专家 id
                                                                                                                              tokens_per_expert: [E]        int32 — 每个专家在本 rank 收到的 token 数


                                                                                                                            输出(dispatch):
                                                                                                                              hidden_nvsh:       [NvS, H]   bf16  — 派发到 VM group 位置的 token
                                                                                                                              route_weights_nvs: [NvS]      fp32  — 对应的路由权重
                                                                                                                              cu_seqlens:        [E+B]      int32 — 每个 VM group 行的 padded token 末偏移
                                                                                                                              plan:              MoonEPCommPlan — 保存用于后续 combine/反向的通信计划

                                                                                                                            核心公式:

                                                                                                                            MoonEP 的核心不是数学公式,而是一个构造性算法:

                                                                                                                            1. 目标:让每个 rank 恰好持有 S×K 个 token

                                                                                                                            2. 容量界:M(I) ≤ E/R,即每 rank 最多冗余 E/R 个专家副本

                                                                                                                            3. 构造:反复从"最过载 rank"搬运 token 到"最欠载 rank",每次精确填满欠载者

                                                                                                                            与标准做法的对比:

                                                                                                                              标准 EP:
                                                                                                                                rank_i 的 token 数 = Σ_e token_per_expert[e]  (e 属于 rank_i 的专家)
                                                                                                                                → 不确定,可能从 0.5*S*K 到 2*S*K 不等


                                                                                                                              MoonEP:
                                                                                                                                rank_i 的 token 数 = S*K  (恒等)
                                                                                                                                → 静态形状,固定缓冲,无 host 同步

                                                                                                                              2.3 专家视角

                                                                                                                              为什么这个设计在理论上 work?

                                                                                                                              MoonEP 的理论基础是K3 report 附录 E 的定理:M(I) ≤ E/R。直觉是:即使路由极端不均(所有 token 都路由到同一个专家),那个专家最多需要从其他 rank 借 E/R 个副本——因为每个 rank 只持有 E/R 个本地专家,所以冗余副本数不可能超过 E/R。

                                                                                                                              KIMI-K3-report-E
                                                                                                                              KIMI-K3-report-E

                                                                                                                              关键设计决策:

                                                                                                                              1. 为什么用贪婪而非最优? 贪婪算法 O(R²) 复杂度,最优解是 NP-hard。实践中贪婪已足够好——每轮填死一个 rank,至多 R-1 轮收敛。

                                                                                                                              2. 为什么只从一个 remote home group 复制? 简化 planning kernel 的实现:每个 rank 的冗余专家全部来自同一个远程 rank,减少了跨 rank 通信的复杂度。

                                                                                                                              3. 为什么 B = E/R(训练)/ B = 3-4(推理)? 训练必须精确匹配(否则梯度 reduce 会错),推理可以容忍少量跨 rank 读取。

                                                                                                                              2.4 负载均衡的数学保证

                                                                                                                              附录 E 的定理给出冗余容量界:

                                                                                                                                M(I) ≤ E/R  恒成立


                                                                                                                                其中 M(I) = max_r redundant_experts(r)
                                                                                                                                即任何 rank 的冗余专家副本数不超过 E/R。

                                                                                                                                构造性证明(Model-Viz/src/parallel/moonep.py:110-190 的 CPU 实现):

                                                                                                                                1. 初始化:每 rank 只持有 home 专家的 token

                                                                                                                                2. 主循环:找欠载 rank u 和过载 rank o,从 o 搬 need = target - load(u) 个 token 到 u

                                                                                                                                3. 终止:每轮填死一个 rank,至多 R-1 轮

                                                                                                                                2.5 拷贝权重

                                                                                                                                我们的问题是:在MoonEP真实场景下,拷贝权重不耗费时间嘛?

                                                                                                                                拷贝权重当然耗时而且是 ms 量级的真实开销,作者也把它算进了 benchmark。——MoonEP 的做法不是"不耗时",而是三件事:摊薄、隐藏、并且承认它。

                                                                                                                                README :25 自己有说明:

                                                                                                                                 

                                                                                                                                The comparison counts MoonEP's extra kernels: MoonEP adds planning and weight-prefetch kernels that DeepEP does not need, and they are already stacked in the bars above. Even with the whole critical path included, total dispatch time is on par with DeepEP v2's dispatch alone and pulls ahead under imbalance.

                                                                                                                                ”

                                                                                                                                也就是说:开销真实存在,作者没有藏它,benchmark 柱状图里 planning 与 prefetch 两个额外 kernel 是叠进去的。结论是"算上这笔开销后仍然不亏、且在不均衡时净赚"。这跟"不耗时"是两回事。

                                                                                                                                comm_vs_deepep
                                                                                                                                comm_vs_deepep

                                                                                                                                MoonEP 让它变得可接受靠三件事:

                                                                                                                                • ① 预取 slot 的物理内存跨层共享,显存代价是 B 份权重总计而非每层(README:54);

                                                                                                                                • ② 拷贝跑在高优先级独立 comm stream 上、只用 2 个 warp 做纯 TMA 传输,藏进主流计算的影子里,反向还能跳过重复预取(api.py:864-879, 840-843);

                                                                                                                                • ③ 训练期 B = E/R 由定理保证拷贝量有紧上界、不随路由倾斜恶化,推理期可降到 3-4 并让溢出专家走对称内存直读(README:56-59)。

                                                                                                                                省下的零拷贝 epilogue、hot-rank 等待、per-layer host 同步和显存碎片,加起来超过这笔支出——这是一笔用有界带宽换无界抖动的交易,不是一笔免费的午餐。

                                                                                                                                下面拆开讲为什么这笔账划得来。

                                                                                                                                2.5.1 成本有多大?先把数量级算清楚

                                                                                                                                按 README :76-77 的默认配置(H20, EP=8):

                                                                                                                                  S=4096, H=7168, K=8, E=256, R=8  →  B = E/R = 32

                                                                                                                                  单个专家的三个投影(gate/up/down)各 [H, H'] bf16。K2 类模型 H'≈2048:

                                                                                                                                    单专家单投影 = 7168 × 2048 × 2 B ≈ 29.4 MB
                                                                                                                                    单专家三投影 ≈ 88 MB
                                                                                                                                    B=32 个 slot 全填  ≈ 2.8 GB

                                                                                                                                    NVLink(H20 约 900 GB/s 双向、单向 ~450 GB/s)搬 2.8 GB ≈ 6 ms 量级。如果搬运多个专家,这显然不是可以忽略的数字——如果它在关键路径上,这个方案就无意义了。

                                                                                                                                    所以关键全在后面三招。

                                                                                                                                    2.5.2 第一招:物理内存池跨层共享 —— 把成本从"每层"摊成"每步"

                                                                                                                                    这是最容易被忽略的一条。README :54:

                                                                                                                                     

                                                                                                                                    Rows [E, E+B): local prefetch slots, filled by buffer.prefetch_weight; ... Their physical memory comes from a process-global pool shared by all layers, so the extra cost is B expert weights per projection in total, not per layer.

                                                                                                                                    ”

                                                                                                                                    显存成本是 B 份权重总计,不是每层 B 份。60 层模型不会变成 60×2.8 GB。

                                                                                                                                    但请注意区分:显存是跨层共享的,拷贝动作仍然每层都要做(每层路由不同、experts_to_copy 不同)。所以这一招解决的是"显存爆炸",不是"带宽开销"。带宽靠下面两招。

                                                                                                                                    2.5.3 第二招:独立 comm stream 异步 —— 把拷贝藏进计算的影子里

                                                                                                                                    这是真正让开销"消失"的机制。api.py:816-879prefetch_weight:

                                                                                                                                      if not async_finish:                                  # :855  同步模式(会阻塞)
                                                                                                                                          self._run_prefetch_weight_on_current_stream(...)
                                                                                                                                          return None


                                                                                                                                      main_stream = torch.cuda.current_stream()
                                                                                                                                      comm = self._comm_stream                              # :864  独立通信流
                                                                                                                                      self._record_streams((plan.experts_to_copy, *weight_prefetch_args), comm)  # :867
                                                                                                                                      input_ready = main_stream.record_event()              # :868
                                                                                                                                      comm.wait_event(input_ready)                          # :869  只等输入就绪


                                                                                                                                      with torch.cuda.stream(comm):                         # :871  ★在 comm stream 上跑
                                                                                                                                          self._run_prefetch_weight_on_current_stream(...)
                                                                                                                                          done = comm.record_event()                        # :877
                                                                                                                                      return done                                           # :879  返回 event,不阻塞

                                                                                                                                      而这个 comm stream 被刻意设成高优先级(api.py:450, 470-471):

                                                                                                                                       

                                                                                                                                      comm_stream_priority: priority of the async comm stream; the default **-1** gives it **higher priority than the main stream**.
                                                                                                                                      ”

                                                                                                                                      调用顺序(README :86-102)是精心排的:

                                                                                                                                        buffer.dispatch(...)        → 返回 plan(含 experts_to_copy)
                                                                                                                                        buffer.prefetch_weight(...) → 立刻在 comm stream 上启动权重搬运
                                                                                                                                                ┊                      (此时主流还在跑 attention / 上一层 FFN / dispatch 尾部)
                                                                                                                                                ┊  ← 权重拷贝在这段影子里完成
                                                                                                                                        group GEMM 需要权重时才等 event

                                                                                                                                        关键洞察:权重拷贝与 token dispatch 走不同硬件路径。token dispatch 是 NVLink 上的小消息散射(延迟敏感),权重 prefetch 是大块连续 TMA 传输(带宽敏感)。两者叠加时,大块传输能把 NVLink 上 dispatch 留下的带宽空隙填满,而不是简单相加。

                                                                                                                                        prefetch.py 的 kernel 实现也是为"尽量不占 SM"设计的:只用 2 个 warp(PRODUCER_WARP / CONSUMER_WARP,:216, :239),全程 TMA 异步拷贝(cp_async_bulk),SM 几乎只做地址计算。:272-275 那段早释放注释解释了为什么不滞后 stages-1 组——就是为了把单 SM 带宽榨到 tile_bytes/remote_latency 以上。

                                                                                                                                        api.py:840-843 还有一处省钱:

                                                                                                                                         

                                                                                                                                        Kept separate from dispatch so the plan-reuse path (combine bwd) can skip re-prefetching.

                                                                                                                                        ”

                                                                                                                                        combine 的 backward 复用已存的 plan(README :144:"planning is skipped and no prefetch is needed")——反向传播不重复拷权重。所以一次前反向只拷一次,不是两次。

                                                                                                                                        2.5.4 第三招:训练强制 B = E/R —— 用定理保证"拷贝量有上界"

                                                                                                                                        README :56-59 这段是整个设计的收口:

                                                                                                                                         

                                                                                                                                        Training: must use B = E/R — the planner duplicates experts from at most one remote home group per rank (≤ E/R experts), so every expert the group GEMM touches is local.

                                                                                                                                        Inference (prefetch only, no gradients): B < E/R is allowed, B = 3–4 is recommended. If a rank ever needs more distinct remote experts than B, the group GEMM reads the overflow weights straight from the home rank through the symmetric mapping — slightly slower, with no impact on correctness.

                                                                                                                                        ”

                                                                                                                                        两个信息量极大的点:

                                                                                                                                        ① 训练期 B = E/R 的理由正是那条定理。 "duplicates experts from at most one remote home group per rank" —— 这跟本项目 moonep.py:26-32 docstring 写的证明完全同源:

                                                                                                                                         

                                                                                                                                        因为每个 rank 至多被填一次,它收来的全部远端 token 来自同一个其他 rank,那个 rank 只 home E/R 个专家 —— 于是每 rank 冗余副本 ≤ E/R。

                                                                                                                                        ”

                                                                                                                                        所以 B = E/R 不是拍脑袋的经验值,而是理论紧界。拷贝量因此有硬上界,不会随路由倾斜恶化——这正是 README :32 说的 "iteration time stays flat at every imbalance level"。

                                                                                                                                        ② 推理期 B 可以远小于界(3-4),代价是"溢出走 symmetric memory 直读"。 这是个漂亮的降级路径:拷不下的专家,group GEMM 直接通过对称内存映射读远端权重(memory semantics,靠 cu_seqlens 寻址),"slightly slower, with no impact on correctness"。推理没有梯度、B 可以砍到 1/8,拷贝成本随之暴跌。

                                                                                                                                        2.5.5 账最终怎么算平的?

                                                                                                                                        MoonEP 花的:planning kernel + weight prefetch(有界、异步、跨层摊薄) MoonEP 省的(README :23-24, :31-32):

                                                                                                                                        1. 零拷贝省掉的 epilogue:token 直接写到远端 rank 上的最终专家分组位置,"no permute in, no permute out",消掉了 "comm-buffer → user-buffer copy that dominates the epilogue"。这笔省下的量本身就很大。

                                                                                                                                        2. 不再被最热 rank 拖累:DeepEP 的延迟由 hottest rank 决定,maxvio 涨则稳定恶化;MoonEP 因为每 rank 恰好 S×K,comm 时间"almost flat"。

                                                                                                                                        3. 消掉 per-layer host 同步:静态 shape 让 grouped GEMM 形状 launch 前已知(:9)。这一条省的是流水线停顿,往往比带宽更值钱。

                                                                                                                                        4. 不再 OOM:DeepEP 的动态激活 shape 碎片化显存,"training OOMs at high imbalance";MoonEP 全静态,"never OOMs"。

                                                                                                                                        净结果(:25):总 dispatch 时间与 DeepEP v2 的 dispatch 单独持平,不均衡下反超;combine 在所有档位都明显更快。


                                                                                                                                        0x03 子知识点拆解

                                                                                                                                        3.1 子知识点树状结构

                                                                                                                                          MoonEP 源码级分析
                                                                                                                                          ├── 4.0 共享抽象与设计动机
                                                                                                                                          ├── 4.1 Buffer API 与 NVL 共享内存管理
                                                                                                                                          │   ├── 4.1.1 VMM 对称内存分配(buffer.py)
                                                                                                                                          │   ├── 4.1.2 Multicast 视图(buffer.py)
                                                                                                                                          │   ├── 4.1.3 Context 创建与缓冲区布局(api.py)
                                                                                                                                          │   └── 4.1.4 Buffer 类 API(api.py)
                                                                                                                                          ├── 4.2 Planning Kernel(4-phase 贪婪规划)
                                                                                                                                          │   ├── 4.2.1 Phase A: 排序与计数
                                                                                                                                          │   ├── 4.2.2 Phase B: 贪婪冗余规划
                                                                                                                                          │   ├── 4.2.3 Phase C: 分配目标位置
                                                                                                                                          │   ├── 4.2.4 Phase D: 扫描输出结构
                                                                                                                                          │   └── 4.2.5 MoonEPCommPlan 数据结构
                                                                                                                                          ├── 4.3 Dispatch Kernel(warp-specialized 派发)
                                                                                                                                          │   ├── 4.3.1 G2S Producer(TMA 流水线)
                                                                                                                                          │   ├── 4.3.2 S2G Consumer(payload 写入 + weight scatter)
                                                                                                                                          │   ├── 4.3.3 Zero Warp(段填充清零)
                                                                                                                                          │   └── 4.3.4 Dedup Builder Warps(dedup 结构构建)
                                                                                                                                          ├── 4.4 Dispatch Epilogue(in-place 重复展开)
                                                                                                                                          ├── 4.5 Combine Kernel(3-stage fp32 累加)
                                                                                                                                          ├── 4.6 Combine Prologue(in-place 重复累加)
                                                                                                                                          ├── 4.7 Prefetch Kernel(2D TMA 权重预取)
                                                                                                                                          ├── 4.8 Grad Reduce Kernel(fp32 梯度归约)
                                                                                                                                          └── 4.9 跨 rank 同步基础设施

                                                                                                                                          3.2 官方代码位置标注

                                                                                                                                          子知识点

                                                                                                                                          源码文件

                                                                                                                                          关键行号

                                                                                                                                          Buffer API

                                                                                                                                          moonep/api.pyBuffer.__init__:439

                                                                                                                                          , dispatch:685, combine:881

                                                                                                                                          VMM 分配

                                                                                                                                          moonep/buffer.pycreate_nvl_dist_tensor:224

                                                                                                                                          , create_nvl_single_owner_tensor:345

                                                                                                                                          Planning Kernel

                                                                                                                                          moonep/planning.pyPlanningKernel.__call__:365

                                                                                                                                          , kernel:519

                                                                                                                                          MoonEPCommPlan

                                                                                                                                          moonep/planning.pyMoonEPCommPlan:31

                                                                                                                                          Dispatch Kernel

                                                                                                                                          moonep/dispatch.pyDispatchKernel.kernel:268

                                                                                                                                          , launch_dispatch:839

                                                                                                                                          Dispatch Epilogue

                                                                                                                                          moonep/dispatch_epilogue.pyDispatchEpilogueKernel.kernel:168

                                                                                                                                          Combine Kernel

                                                                                                                                          moonep/combine.pyCombineKernel.kernel:210

                                                                                                                                          , launch_combine:565

                                                                                                                                          Combine Prologue

                                                                                                                                          moonep/combine_prologue.pyCombinePrologueKernel.kernel:197

                                                                                                                                          Prefetch Kernel

                                                                                                                                          moonep/prefetch.pyPrefetchKernel.kernel:137

                                                                                                                                          , launch_prefetch:317

                                                                                                                                          Grad Reduce

                                                                                                                                          moonep/grad_reduce.pyGradReduceKernel.kernel:150

                                                                                                                                          , launch_grad_reduce:437

                                                                                                                                          PTX 工具

                                                                                                                                          moonep/_common.pygrid_sync:249

                                                                                                                                          , cross_rank_barrier:274, cp_async_bulk_g2s:414

                                                                                                                                          常量

                                                                                                                                          moonep/constants.pyRANK_BITS=7

                                                                                                                                          , KIDX_BITS=7, DEDUP_BUILDER_WARPS=4

                                                                                                                                          跨 rank 同步

                                                                                                                                          moonep/inter_rank_sync.pylaunch_inter_rank_sync:119

                                                                                                                                          CPU 教学实现

                                                                                                                                          Model-Viz/src/parallel/moonep.pyplan_redundant_experts:110

                                                                                                                                          , MoonEP:207

                                                                                                                                          完整执行流程图如下:

                                                                                                                                            用户调用:
                                                                                                                                              buffer.dispatch(hidden_sh, route_weights_sk, topk_experts_sk, tokens_per_expert)
                                                                                                                                                │
                                                                                                                                                ├── inter_rank_sync()        ← 跨 rank 对齐
                                                                                                                                                ├── planning()               ← 4-phase GPU planning
                                                                                                                                                │   ├── Phase A: 排序 + 贪婪规划
                                                                                                                                                │   ├── Phase B: 分配目标位置
                                                                                                                                                │   ├── Phase C: dst canonicalization
                                                                                                                                                │   └── Phase D: 扫描输出结构
                                                                                                                                                ├── dispatch()               ← warp-specialized 派发
                                                                                                                                                │   ├── Warp 0: G2S TMA
                                                                                                                                                │   ├── Warp 1: S2G + weight scatter
                                                                                                                                                │   ├── Warp 2: zero-fill
                                                                                                                                                │   └── Warp 3+: dedup builder (3-pass)
                                                                                                                                                ├── dispatch_epilogue()      ← in-place dedup 展开
                                                                                                                                                └── 返回 (hidden_nvsh, route_weights_nvs, cu_seqlens, plan)


                                                                                                                                              buffer.prefetch_weight(plan, full_gate_weight, full_up_weight, full_down_weight)
                                                                                                                                                └── prefetch() × 3          ← 2D TMA 权重预取 (gate/up/down)


                                                                                                                                              # Expert GEMM 在外部执行,输入/输出都是 NVL buffer view


                                                                                                                                              buffer.combine(plan, hidden_nvsh, route_weights_nvs)
                                                                                                                                                ├── inter_rank_sync()
                                                                                                                                                ├── combine_prologue()      ← in-place fp32 dedup 累加
                                                                                                                                                ├── combine()               ← 3-stage fp32 ACC + weight gather
                                                                                                                                                └── 返回 (hidden_sh, route_weights_sk)


                                                                                                                                              # Backward:
                                                                                                                                              buffer.dispatch(grad_output_sh, plan=plan)   ← re-dispatch (复用 plan)
                                                                                                                                              buffer.combine(plan, grad_hidden_nvsh)       ← combine bwd
                                                                                                                                              buffer.reduce_grad(plan, ...)                ← fp32 梯度归约


                                                                                                                                            3.3 本项目复现

                                                                                                                                            参考代码:MoonEP-master/moonep/ 全部 12 个模块

                                                                                                                                            教学实现:parallel/moonep.py(288 行 CPU 模拟)

                                                                                                                                            MoonEP 的核心优化(VMM、NVLink multicast、cp.async.bulk、PDL)都是 GPU 专用硬件特性,无法在 CPU 上复现。教学实现覆盖了规划算法但不覆盖内核级优化。

                                                                                                                                            原因:硬件限制。

                                                                                                                                            0x04 子知识点深度分析

                                                                                                                                            4.0 共享抽象与设计动机

                                                                                                                                            MoonEP 的所有 kernel 共享一套核心抽象,理解它们是读懂整个代码库的前提。

                                                                                                                                            4.0.1 符号与 shape 约定

                                                                                                                                              符号          含义                              典型值
                                                                                                                                              ─────────────────────────────────────────────────────────
                                                                                                                                              S             每 rank 输入 token 数              4096
                                                                                                                                              K             路由 top-k                        8
                                                                                                                                              E             EP 组内总路由专家数                 256
                                                                                                                                              R             EP rank 数                        8
                                                                                                                                              epn           每 rank 本地专家数 = E/R           32
                                                                                                                                              B             权重预取槽数(训练=E/R,推理=3-4)    32
                                                                                                                                              N = S*K       总 token-专家指派数                32768
                                                                                                                                              NvS           派发后每 rank token 槽位数         N + padding
                                                                                                                                              H             隐藏维度                          7168
                                                                                                                                              H'            专家 FFN 中间维度                  2048


                                                                                                                                              4.0.2 NVLink 共享内存布局

                                                                                                                                              所有 rank 通过 NVLink 共享两块关键缓冲区:

                                                                                                                                              hidden_buf[R * NvS_padded, H] bf16 — token 数据:

                                                                                                                                                ┌─────────────────────────────────────────────────────┐
                                                                                                                                                │ rank 0 的 NvS_padded 行  │ rank 1 的 ...  │ ...      │
                                                                                                                                                │ [0, NvS) 有效, [NvS, NvS_padded) padding   │         │
                                                                                                                                                └─────────────────────────────────────────────────────┘

                                                                                                                                                meta_buf[R * meta_chunk_padded] int32 — 元数据(多用途复用):

                                                                                                                                                  偏移区域                    用途
                                                                                                                                                  [0, NvS)                   weights (fp32, alias 为 int32)
                                                                                                                                                  [NvS, NvS + R*E)           tpe gather (tokens_per_expert 跨 rank 收集)
                                                                                                                                                  [NvS + R*E, ...)           planning 内部 scratch/staging
                                                                                                                                                  [..., +N4)                 topk0 offload scratch
                                                                                                                                                  [..., +N4)                 ORDER, c1 order consumed by c2/passB
                                                                                                                                                  [..., +N4)                 ORDER0, rank1 rank0-c1 scratch
                                                                                                                                                  [..., +3)                  cross-rank phase barrier
                                                                                                                                                  [..., +NvS)                src_info scratch (planning 发布, dispatch builder 消费)

                                                                                                                                                  这种布局的关键设计:所有跨 rank 数据交换都通过 NVLink 共享内存完成,无需显式通信原语。

                                                                                                                                                  4.0.3 MoonEPCommPlan 数据结构

                                                                                                                                                  官方代码中,planning.py:31-88 定义了 planning kernel 的输出,贯穿整个通信流程:

                                                                                                                                                    @dataclass(frozen=True, slots=True)
                                                                                                                                                    class MoonEPCommPlan:
                                                                                                                                                        dst: torch.Tensor              # [N] int32 — 每个 token 的目标位置
                                                                                                                                                                                       # 非负: dest_rank * NvS + local_offset (拷贝 payload)
                                                                                                                                                                                       # 负值: -raw_dst - 1 (duplicate, 只散播 weight)
                                                                                                                                                        experts_to_copy: torch.Tensor  # [R, B] int32 — 每 rank 要预取的远程专家 id
                                                                                                                                                        zero_fill_ranges: torch.Tensor # [E+B, 2] int32 — 每个 VM group 行的 padding 范围
                                                                                                                                                        remote_stats: torch.Tensor     # [2] int32 — 远程专家统计
                                                                                                                                                        dup_groups: torch.Tensor       # [NvS, 3] int32 — (primary_loff, dup_start, dup_n)
                                                                                                                                                        dup_loffs: torch.Tensor        # [NvS] int32 — duplicate slot 偏移
                                                                                                                                                        dup_counts: torch.Tensor       # [2] int32 — (n_groups, n_dup_loffs)
                                                                                                                                                        N, R, E, B, NvS, K: int        # 形状常量

                                                                                                                                                    dst 的负编码是 MoonEP 的核心技巧:同一个 token 被路由到同一 rank 的多个专家时,只有第一个 k 路径拷贝 payload(dst >= 0),后续路径标记为 duplicate(dst < 0),只散播 weight。重复行通过 dispatch epilogue 在 NVL shard 上 in-place 展开。


                                                                                                                                                    4.1 Buffer API 与 NVL 共享内存管理

                                                                                                                                                    4.1.1 要解决的问题

                                                                                                                                                    EP 通信的核心挑战是跨 rank 数据交换。传统做法用 all_to_all 通信原语,但:

                                                                                                                                                    • 每次 all_to_all 需要 host-device 同步

                                                                                                                                                    • 数据在发送端和接收端各存一份,浪费显存

                                                                                                                                                    • 无法做到 zero-copy

                                                                                                                                                    MoonEP 的解决方案:用 NVLink 共享内存(VMM)让所有 rank 直接读写同一块物理内存。

                                                                                                                                                    4.1.2 技术难点

                                                                                                                                                    1. VMM 对称内存分配:需要 CUDA driver 级别的 cuMemCreate + cuMemAddressReserve + cuMemMap,不是 PyTorch 的 torch.cuda.tensor 能搞定的

                                                                                                                                                    2. 跨 rank 内存共享:每个 rank 的 GPU 都能看到同一块物理内存,但需要通过 fabric handle(跨节点)或 POSIX fd(节点内)交换映射信息

                                                                                                                                                    3. Multicast 支持:NVSwitch 的 SHARP 硬件可以让一次写操作同时复制到所有 rank 的本地 chunk

                                                                                                                                                    4.1.3 架构与类依赖关系图

                                                                                                                                                      buffer.py
                                                                                                                                                      ├── nvl_dist_alloc()           ← pybind11 → cuMemCreate (CUDA driver)
                                                                                                                                                      ├── nvl_dist_map()             ← pybind11 → cuMemMap (CUDA driver)
                                                                                                                                                      ├── nvl_fabric_supported()     ← 检查 NVLink fabric 支持
                                                                                                                                                      ├── nvl_multicast_create()     ← cuMulticastCreate (NVSwitch SHARP)
                                                                                                                                                      ├── nvl_multicast_bind_map()   ← 绑定物理内存到 multicast 对象
                                                                                                                                                      ├── create_nvl_dist_tensor()   → 所有 rank 可读写的 NVL 张量
                                                                                                                                                      ├── create_nvl_dist_multicast_tensor() → NVL 张量 + multicast 视图
                                                                                                                                                      └── create_nvl_single_owner_tensor()   → 单 owner 的 NVL 张量


                                                                                                                                                      api.py
                                                                                                                                                      ├── _create_context()          → 分配 hidden_buf + meta_buf + 本地 scratch
                                                                                                                                                      └── Buffer 类                  → 顶层 API,封装 dispatch/combine/prefetch/reduce_grad


                                                                                                                                                      4.1.4 数据流

                                                                                                                                                        _create_context() 被 Buffer.__init__ 调用:
                                                                                                                                                          1. 计算 NvS = S*K + (token_padding-1)*2*E/R  (逻辑槽位)
                                                                                                                                                          2. NvS_padded = pad_dim0_for_alignment([NvS, H], bf16)  (VMM 对齐)
                                                                                                                                                          3. hidden_buf = create_nvl_dist_tensor([NvS_padded, H], bf16)  ← NVL 共享
                                                                                                                                                          4. meta_buf, meta_mc = create_nvl_dist_multicast_tensor([meta_chunk_padded], int32)  ← NVL + multicast
                                                                                                                                                          5. 分配本地 scratch: alloc, group_tokens, z, local_hist, grid_sync_bar, primary_packed, kmask, kidx_to_loff, builder_bar


                                                                                                                                                        4.1.5 关键类/函数职责表

                                                                                                                                                        函数/类

                                                                                                                                                        文件:行号

                                                                                                                                                        输入

                                                                                                                                                        输出

                                                                                                                                                        职责

                                                                                                                                                        nvl_dist_alloc

                                                                                                                                                        buffer.py (pybind11)

                                                                                                                                                        shape, dtype, use_fabric

                                                                                                                                                        keepalive, shareable, owned_handle

                                                                                                                                                        分配 VMM 物理内存

                                                                                                                                                        nvl_dist_map

                                                                                                                                                        buffer.py (pybind11)

                                                                                                                                                        chunk_shape, dtype, shareables, local_rank, world_size, use_fabric

                                                                                                                                                        full_tensor

                                                                                                                                                        创建跨 rank 映射

                                                                                                                                                        create_nvl_dist_tensor

                                                                                                                                                        buffer.py:224

                                                                                                                                                        chunk_shape, dtype, local_rank, world_size, group

                                                                                                                                                        tensor

                                                                                                                                                        所有 rank 可读写的 NVL 张量

                                                                                                                                                        create_nvl_dist_multicast_tensor

                                                                                                                                                        buffer.py:251

                                                                                                                                                        chunk_shape, dtype, local_rank, world_size, group

                                                                                                                                                        (full_tensor, mc_view)

                                                                                                                                                        NVL 张量 + multicast 视图

                                                                                                                                                        create_nvl_single_owner_tensor

                                                                                                                                                        buffer.py:345

                                                                                                                                                        shape, dtype, owner_rank, local_rank, group

                                                                                                                                                        tensor

                                                                                                                                                        单 owner 的 NVL 张量

                                                                                                                                                        _create_context

                                                                                                                                                        api.py:213

                                                                                                                                                        S, H, K, E, num_ep_ranks, ...

                                                                                                                                                        ctx dict

                                                                                                                                                        预分配所有缓冲区

                                                                                                                                                        Buffer.__init__

                                                                                                                                                        api.py:439

                                                                                                                                                        S, H, K, E, num_ep_ranks, ...

                                                                                                                                                        Buffer

                                                                                                                                                        创建 context + comm stream

                                                                                                                                                        Buffer.dispatch

                                                                                                                                                        api.py:685

                                                                                                                                                        hidden_sh, route_weights_sk, topk_experts_sk, tokens_per_expert

                                                                                                                                                        (hidden_nvsh, route_weights_nvs, cu_seqlens, plan)

                                                                                                                                                        dispatch 前向

                                                                                                                                                        Buffer.combine

                                                                                                                                                        api.py:881

                                                                                                                                                        plan, hidden_nvsh, route_weights_nvs

                                                                                                                                                        (hidden_sh, route_weights_sk, event)

                                                                                                                                                        combine 前向

                                                                                                                                                        4.1.6 实现机制详解

                                                                                                                                                        VMM 分配流程(buffer.py:224-248):

                                                                                                                                                          def create_nvl_dist_tensor(chunk_shape, dtype, local_rank, world_size, group):
                                                                                                                                                              use_fabric = _use_fabric_for_group(group)           # 1. 决定用 fabric 还是 fd
                                                                                                                                                              keepalive, shareable, owned_handle = nvl_dist_alloc(
                                                                                                                                                                  shape=chunk_shape, dtype=dtype, use_fabric=use_fabric)  # 2. cuMemCreate
                                                                                                                                                              try:
                                                                                                                                                                  return _map_nvl_dist_tensor(                    # 3. cuMemMap
                                                                                                                                                                      chunk_shape, dtype, shareable, keepalive,
                                                                                                                                                                      local_rank, world_size, group, use_fabric,
                                                                                                                                                                  )
                                                                                                                                                              finally:
                                                                                                                                                                  nvl_release_mem_handle(owned_handle)             # 4. 释放 handle(映射已建立)


                                                                                                                                                          Fabric vs FD 的选择(buffer.py:37-63):

                                                                                                                                                          • 跨节点(world_size > 1):必须用 fabric handle(NVLink fabric 支持)

                                                                                                                                                          • 节点内(world_size == 1):可以用 POSIX fd(更简单)

                                                                                                                                                          • 环境变量 MOONEP_MEM_HANDLE_TYPE 可覆盖:auto/fabric/fd

                                                                                                                                                          4.1.7 对比基线

                                                                                                                                                          维度

                                                                                                                                                          标准 EP (all_to_all)

                                                                                                                                                          MoonEP (NVL VMM)

                                                                                                                                                          数据拷贝次数

                                                                                                                                                          2(发送端打包 + 接收端解包)

                                                                                                                                                          0(直接读写共享内存)

                                                                                                                                                          Host 同步

                                                                                                                                                          每次 all_to_all 需要

                                                                                                                                                          无需

                                                                                                                                                          显存占用

                                                                                                                                                          2× buffer(发送 + 接收)

                                                                                                                                                          1× buffer(共享)

                                                                                                                                                          通信延迟

                                                                                                                                                          受 PCIe/NVLink 带宽限制

                                                                                                                                                          NVLink 直连,延迟更低

                                                                                                                                                          4.1.8 反方辩手

                                                                                                                                                          a) 反对最强理由:VMM 对称内存需要特定硬件支持(NVLink + NVSwitch),不是所有 GPU 都能用。

                                                                                                                                                          b) 最可能错的假设:假设 NVLink 带宽足够覆盖所有 EP 场景。当 EP 组很大(R=64+)时,跨节点 NVLink fabric 的延迟可能成为瓶颈。

                                                                                                                                                          c) 胜出条件:节点内 EP(R ≤ 8),NVLink 带宽充足;失败条件:跨节点 EP,或 NVLink 带宽不足。

                                                                                                                                                          d) 更稳健的做法:DeepEP v2 的 all_to_all 方案,虽然性能差一点,但兼容所有硬件。

                                                                                                                                                          e) 受伤害的利益相关方:使用非 NVIDIA GPU 的训练方(如 AMD MI300X)。

                                                                                                                                                          4.1.9 计算复杂度分析

                                                                                                                                                          • FLOPs:NVL 分配本身无计算,纯内存操作

                                                                                                                                                          • 内存:hidden_buf = R × NvS_padded × H × 2 bytes (bf16);meta_buf = R × meta_chunk_padded × 4 bytes (int32)

                                                                                                                                                          • 参数数量:无新增可训练参数(通信库,不是模型组件)

                                                                                                                                                          4.1.10 常见疑问 Q&A

                                                                                                                                                          Q: 为什么 meta_buf 用 int32 而不是 fp32?A: meta_buf 是多用途复用的——权重区域逻辑上是 fp32,但通过 view(torch.int32) 共享同一块内存。int32 的位操作(atomicAdd、atomicOr)在 planning/dispatch builder 中更方便。

                                                                                                                                                          Q: zero_copy=True 为什么不能跨通信调用保存 tensor?A: 因为返回的是 NVL buffer 的 view,下一次 dispatch/combine 会覆盖同一块内存。autograd 不能把 view 存到 SavedTensor 里——那会导致 backward 时读到被覆盖的数据。


                                                                                                                                                          4.2 Planning Kernel(4-phase 贪婪规划)

                                                                                                                                                          4.2.1 要解决的问题

                                                                                                                                                          Planning kernel 是 MoonEP 的"大脑"——它决定每个 token 应该被发到哪个 rank 的哪个专家槽位。核心挑战:

                                                                                                                                                          1. 路由不均:不同专家收到的 token 数差异巨大

                                                                                                                                                          2. 完美均衡:每个 rank 必须恰好收到 S×K 个 token

                                                                                                                                                          3. 冗余规划:需要决定哪些远程专家要被复制到本地

                                                                                                                                                          4. 在线计算:规划必须在 GPU 上完成,不能回传 host

                                                                                                                                                          4.2.2 技术难点

                                                                                                                                                          • 4 个 phase 必须在一个 cooperative grid launch 中完成(不能拆成多个 kernel,因为中间结果在 SMEM/GMEM 之间传递)

                                                                                                                                                          • Phase B 的贪婪算法需要warp 级别的 reduction(找最大/最小值)

                                                                                                                                                          • Phase C 的二分搜索需要 O(log R) 步骤,每步读 global memory

                                                                                                                                                          • 输出结构(dst, cu_seqlens, experts_to_copy, zero_fill_ranges)的大小与 E, R, B 相关,必须在编译时确定

                                                                                                                                                          4.2.3 架构与执行流

                                                                                                                                                            PlanningKernel.__call__ (planning.py:365)
                                                                                                                                                              └── kernel (planning.py:519)
                                                                                                                                                                   ├── Phase A (planning.py:601-702):
                                                                                                                                                                   │   ├── Step 1: tpe gather → rank0 chunk
                                                                                                                                                                   │   ├── Step 2: cross_rank_barrier
                                                                                                                                                                   │   ├── Step 3: tpe_cumsum 计算
                                                                                                                                                                   │   ├── Step 4: 贪婪冗余规划 (balance loop)
                                                                                                                                                                   │   ├── Step 5: alloc_tensor 计算
                                                                                                                                                                   │   └── Step 6: cu_seqlens + zero_fill_ranges + experts_to_copy
                                                                                                                                                                   │
                                                                                                                                                                   ├── Phase B (planning.py:961-977):
                                                                                                                                                                   │   └── C2: 根据 ORDER 将 token 分配到目标 rank/offset
                                                                                                                                                                   │
                                                                                                                                                                   ├── Phase C (planning.py:979-1077):
                                                                                                                                                                   │   └── 跨 rank barrier + dst canonicalization (负编码 duplicate)
                                                                                                                                                                   │
                                                                                                                                                                   └── Phase D (planning.py:1003-1131):
                                                                                                                                                                       └── 扫描输出结构写入 cu_seqlens, zero_fill_ranges, experts_to_copy

                                                                                                                                                            4.2.4 Phase A 详解:排序与冗余规划

                                                                                                                                                            Phase A 是最复杂的部分,包含 6 个步骤:

                                                                                                                                                            Step 1-2: tpe gather + cross-rank barrier(planning.py:602-609)

                                                                                                                                                              # 每个 rank 把自己的 tpe (tokens_per_expert) 写入 meta_buf 的 rank 0 区域
                                                                                                                                                              copy_v4_remote(meta, TPE_OFF + rank * E, tpe, E, pid, tid, num_threads, num_sms)
                                                                                                                                                              # rank 0 还收集所有 rank 的 topk 原始数据
                                                                                                                                                              if rank == 0:
                                                                                                                                                                  copy_v4_remote(meta, ms + TOPK0_OFF, topk, N, pid, tid, num_threads, num_sms)
                                                                                                                                                              # 跨 rank 同步,确保所有 rank 的 tpe 都可见
                                                                                                                                                              cross_rank_barrier(meta, ms, BARRIER_OFF, rank, R, bar_p, num_sms, num_threads, tid)

                                                                                                                                                              Step 3: tpe_cumsum 计算(planning.py:625-670)

                                                                                                                                                              rank 0 计算跨 rank 的 token 数前缀和:

                                                                                                                                                                # 对每个 expert,计算 rank 间的累积和
                                                                                                                                                                # tpe_cumsum[r, e] = sum(tpe[0..r-1, e]) + tpe[r, e]
                                                                                                                                                                # 这告诉每个 rank:expert e 的第 global_rank 个 token 应该发到哪里

                                                                                                                                                                Step 4: 贪婪冗余规划(planning.py:671-702)

                                                                                                                                                                这是 MoonEP 的核心算法,在 GPU 上实现:

                                                                                                                                                                  # balance[j] = group_tokens[j] - CAP  (CAP = S*K)
                                                                                                                                                                  # 循环:
                                                                                                                                                                  #   surplus = max(balance) → 有盈余的 rank
                                                                                                                                                                  #   deficit = min(balance) → 有亏空的 rank
                                                                                                                                                                  #   move_tokens = -deficit → 从 surplus 搬 move_tokens 个 token 到 deficit
                                                                                                                                                                  #   z[surplus_rank, deficit_rank] = move_tokens
                                                                                                                                                                  # 终止条件:surplus <= 0 或 deficit >= 0


                                                                                                                                                                  warp 级别的 argmax/argmin 用 reg_scan_argmax_min_idx(planning.py:258-263)实现,纯寄存器操作,无需 shared memory。

                                                                                                                                                                  Step 5: alloc_tensor 计算(planning.py:703-798)

                                                                                                                                                                  对每个 owner rank,计算其他 rank 要从它这里拿多少 token:

                                                                                                                                                                    # alloc_tensor[rank, expert] = 该 rank 为 expert 计算的 token 数
                                                                                                                                                                    # alloc_cumsum[expert, rank] = alloc_tensor 的行前缀和(供 Phase C 二分搜索)


                                                                                                                                                                    Step 6: cu_seqlens + zero_fill_ranges(planning.py:799-954)

                                                                                                                                                                    对每个 dest_rank,计算 VM group 的 padded token 末偏移:

                                                                                                                                                                      # cu_seqlens[dest_rank, group_idx] = padded_end_offset
                                                                                                                                                                      # zero_fill_ranges[dest_rank, group_idx] = (pad_start, pad_count)
                                                                                                                                                                      # experts_to_copy[dest_rank, slot] = 要预取的远程专家 id


                                                                                                                                                                      4.2.5 Phase B: C2 分配目标位置

                                                                                                                                                                      Phase B(planning.py:961-1077)根据 ORDER(Phase A 产出的排序序列)将每个 token 分配到目标 rank 和 offset:

                                                                                                                                                                        # 对每个 token offv = ORDER[idx]:
                                                                                                                                                                        #   expert_idx = topk[offv]
                                                                                                                                                                        #   prev = tpe_cumsum[rank-1, expert_idx]  (本 rank 之前的累积)
                                                                                                                                                                        #   global_rank = prev + (idx - s_expoff[expert_idx])  (全局排名)
                                                                                                                                                                        #   二分搜索找到目标 rank: alloc_cumsum[expert_idx, mid] > global_rank
                                                                                                                                                                        #   lo = expert_off[lo, expert_idx]  (目标 offset)
                                                                                                                                                                        #   dst[offv] = lo * NvS + bo + (global_rank - pc)
                                                                                                                                                                        #   src_info[lo * ms + SRC_INFO_OFF + loff] = rank * NvS + offv  (发布源信息)


                                                                                                                                                                        4.2.6 Phase C: dst canonicalization

                                                                                                                                                                        Phase C(planning.py:1079-1113)处理 duplicate 检测:

                                                                                                                                                                          # 对每个 token 的 K 个路由路径,检测是否有重复目标 rank
                                                                                                                                                                          # seen_lo, seen_hi: 128-bit 位掩码
                                                                                                                                                                          # 如果 dst[k] 的目标 rank 已经在 seen 中,则标记为 duplicate:
                                                                                                                                                                          #   dst[base_idx + k] = -(dst_vals[k]) - 1
                                                                                                                                                                          # 否则标记为 primary:
                                                                                                                                                                          #   seen_lo |= (1 << d)


                                                                                                                                                                          这个位掩码技巧让 duplicate 检测完全在寄存器中完成,无需 shared memory。

                                                                                                                                                                          4.2.7 Phase D: 扫描输出结构

                                                                                                                                                                          Phase D(planning.py:1003-1131)将 planning 的结果从 meta_buf 拷贝到输出张量:

                                                                                                                                                                            # cu_seqlens[group_idx] = s_pd_cu_stage[local_group]
                                                                                                                                                                            # zero_fill[group_idx*2] = s_pd_zfr_stage[local_group*2]
                                                                                                                                                                            # experts_to_copy[etc_idx] = s_pd_etc_stage[local_idx]
                                                                                                                                                                            # remote_stats[i] = meta[PB + STATS_SUB + rank*2 + i]


                                                                                                                                                                            使用 cp.async.bulk G2S + S2G 的流水线,避免直接从 global memory 读取。

                                                                                                                                                                            4.2.8 数据流图

                                                                                                                                                                              输入:
                                                                                                                                                                                topk_experts_sk: [S, K] int32  →  topk_flat: [N] int32
                                                                                                                                                                                tokens_per_expert: [E] int32   →  tpe: [E] int32


                                                                                                                                                                              Phase A:
                                                                                                                                                                                tpe → meta_buf[TPE_OFF + rank*E]  (每个 rank 写自己的)
                                                                                                                                                                                cross_rank_barrier
                                                                                                                                                                                rank 0: tpe_cumsum[R, E], group_tokens[R], z[R,R]
                                                                                                                                                                                rank 0: alloc_tensor[R, E], alloc_cumsum[E, R]
                                                                                                                                                                                rank 0: cu_seqlens[R, E+B], zero_fill_ranges[R, E+B, 2]
                                                                                                                                                                                rank 0: experts_to_copy[R, B], remote_stats[R, 2]
                                                                                                                                                                                rank 0: multimem_st → meta_mc (multicast 到所有 rank)


                                                                                                                                                                              Phase B:
                                                                                                                                                                                ORDER[N] → dst[N] int32, src_info[NvS] int32


                                                                                                                                                                              Phase C:
                                                                                                                                                                                dst[N] canonicalized (负编码 duplicate)


                                                                                                                                                                              Phase D:
                                                                                                                                                                                meta_buf → cu_seqlens[E+B], zero_fill_ranges[E+B, 2], experts_to_copy[R, B]


                                                                                                                                                                              输出:
                                                                                                                                                                                dst[N]              → plan.dst
                                                                                                                                                                                cu_seqlens[E+B]     → 返回值
                                                                                                                                                                                experts_to_copy[R,B] → plan.experts_to_copy
                                                                                                                                                                                zero_fill_ranges[E+B,2] → plan.zero_fill_ranges
                                                                                                                                                                                dup_groups/dup_loffs/dup_counts → 由 dispatch builder 填充


                                                                                                                                                                              4.2.9 对比基线

                                                                                                                                                                              维度

                                                                                                                                                                              标准 EP

                                                                                                                                                                              MoonEP Planning

                                                                                                                                                                              规划位置

                                                                                                                                                                              CPU

                                                                                                                                                                              GPU (cooperative grid)

                                                                                                                                                                              规划延迟

                                                                                                                                                                              O(E log E) host

                                                                                                                                                                              O(E + R²) GPU warp-level

                                                                                                                                                                              中间结果

                                                                                                                                                                              需要 host-device 同步

                                                                                                                                                                              全部在 GPU 上完成

                                                                                                                                                                              负载均衡

                                                                                                                                                                              无保证

                                                                                                                                                                              完美均衡 (S*K 恒等)

                                                                                                                                                                              4.2.10 反方辩手

                                                                                                                                                                              a) 反对最强理由:planning kernel 的 4-phase 设计过于复杂,cooperative grid launch 的调试极其困难。 b) 最可能错的假设:假设 routing 分布不会极端到让 B = E/R 不够用。如果某个 rank 需要 > E/R 个不同的远程专家,多余的会直接从 home rank 通过 NVLink 读取(慢但正确)。 c) 胜出条件:E/R ≥ K(每 rank 至少有 K 个本地专家),routing 有一定随机性;失败条件:E/R < K 且 routing 极端集中。 d) 更稳健的做法:静态预分配 + all_to_all,牺牲一点性能但实现简单。 e) 受伤害的利益相关方:推理服务方(latency 敏感,planning 开销占比更高)。

                                                                                                                                                                              完成度:已实现并运行通过(moonep/planning.py)

                                                                                                                                                                              4.2.11 计算复杂度分析

                                                                                                                                                                              • FLOPs:Phase A 的 tpe_cumsum: O(E×R);贪婪规划: O(R²);Phase B 的 C2: O(N×log R);总: O(E×R + R² + N×log R)

                                                                                                                                                                              • 内存:SMEM: O(E + R² + NvS);GMEM: meta_buf 的 planning 区域

                                                                                                                                                                              • 参数敏感性:

                                                                                                                                                                                • num_sms:越大规划越快,但受 SM 数量限制

                                                                                                                                                                                • BLOCK_SIZE_P2 = 2048:warp 级别操作的粒度,过大降低并行度

                                                                                                                                                                                • token_padding = 128:padding 越大 NvS 越大,浪费显存但对齐更好


                                                                                                                                                                              4.3 Dispatch Kernel(warp-specialized 派发)

                                                                                                                                                                              4.3.1 要解决的问题

                                                                                                                                                                              Dispatch kernel 的任务是:根据 planning 产出的 dst 数组,把 [S, H] 的 token 数据直接写到 NVL 共享内存中对应 rank 的对应槽位——不需要 all_to_all,不需要显式 permute。

                                                                                                                                                                              核心挑战:

                                                                                                                                                                              1. 零拷贝:token 直接写到目标 rank 的最终位置,无需中间缓冲

                                                                                                                                                                              2. Per-row TMA:每行用 cp.async.bulk 做一次 128-bit 对齐的 TMA 拷贝

                                                                                                                                                                              3. Dedup 结构构建:在 dispatch 的同时,builder warps 需要扫描 src_info 构建 dup_groups/dup_loffs/dup_counts

                                                                                                                                                                              4. 段填充清零:padding 行需要被清零(expert GEMM 会读到这些行)

                                                                                                                                                                              4.3.2 Warp 分工

                                                                                                                                                                              dispatch.py:50-82 定义了 warp 布局:

                                                                                                                                                                                Warp 0 (PRODUCER):  G2S producer — 从 hidden_sh 读一行到 stage_smem
                                                                                                                                                                                Warp 1 (CONSUMER):  S2G consumer — 从 stage_smem 写到目标 rank 的 NVL 位置
                                                                                                                                                                                Warp 2 (ZERO):      zero warp — 清零 padding 行
                                                                                                                                                                                Warp 3+ (DEDUP_BUILDER): dedup builder warps — 构建 dedup 结构(仅 fresh planning)

                                                                                                                                                                                总线程数:96 + 32 * DEDUP_BUILDER_WARPS(dispatch.py:77)

                                                                                                                                                                                4.3.3 G2S Producer(TMA 流水线)

                                                                                                                                                                                dispatch.py:360-383:

                                                                                                                                                                                  # Warp 0 驱动 TMA G2S 流水线
                                                                                                                                                                                  # 每个 token 一行:cp_async_bulk_g2s(smem_row, gmem_row, H_BYTES, mbar)
                                                                                                                                                                                  # PipelineTmaAsync 管理多阶段流水线(stages = 2..16,取决于 H 和 smem budget)
                                                                                                                                                                                  for li in cutlass.range(n_tok, unroll=1):
                                                                                                                                                                                      load_pipe.producer_acquire(load_state)
                                                                                                                                                                                      if cute.arch.lane_idx() == 0:
                                                                                                                                                                                          cp_async_bulk_g2s(s_row_int, g_row_int, H_BYTES, mbar_int)
                                                                                                                                                                                      load_state.advance()

                                                                                                                                                                                  4.3.4 S2G Consumer(payload 写入 + weight scatter)

                                                                                                                                                                                  dispatch.py:387-448:

                                                                                                                                                                                    # Warp 1 从 stage_smem 读取,根据 dst 决定写到哪里
                                                                                                                                                                                    for li in cutlass.range(n_tok, unroll=1):
                                                                                                                                                                                        load_pipe.consumer_wait(use_state)
                                                                                                                                                                                        if cute.arch.lane_idx() == 0:
                                                                                                                                                                                            for k in range(K):
                                                                                                                                                                                                dst_val = dst[sK + k]
                                                                                                                                                                                                store_token = dst_val >= 0          # 非负 = primary, 拷贝 payload
                                                                                                                                                                                                raw_dst = dst_val if store_token else -dst_val - 1
                                                                                                                                                                                                drank = raw_dst // NvS
                                                                                                                                                                                                loff = raw_dst % NvS
                                                                                                                                                                                                if store_token:
                                                                                                                                                                                                    drow = drank * NvS_padded + loff
                                                                                                                                                                                                    cp_async_bulk_s2g(s_row, gmem_dst + drow * H, H_BYTES)
                                                                                                                                                                                                # weight scatter: 所有路径都写 weight(包括 duplicate)
                                                                                                                                                                                                meta_tensor[drank * meta_stride + weights_off + loff] = wb
                                                                                                                                                                                        use_state.advance()


                                                                                                                                                                                    关键点:weight scatter 对所有 K 路径都执行(包括 duplicate),因为 route weights 是 per-topk 的值,不能 dedup。

                                                                                                                                                                                    4.3.5 Zero Warp(段填充清零)

                                                                                                                                                                                    dispatch.py:467-497:

                                                                                                                                                                                      # Warp 2 并行清零 padding 行
                                                                                                                                                                                      # zero_fill_ranges[e] = (pad_start, n_pad_rows)
                                                                                                                                                                                      while e < zero_groups:
                                                                                                                                                                                          pad_start, n_pad = zero_fill_ranges[e*2], zero_fill_ranges[e*2+1]
                                                                                                                                                                                          if n_pad > 0:
                                                                                                                                                                                              for j in range(n_pad):
                                                                                                                                                                                                  loff = pad_start + j
                                                                                                                                                                                                  local_row = rank * NvS_padded + loff
                                                                                                                                                                                                  cp_async_bulk_s2g(zero_smem, gmem_dst + local_row * H, H_BYTES)
                                                                                                                                                                                                  if with_weights:
                                                                                                                                                                                                      meta_tensor[rank * meta_stride + weights_off + loff] = 0
                                                                                                                                                                                          e += num_sms  # grid-stride


                                                                                                                                                                                      Zero warp 使用预初始化的 zero_smem(所有线程协作清零一次,后续直接复用),避免每次清零都写一遍。

                                                                                                                                                                                      4.3.6 Dedup Builder Warps(3-pass 构建 dedup 结构)

                                                                                                                                                                                      dispatch.py:502-681,这是 dispatch kernel 中最复杂的部分:

                                                                                                                                                                                      Pass 1: Primary election(dispatch.py:557-576)

                                                                                                                                                                                        # 每个 builder warp 扫描自己负责的 src_info chunk
                                                                                                                                                                                        # 对每个 (source_rank, token) key:
                                                                                                                                                                                        #   packed = (kidx << NvS_BITS) | loff
                                                                                                                                                                                        #   atom_min_relaxed_gpu_s32(primary_packed[key], packed)  // 选最小 loff 作为 primary
                                                                                                                                                                                        #   atom_or_relaxed_gpu_b32(kmask[key], 1 << kidx)        // 记录哪些 kidx 存在
                                                                                                                                                                                        #   kidx_to_loff[key * K + kidx] = loff                    // 记录 kidx → loff 映射


                                                                                                                                                                                        Pass 2a: Classification(dispatch.py:593-611)

                                                                                                                                                                                          # 每个 lane 分类自己 chunk 的 slot:
                                                                                                                                                                                          #   primary_loff = packed & NvS_MASK
                                                                                                                                                                                          #   dup_count = popc(mask) - 1
                                                                                                                                                                                          #   if loff == primary_loff and dup_count > 0:
                                                                                                                                                                                          #       lane_grp_n += 1     // 本 lane 负责的 group 数
                                                                                                                                                                                          #       lane_dup_n += dup_count  // 本 lane 负责的 dup 数


                                                                                                                                                                                          Pass 2b: Output emission(dispatch.py:648-681)

                                                                                                                                                                                            # warp-inclusive-scan 得到 lane 间的偏移
                                                                                                                                                                                            # 每个 lane 用 2 个 atomicAdd 预留输出空间
                                                                                                                                                                                            # 然后写入 dup_groups[my_grp*3] = (loff, my_dup, dup_count)
                                                                                                                                                                                            #         dup_loffs[my_dup + pos] = cur_dup_loff


                                                                                                                                                                                            4.3.7 执行时序

                                                                                                                                                                                              Warp 0 (producer):  acquire → G2S → advance → acquire → G2S → ...
                                                                                                                                                                                              Warp 1 (consumer):  wait → 读 dst → S2G(多个 k) → commit → wait → ...
                                                                                                                                                                                              Warp 2 (zero):      并行清零 padding 行
                                                                                                                                                                                              Warp 3+ (builder):  Pass 1 → cross_warp_sync → Pass 2a → cross_warp_sync → Pass 2b
                                                                                                                                                                                              Exit:               cross_rank_barrier → pdl_trigger_dependents


                                                                                                                                                                                              4.3.8 数据流

                                                                                                                                                                                                输入:
                                                                                                                                                                                                  hidden_sh: [S, H] bf16           → stage_smem → NVL hidden_buf
                                                                                                                                                                                                  route_weights_sk: [S, K] fp32    → meta_buf weights 区域
                                                                                                                                                                                                  dst: [N] int32                    → 决定每行写到哪个 rank 的哪个 offset
                                                                                                                                                                                                  zero_fill_ranges: [E+B, 2] int32 → zero warp 读取
                                                                                                                                                                                                  src_info: [NvS] int32            → builder warps 读取


                                                                                                                                                                                                输出:
                                                                                                                                                                                                  hidden_buf: [R*NvS_padded, H] bf16  → 写入目标 rank 的 payload 行
                                                                                                                                                                                                  meta_buf weights: [NvS] fp32         → 写入 route weights
                                                                                                                                                                                                  dup_groups: [NvS, 3] int32           → builder 构建
                                                                                                                                                                                                  dup_loffs: [NvS] int32               → builder 构建
                                                                                                                                                                                                  dup_counts: [2] int32                 → builder 构建


                                                                                                                                                                                                4.3.9 对比基线

                                                                                                                                                                                                维度

                                                                                                                                                                                                标准 EP (all_to_all + permute)

                                                                                                                                                                                                MoonEP Dispatch

                                                                                                                                                                                                数据拷贝

                                                                                                                                                                                                2次(打包 + 解包)

                                                                                                                                                                                                1次(直接写到最终位置)

                                                                                                                                                                                                Permute

                                                                                                                                                                                                显式 permute/unpermute

                                                                                                                                                                                                融合在 dispatch/combine 中

                                                                                                                                                                                                缓冲区

                                                                                                                                                                                                2× S×K×H

                                                                                                                                                                                                1× NvS×H

                                                                                                                                                                                                Dedup

                                                                                                                                                                                                无(每个 token 独立)

                                                                                                                                                                                                构建 dedup 结构 + epilogue 展开

                                                                                                                                                                                                4.3.10 反方辩手

                                                                                                                                                                                                a) 反对最强理由:dedup builder 的 3-pass 设计增加了 dispatch kernel 的延迟,尤其是 Pass 1 的 atom_min_relaxed_gpu_s32 可能成为热点。 b) 最可能错的假设:假设 K ≤ 32。如果 K > 32,kmask 的 u32 位掩码不够用。 c) 胜出条件:K ≤ 32,routing 有一定重复(dedup 收益大);失败条件:K > 32 或 routing 完全无重复(builder 白跑)。 d) 更稳健的做法:不做 dedup,每个 token 的 K 路径都独立拷贝 payload(牺牲带宽但逻辑简单)。 e) 受伤害的利益相关方:K 很大的模型(如 K=64 的 routing)。

                                                                                                                                                                                                4.3.11 参数敏感性

                                                                                                                                                                                                • DEDUP_BUILDER_WARPS = 4(constants.py:17):builder warp 数量。太少则 Pass 1 延迟高;太多则 warp 级别同步开销大。4 是实测甜点。

                                                                                                                                                                                                • stages(pipeline depth):取决于 H 和 smem budget。H=7168 时通常 2-4 stages。

                                                                                                                                                                                                • num_sms:dispatch 的并行度,越大吞吐越高。


                                                                                                                                                                                                4.4 Dispatch Epilogue(in-place 重复展开)

                                                                                                                                                                                                4.4.1 要解决的问题

                                                                                                                                                                                                Dispatch 只拷贝了 primary 行到 NVL shard。对于 duplicate 的 token(被路由到同一 rank 的多个专家),它们的 payload 行还没有被写入。Dispatch Epilogue 负责从 primary 行展开到所有 duplicate slot。

                                                                                                                                                                                                4.4.2 实现机制

                                                                                                                                                                                                dispatch_epilogue.py:44-61:

                                                                                                                                                                                                  class DispatchEpilogueKernel:
                                                                                                                                                                                                      """Round-robin duplicate-group expansion on the local NVL shard.


                                                                                                                                                                                                      两个 warp 镜像 dispatch 的数据路径:
                                                                                                                                                                                                      - Warp 0 (producer): 把 B 个 primary 行 G2S 到 smem pipeline stage
                                                                                                                                                                                                      - Warp 1 (consumer): 把每行 S2G 到所有 duplicate slot
                                                                                                                                                                                                      """

                                                                                                                                                                                                  核心逻辑(dispatch_epilogue.py:208-305):

                                                                                                                                                                                                    # 从 dup_counts[0] 读取有效 group 数
                                                                                                                                                                                                    n_groups = dup_counts_tensor[0]


                                                                                                                                                                                                    # Warp 0 (producer): 批量 G2S
                                                                                                                                                                                                    while gi < n_groups:
                                                                                                                                                                                                        n = min(B, n_groups - gi)
                                                                                                                                                                                                        # 从 hidden_buf 读取 B 个 primary 行到 stage_smem
                                                                                                                                                                                                        for idx in range(n):
                                                                                                                                                                                                            loff = dup_groups[(gi+idx) * 3]  # primary_loff
                                                                                                                                                                                                            cp_async_bulk_g2s(stage_smem[idx], hidden[loff], H_BYTES, mbar)


                                                                                                                                                                                                    # Warp 1 (consumer): 批量 S2G 到 duplicate slot
                                                                                                                                                                                                    while gi < n_groups:
                                                                                                                                                                                                        for idx in range(n):
                                                                                                                                                                                                            dup_start = dup_groups[(gi+idx)*3 + 1]
                                                                                                                                                                                                            dup_n = dup_groups[(gi+idx)*3 + 2]
                                                                                                                                                                                                            for k in range(dup_n):
                                                                                                                                                                                                                slot = dup_loffs[dup_start + k]
                                                                                                                                                                                                                cp_async_bulk_s2g(hidden[slot], stage_smem[idx], H_BYTES)

                                                                                                                                                                                                    关键设计:primary 行只从 gmem 读一次,然后 fan-out 到所有 duplicate slot。这比每个 duplicate 都从 gmem 读 primary 要快得多。

                                                                                                                                                                                                    4.4.3 对比 Combine Prologue

                                                                                                                                                                                                    维度

                                                                                                                                                                                                    Dispatch Epilogue

                                                                                                                                                                                                    Combine Prologue

                                                                                                                                                                                                    方向

                                                                                                                                                                                                    primary → duplicate (fan-out)

                                                                                                                                                                                                    duplicate → primary (reduce)

                                                                                                                                                                                                    数据类型

                                                                                                                                                                                                    bf16 (拷贝)

                                                                                                                                                                                                    fp32 (累加)

                                                                                                                                                                                                    无跨 rank barrier

                                                                                                                                                                                                    是(纯本地操作)

                                                                                                                                                                                                    是(纯本地操作)

                                                                                                                                                                                                    被谁消费

                                                                                                                                                                                                    Expert GEMM

                                                                                                                                                                                                    Combine kernel

                                                                                                                                                                                                    4.4.4 反方辩手

                                                                                                                                                                                                    a) 反对最强理由:每个 duplicate group 都要从 gmem 读一次 primary 行,如果 duplicate 很多(K 很大),读带宽可能成为瓶颈。 b) 最可能错的假设:假设 duplicate group 的大小(dup_n)通常很小(≤ K-1)。如果 routing 高度集中,某些 group 的 dup_n 可能很大。 c) 胜出条件:K ≤ 16,routing 有一定分散性;失败条件:K 很大且 routing 极端集中。 d) 更稳健的做法:在 dispatch 中直接写所有 duplicate 行(不做 dedup),牺牲带宽但延迟更低。

                                                                                                                                                                                                    完成度:已实现并运行通过(moonep/dispatch_epilogue.py)


                                                                                                                                                                                                    4.5 Combine Kernel(3-stage fp32 累加)

                                                                                                                                                                                                    4.5.1 要解决的问题

                                                                                                                                                                                                    Combine kernel 执行 dispatch 的逆操作:从 NVL 共享内存中收集 expert output,按 token 聚合(K 次累加),写回 [S, H] 的 token-major 格式。

                                                                                                                                                                                                    核心挑战:

                                                                                                                                                                                                    1. FP32 累加:expert output 是 bf16,但累加必须在 fp32 中进行(避免精度损失)

                                                                                                                                                                                                    2. Dedup 优化:duplicate 的贡献已经由 combine prologue 预累加到 primary slot,combine 只需拉取 primary

                                                                                                                                                                                                    3. Weight gather:route weights 需要同步 gather 回 token-major 格式

                                                                                                                                                                                                    4.5.2 Warp 分工

                                                                                                                                                                                                    combine.py:40-61:

                                                                                                                                                                                                      Warp 0 (PRODUCER):  G2S producer — 从 NVL hidden_buf 读一行到 stage_smem
                                                                                                                                                                                                      Warp 1-4 (ACC):     fp32 ACC consumers — 128 线程累加 fp32 寄存器
                                                                                                                                                                                                      Warp 5 (S2G):       S2G consumer — 把累加结果写回 gmem output
                                                                                                                                                                                                      Warp 6 (WEIGHT):    weight-gather epilogue — 并行 gather route weights(仅 with_weights)

                                                                                                                                                                                                      4.5.3 关键实现细节

                                                                                                                                                                                                      FP32 ACC in Registers(combine.py:363-435):

                                                                                                                                                                                                        # 每个 ACC 线程拥有 H/ACC_THREADS 个 fp32 寄存器
                                                                                                                                                                                                        H_PER_THR = H // ACC_THREADS  # = H // 128
                                                                                                                                                                                                        acc_reg = cute.make_rmem_tensor(H_PER_THR, Float32)


                                                                                                                                                                                                        for s_local in range(n_tok):
                                                                                                                                                                                                            # Prologue: 零初始化累加器
                                                                                                                                                                                                            for j in range(H_PER_THR):
                                                                                                                                                                                                                acc_reg[j] = Float32(0.0)


                                                                                                                                                                                                            for k in range(K):
                                                                                                                                                                                                                dst_val = dst[sK + k]
                                                                                                                                                                                                                accumulate_token = dst_val >= 0  # 只累加 primary (dst >= 0)
                                                                                                                                                                                                                if accumulate_token:
                                                                                                                                                                                                                    load_pipe.consumer_wait(use_state)
                                                                                                                                                                                                                    for j in range(H_PER_THR):
                                                                                                                                                                                                                        idx = j * ACC_THREADS + acc_tid
                                                                                                                                                                                                                        acc_reg[j] += Float32(stage_smem[idx, use_state.index])
                                                                                                                                                                                                                    load_pipe.consumer_release(use_state)


                                                                                                                                                                                                            # Epilogue: fp32 → bf16 写回
                                                                                                                                                                                                            for j in range(H_PER_THR):
                                                                                                                                                                                                                out_smem[idx, stg_o] = BFloat16(acc_reg[j])
                                                                                                                                                                                                            acc_bar.arrive_and_wait()  # 4 个 ACC warp 同步
                                                                                                                                                                                                            out_pipe.producer_commit(out_state)


                                                                                                                                                                                                        Weight Gather(combine.py:485-511):

                                                                                                                                                                                                          # Warp 6 独立于数据路径,直接从 meta_buf 读取 route weights
                                                                                                                                                                                                          # 对所有 K 路径(包括 duplicate)都执行 gather
                                                                                                                                                                                                          for sk_chunk inrange(n_chunks):
                                                                                                                                                                                                              dst_val = dst[sk_global]
                                                                                                                                                                                                              raw_dst = dst_val if dst_val >= 0 else -dst_val - 1
                                                                                                                                                                                                              drank = raw_dst // NvS
                                                                                                                                                                                                              loff = raw_dst % NvS
                                                                                                                                                                                                              wb = meta_tensor[drank * meta_stride + weights_off + loff]
                                                                                                                                                                                                              output_sk[sk_global] = wb


                                                                                                                                                                                                          4.5.4 与 DeepEP v2 的性能对比

                                                                                                                                                                                                          README 的性能数据(README.md:13-32):

                                                                                                                                                                                                          • MoonEP 的 combine 时间在所有 imbalance 级别下都显著低于 DeepEP v2

                                                                                                                                                                                                          • MoonEP 的总 dispatch 时间(含 planning + weight prefetch)与 DeepEP v2 的 dispatch 相当,但在 imbalance 时领先

                                                                                                                                                                                                          • MoonEP 的 combine 明显更快,因为 dedup 减少了需要拉取的行数

                                                                                                                                                                                                          e2e_vs_deepep
                                                                                                                                                                                                          e2e_vs_deepep
                                                                                                                                                                                                          comm_vs_deepep
                                                                                                                                                                                                          comm_vs_deepep

                                                                                                                                                                                                          4.5.5 反方辩手

                                                                                                                                                                                                          a) 反对最强理由:6-7 个 warp 的设计增加了 occupancy 压力,可能在某些 GPU 上导致 register spilling。 b) 最可能错的假设:假设 H % 128 == 0。如果 H 不是 128 的倍数,ACC 线程数需要调整。 c) 胜出条件:H ≥ 128 且 K ≥ 2(dedup 收益明显);失败条件:H 很小(如 H=64)且 K=1(无 dedup)。 d) 更稳健的做法:不做 dedup 优化,直接拉取所有 K 行。

                                                                                                                                                                                                          完成度:已实现并运行通过(moonep/combine.py)


                                                                                                                                                                                                          4.6 Prefetch + GradReduce(权重预取 + 梯度归约)

                                                                                                                                                                                                          4.6.1 Prefetch Kernel

                                                                                                                                                                                                          要解决的问题:远程专家的权重在其他 rank 的 GPU 上,dispatch 后需要在本地 GEMM 之前把权重拉过来。

                                                                                                                                                                                                          prefetch.py:29-76:

                                                                                                                                                                                                            class PrefetchKernel:
                                                                                                                                                                                                                """Persistent 2D TMA remote-expert prefetch."""
                                                                                                                                                                                                                M_BLOCK = 128  # tile 高度
                                                                                                                                                                                                                N_BLOCK = 128  # tile 宽度
                                                                                                                                                                                                                # 用 2D TMA 拷贝 H×H' 的权重 tile


                                                                                                                                                                                                            执行流(prefetch.py:137-277):

                                                                                                                                                                                                              # 预扫描:构建 exp_tab/slot_tab(active slot 的 compact 列表)
                                                                                                                                                                                                              n_active = 0
                                                                                                                                                                                                              for b in range(B):
                                                                                                                                                                                                                  e = experts[b]
                                                                                                                                                                                                                  if e >= 0:
                                                                                                                                                                                                                      exp_tab[n_active] = e
                                                                                                                                                                                                                      slot_tab[n_active] = b
                                                                                                                                                                                                                      n_active += 1


                                                                                                                                                                                                              # Warp 0 (producer): 2D TMA G2S
                                                                                                                                                                                                              for tile in range(bidx, total_tiles, num_sms):
                                                                                                                                                                                                                  i = tile // TILES_PER_EXPERT
                                                                                                                                                                                                                  mt = (tile % TILES_PER_EXPERT) // NTILES
                                                                                                                                                                                                                  nt = (tile % TILES_PER_EXPERT) % NTILES
                                                                                                                                                                                                                  expert = exp_tab[i]
                                                                                                                                                                                                                  cute.copy(tma_g2s, tSgS[(None, (expert*MTILES+mt, nt))], tSsS[(None, stage)])


                                                                                                                                                                                                              # Warp 1 (consumer): 2D TMA S2G
                                                                                                                                                                                                              for tile in range(bidx, total_tiles, num_sms):
                                                                                                                                                                                                                  b = slot_tab[i]
                                                                                                                                                                                                                  cute.copy(tma_s2g, tDsD[(None, stage)], tDgD[(None, (b*MTILES+mt, nt))])


                                                                                                                                                                                                              4.6.2 Grad Reduce Kernel

                                                                                                                                                                                                              要解决的问题:backward 时,remote expert 的权重梯度在 reduce buffer 中,需要归约回 home rank。

                                                                                                                                                                                                              grad_reduce.py:46-54:

                                                                                                                                                                                                                class GradReduceKernel:
                                                                                                                                                                                                                    M_BLOCK = 128
                                                                                                                                                                                                                    N_BLOCK = 128
                                                                                                                                                                                                                    STAGES = 3           # load pipeline depth
                                                                                                                                                                                                                    ACC_THREADS = 128    # 4 个 fp32 ACC warp
                                                                                                                                                                                                                    NUM_THREADS = 160    # 1 load + 4 acc


                                                                                                                                                                                                                两阶段执行(grad_reduce.py:297-389):

                                                                                                                                                                                                                  # Phase 1: warp-specialized accumulate(无 clear)
                                                                                                                                                                                                                  for work_idx in range(bidx, total_work, num_sms):
                                                                                                                                                                                                                      local_expert = alist[work_idx // TILES_PER_EXPERT]
                                                                                                                                                                                                                      # Warp 0: streaming remote reduce tiles (G2S TMA)
                                                                                                                                                                                                                      # Warps 1-4: seed local grad + accumulate remote + store back


                                                                                                                                                                                                                  # Phase 2: cross_rank_barrier then local clear
                                                                                                                                                                                                                  cross_rank_barrier(...)
                                                                                                                                                                                                                  # 每个 rank 清零自己的 consumed slots(16B vector stores)


                                                                                                                                                                                                                  关键设计:accumulation never writes the reduce buffers。所有累加在 fp32 寄存器中完成,最后一次性写回 home rank 的 grad buffer。清零只清自己的 consumed slots,不做 remote write clear(因为 NVLink 双向带宽共享,remote write 会拉长 phase 1)。

                                                                                                                                                                                                                  4.6.3 反方辩手

                                                                                                                                                                                                                  a) Prefetch: 2D TMA 的 tile 大小固定 128×128,如果 H 或 H' 不是 128 的倍数会浪费带宽。 b) GradReduce: prescan 的 match_any_b32 + atomicAdd 在 warp 0 上串行执行,当 R*B 很大时可能成为瓶颈。 c) 更稳健的做法:不预取权重,直接从 home rank 的 NVLink mapping 读取(内存语义,慢但正确)。README 提到推理时可以这样做。

                                                                                                                                                                                                                  完成度:已实现并运行通过(moonep/prefetch.py + moonep/grad_reduce.py)


                                                                                                                                                                                                                  4.7 跨 rank 同步基础设施

                                                                                                                                                                                                                  4.7.1 grid_sync(_common.py:249-271)

                                                                                                                                                                                                                    def grid_sync(bar_ptr, nsm, tid):
                                                                                                                                                                                                                        """Self-resetting cooperative grid barrier."""
                                                                                                                                                                                                                        # SM0 发送 TAG - (nsm-1),其他 SM 发送 +1
                                                                                                                                                                                                                        # 总增量 = TAG = 0x80000000,低 31 位始终为 0
                                                                                                                                                                                                                        # top bit 翻转表示所有 SM 到达


                                                                                                                                                                                                                    4.7.2 cross_rank_barrier(_common.py:274-347)

                                                                                                                                                                                                                      def cross_rank_barrier(meta_buf, meta_stride, barrier_off, rank, num_ranks, bar_ptr, nsm, num_threads, tid):
                                                                                                                                                                                                                          """Self-resetting cross-rank barrier."""
                                                                                                                                                                                                                          # Entry fence: fence.proxy.alias (multicast → unicast coherence)
                                                                                                                                                                                                                          grid_sync(bar_ptr, nsm, tid)
                                                                                                                                                                                                                          # Block 0: 发送 +/-1 信号到 peer 的 phase slot
                                                                                                                                                                                                                          # 自旋等待自己的 phase slot 达到目标值
                                                                                                                                                                                                                          # Exit fence: fence.proxy.async.global (generic → TMA coherence)
                                                                                                                                                                                                                          grid_sync(bar_ptr, nsm, tid)


                                                                                                                                                                                                                      3 个 int32 slot 的自复位设计(_common.py:286-303):

                                                                                                                                                                                                                      • +0/+1:两个 phase 信号(交替使用)

                                                                                                                                                                                                                      • +2:本地 phase/sign 状态

                                                                                                                                                                                                                      4.7.3 cross_warp_sync(_common.py:349-390)

                                                                                                                                                                                                                        def cross_warp_sync(bar_ptr, nparticipants, leader):
                                                                                                                                                                                                                            """All-participating-warp barrier."""
                                                                                                                                                                                                                            # leader warp 发送 TAG - (nparticipants-1)
                                                                                                                                                                                                                            # 其他 warp 发送 +1
                                                                                                                                                                                                                            # 总增量 = TAG,自复位


                                                                                                                                                                                                                        用于 dispatch builder 的 4 个 warp 之间的同步。

                                                                                                                                                                                                                        4.7.4 PTX 工具函数

                                                                                                                                                                                                                        函数

                                                                                                                                                                                                                        行号

                                                                                                                                                                                                                        用途

                                                                                                                                                                                                                        cp_async_bulk_g2s

                                                                                                                                                                                                                        _common.py:414

                                                                                                                                                                                                                        TMA G2S 拷贝

                                                                                                                                                                                                                        cp_async_bulk_s2g

                                                                                                                                                                                                                        _common.py:438

                                                                                                                                                                                                                        TMA S2G 拷贝

                                                                                                                                                                                                                        atom_add_release_gpu

                                                                                                                                                                                                                        _common.py:75

                                                                                                                                                                                                                        GPU scope atomicAdd (release)

                                                                                                                                                                                                                        atom_add_relaxed_gpu_s32

                                                                                                                                                                                                                        _common.py:92

                                                                                                                                                                                                                        GPU scope atomicAdd (relaxed)

                                                                                                                                                                                                                        atom_min_relaxed_gpu_s32

                                                                                                                                                                                                                        _common.py:109

                                                                                                                                                                                                                        GPU scope atomicMin (relaxed)

                                                                                                                                                                                                                        atom_or_relaxed_gpu_b32

                                                                                                                                                                                                                        _common.py:125

                                                                                                                                                                                                                        GPU scope atomicOr (relaxed)

                                                                                                                                                                                                                        popc_b32

                                                                                                                                                                                                                        _common.py:159

                                                                                                                                                                                                                        32-bit popcount

                                                                                                                                                                                                                        ctz_b32

                                                                                                                                                                                                                        _common.py:176

                                                                                                                                                                                                                        Count trailing zeros

                                                                                                                                                                                                                        ld_acquire_gpu_s32

                                                                                                                                                                                                                        _common.py:199

                                                                                                                                                                                                                        GPU scope load (acquire)

                                                                                                                                                                                                                        ld_acquire_sys_s32

                                                                                                                                                                                                                        _common.py:232

                                                                                                                                                                                                                        System scope load (acquire)

                                                                                                                                                                                                                        red_add_release_sys

                                                                                                                                                                                                                        _common.py:216

                                                                                                                                                                                                                        System scope reduce add

                                                                                                                                                                                                                        pdl_trigger_dependents

                                                                                                                                                                                                                        _common.py:394

                                                                                                                                                                                                                        Programmatic dependent launch trigger

                                                                                                                                                                                                                        pdl_wait_predecessor

                                                                                                                                                                                                                        _common.py:404

                                                                                                                                                                                                                        PDL wait

                                                                                                                                                                                                                        0x05 本项目的实现 & 参考 & 讨论

                                                                                                                                                                                                                        5.1 具体代码

                                                                                                                                                                                                                          r"""MoonEP:完美均衡的专家并行调度(论文 §5.2.1 + 附录 E)。


                                                                                                                                                                                                                          设计动机(why)
                                                                                                                                                                                                                          -------------
                                                                                                                                                                                                                          专家并行的老问题是**路由负载不均**:Top-K 路由下不同专家在不同
                                                                                                                                                                                                                          micro-batch、不同层的负载都是波动的,某几个"热"专家会把 token 堆到少数
                                                                                                                                                                                                                          rank 上,带来三重代价:
                                                                                                                                                                                                                            1. 计算瓶颈:hot rank 变慢,拖慢整次同步;
                                                                                                                                                                                                                            2. 显存碎片:路由后的激活 shape 每步每层都不同,无法预分配固定缓冲;
                                                                                                                                                                                                                            3. host 同步停滞:形状未知,host 每层都要和设备同步一次才能知道该分配多大
                                                                                                                                                                                                                               显存、怎么发 grouped GEMM,直接打穿流水线。


                                                                                                                                                                                                                          MoonEP 的关键洞察(附录 E)
                                                                                                                                                                                                                          ----------------------------
                                                                                                                                                                                                                          只要允许 **复制**(redundant expert),就可以让每个 TF 拿到的 token 数
                                                                                                                                                                                                                          **严格相等**(每个 rank 恰好 ``S*K`` 个),从而重获静态 shape 的三大好处:
                                                                                                                                                                                                                            - 通信缓冲固定为 ``S*K``(而不是最坏 ``S*K*R``);
                                                                                                                                                                                                                            - grouped GEMM 的形状在 launch 前已知,无需 host 同步;
                                                                                                                                                                                                                            - 负载零波动,无 hot rank。


                                                                                                                                                                                                                          问题变成:复制多少份才够?**附录 E 的定理**给出了答案:
                                                                                                                                                                                                                              M(I) <= E/R  恒成立,且界基本是紧的。
                                                                                                                                                                                                                          即每 rank 预留给"非本地主家专家"的槽位(redundant slots)只需 ``E/R`` 个,
                                                                                                                                                                                                                          就**永远**存在一个可行规划——训练永不因规划失败中断。


                                                                                                                                                                                                                          构造性证明(plan_redundant_experts 就是它的直接翻译):
                                                                                                                                                                                                                            反复挑选"欠载 rank u"和"过载 rank o",把 ``target - load(u)`` 个 token
                                                                                                                                                                                                                            从 o 搬到 u。因为 ``load(o) > target >= deficit(u)``,o 永远拿得出足够
                                                                                                                                                                                                                            token,u 一次就被填到 target、之后不再被碰。每轮填死一个 rank,至多
                                                                                                                                                                                                                            ``R-1`` 轮结束;并且因为每个 rank 至多被填一次,它收来的全部远端 token
                                                                                                                                                                                                                            来自**同一个**其他 rank,那个 rank 只 home ``E/R`` 个专家 —— 于是每 rank
                                                                                                                                                                                                                            冗余副本 ≤ ``E/R``。


                                                                                                                                                                                                                          本实现在 CPU 上把"规划层"完整落地(plan_redundant_experts → RedundancyPlan
                                                                                                                                                                                                                          → build_permutation / dispatch / combine),并用数值实验验证"恒定 S*K 缓冲
                                                                                                                                                                                                                          vs 最坏 S*K*R"以及 M(T)<=E/R 的界。真实 GPU 上的对称内存 / zero-copy
                                                                                                                                                                                                                          dispatch / prefetch 等内核级优化不属于本教学实现的范围(见 4.10 升华)。
                                                                                                                                                                                                                          """


                                                                                                                                                                                                                          @dataclass
                                                                                                                                                                                                                          class RedundancyPlan:
                                                                                                                                                                                                                              """一次规划的结果:每个 (rank, expert) 持有的 token 数。"""


                                                                                                                                                                                                                              n_experts: int
                                                                                                                                                                                                                              n_ranks: int
                                                                                                                                                                                                                              experts_per_rank: int
                                                                                                                                                                                                                              #: ``holdings[rank][expert] = 该 rank 要为 expert 计算的 token 数``。
                                                                                                                                                                                                                              holdings: list[dict[int, int]] | None = None
                                                                                                                                                                                                                              #: 每个 rank 计算的**非本地**(redundant)专家集合。
                                                                                                                                                                                                                              redundant: list[set[int]] | None = None
                                                                                                                                                                                                                              #: 规划器执行的"搬运"次数。
                                                                                                                                                                                                                              moves: int = 0


                                                                                                                                                                                                                              def __post_init__(self) -> None:
                                                                                                                                                                                                                                  if self.holdings is None:
                                                                                                                                                                                                                                      self.holdings = [{} for _ in range(self.n_ranks)]
                                                                                                                                                                                                                                  if self.redundant is None:
                                                                                                                                                                                                                                      self.redundant = [set() for _ in range(self.n_ranks)]


                                                                                                                                                                                                                              def home_rank(self, expert: int) -> int:
                                                                                                                                                                                                                                  """专家 ``expert`` 的主家(home)rank:按连续切片分配。"""
                                                                                                                                                                                                                                  return expert // self.experts_per_rank


                                                                                                                                                                                                                              def tokens_per_rank(self) -> list[int]:
                                                                                                                                                                                                                                  """每个 rank 实际计算的 token 数(应全部等于 target)。"""
                                                                                                                                                                                                                                  return [sum(h.values()) for h in self.holdings]


                                                                                                                                                                                                                              def max_redundant(self) -> int:
                                                                                                                                                                                                                                  """所有 rank 中冗余副本数目的最大值(界要 <= E/R)。"""
                                                                                                                                                                                                                                  return max((len(r) for r in self.redundant), default=0)


                                                                                                                                                                                                                              @property
                                                                                                                                                                                                                              def capacity(self) -> int:
                                                                                                                                                                                                                                  """附录 E 的界:E/R 个冗余槽位/rank(向上取整)。"""
                                                                                                                                                                                                                                  return -(-self.n_experts // self.n_ranks)


                                                                                                                                                                                                                              def is_balanced(self) -> bool:
                                                                                                                                                                                                                                  """所有 rank 的负载严格相同。"""
                                                                                                                                                                                                                                  counts = self.tokens_per_rank()
                                                                                                                                                                                                                                  return len(set(counts)) <= 1


                                                                                                                                                                                                                              def respects_bound(self) -> bool:
                                                                                                                                                                                                                                  """冗余副本数不超过容量界。"""
                                                                                                                                                                                                                                  return self.max_redundant() <= self.capacity


                                                                                                                                                                                                                              def summary(self) -> dict[str, float]:
                                                                                                                                                                                                                                  return {
                                                                                                                                                                                                                                      "balanced": float(self.is_balanced()),
                                                                                                                                                                                                                                      "max_redundant": float(self.max_redundant()),
                                                                                                                                                                                                                                      "capacity": float(self.capacity),
                                                                                                                                                                                                                                      "moves": float(self.moves),
                                                                                                                                                                                                                                  }



                                                                                                                                                                                                                          def plan_redundant_experts(
                                                                                                                                                                                                                              loads: list[int] | Tensor,
                                                                                                                                                                                                                              n_ranks: int,
                                                                                                                                                                                                                              *,
                                                                                                                                                                                                                              experts_per_rank: int | None = None,
                                                                                                                                                                                                                          ) -> RedundancyPlan:
                                                                                                                                                                                                                              """规划一个完美均衡的分配(附录 A 构造的直接翻译)。


                                                                                                                                                                                                                              Args:
                                                                                                                                                                                                                                  loads: ``loads[e]`` = 路由到专家 ``e`` 的 token-专家指派个数。
                                                                                                                                                                                                                                  n_ranks: 专家并行度 R。
                                                                                                                                                                                                                                  experts_per_rank: 每 rank 本地专家数(缺省 = ceil(E/R))。


                                                                                                                                                                                                                              Returns:
                                                                                                                                                                                                                                  均衡的 RedundancyPlan。要求总指派数能被 R 整除
                                                                                                                                                                                                                                  (Top-K × S × R 的算术让 target 恰为 S*K)。


                                                                                                                                                                                                                              算法(一步步验证界):
                                                                                                                                                                                                                                1. 初始:每个 rank 只持有它 home 专家的 token(``home = min(e // epr, R-1)``)。
                                                                                                                                                                                                                                2. 主循环:
                                                                                                                                                                                                                                   - 找第一个欠载 rank ``u``(load(u) < target);
                                                                                                                                                                                                                                   - 找当前最过载的 rank ``o``;
                                                                                                                                                                                                                                   - 从 o 的 holdings 中(从大专家开始,控制冗余副本数)取出
                                                                                                                                                                                                                                     ``need = target - load(u)`` 个 token 搬到 u;
                                                                                                                                                                                                                                   - o 一定是够拿的(load(o) > target >= need),所以 u 恰好落 target;
                                                                                                                                                                                                                                3. 终止:某个 rank 一旦被填满再也不被触碰,至多 R-1 轮收敛。
                                                                                                                                                                                                                              """
                                                                                                                                                                                                                              if isinstance(loads, Tensor):
                                                                                                                                                                                                                                  loads = [int(x) for x in loads.tolist()]
                                                                                                                                                                                                                              n_experts = len(loads)
                                                                                                                                                                                                                              experts_per_rank = experts_per_rank or -(-n_experts // n_ranks)


                                                                                                                                                                                                                              total = sum(loads)
                                                                                                                                                                                                                              if total % n_ranks != 0:
                                                                                                                                                                                                                                  raise ValueError(
                                                                                                                                                                                                                                      f"总 token-专家指派数 {total} 不能被 {n_ranks} 个 rank 整除;"
                                                                                                                                                                                                                                      "MoonEP 的静态 shape 需要一个能整除的总量"
                                                                                                                                                                                                                                  )
                                                                                                                                                                                                                              target = total // n_ranks


                                                                                                                                                                                                                              plan = RedundancyPlan(n_experts, n_ranks, experts_per_rank)
                                                                                                                                                                                                                              # 初始摆放:每家放自家专家的 token。
                                                                                                                                                                                                                              for e, load in enumerate(loads):
                                                                                                                                                                                                                                  if load:
                                                                                                                                                                                                                                      home = min(e // experts_per_rank, n_ranks - 1)
                                                                                                                                                                                                                                      plan.holdings[home][e] = plan.holdings[home].get(e, 0) + load


                                                                                                                                                                                                                              current = [sum(h.values()) for h in plan.holdings]


                                                                                                                                                                                                                              while True:
                                                                                                                                                                                                                                  # 找到第一个欠载 rank——它的负载将被精确补齐。
                                                                                                                                                                                                                                  under = next((r for r in range(n_ranks) if current[r] < target), None)
                                                                                                                                                                                                                                  if under is None:
                                                                                                                                                                                                                                      break  # 都已均衡(含整除舍入内)
                                                                                                                                                                                                                                  # 找最过载的 rank 作为"供应者"。
                                                                                                                                                                                                                                  over = max(range(n_ranks), key=lambda r: current[r])
                                                                                                                                                                                                                                  if current[over] <= target:
                                                                                                                                                                                                                                      break  # 整数舍入内已均衡
                                                                                                                                                                                                                                  need = target - current[under]


                                                                                                                                                                                                                                  # 从 over 手里按"大专家优先"搬 need 个 token 给 under。
                                                                                                                                                                                                                                  # 大专家优先 => 尽可能少搬不同的专家 => 冗余副本数少。
                                                                                                                                                                                                                                  for expert in sorted(plan.holdings[over], key=lambda e: -plan.holdings[over][e]):
                                                                                                                                                                                                                                      if need == 0:
                                                                                                                                                                                                                                          break
                                                                                                                                                                                                                                      take = min(plan.holdings[over][expert], need)
                                                                                                                                                                                                                                      plan.holdings[over][expert] -= take
                                                                                                                                                                                                                                      if plan.holdings[over][expert] == 0:
                                                                                                                                                                                                                                          del plan.holdings[over][expert]
                                                                                                                                                                                                                                      plan.holdings[under][expert] = plan.holdings[under].get(expert, 0) + take
                                                                                                                                                                                                                                      # 非本地专家级别才计入冗余。
                                                                                                                                                                                                                                      if expert // experts_per_rank != under:
                                                                                                                                                                                                                                          plan.redundant[under].add(expert)
                                                                                                                                                                                                                                      need -= take


                                                                                                                                                                                                                                  current = [sum(h.values()) for h in plan.holdings]
                                                                                                                                                                                                                                  plan.moves += 1
                                                                                                                                                                                                                                  if plan.moves > n_ranks * n_ranks:  # 保险丝:理论上不会触发
                                                                                                                                                                                                                                      raise RuntimeError("MoonEP 规划器未收敛")


                                                                                                                                                                                                                              return plan


                                                                                                                                                                                                                          def redundancy_lower_bound(loads: list[int], n_ranks: int, experts_per_rank: int) -> int:
                                                                                                                                                                                                                              """冗余副本数的一个下界(廉价健全性检查)。


                                                                                                                                                                                                                              只要有任一 rank 的 home 负载低于 target,它就必须至少算 1 个非本地专家,
                                                                                                                                                                                                                              所以 max_redundant >= 1 一旦路由不均衡就成立。论文用整数线性规划求精确
                                                                                                                                                                                                                              最优作参考,这里用下界防止规划器做匪夷所思的事。
                                                                                                                                                                                                                              """
                                                                                                                                                                                                                              target = sum(loads) // n_ranks
                                                                                                                                                                                                                              home = [0] * n_ranks
                                                                                                                                                                                                                              for e, load in enumerate(loads):
                                                                                                                                                                                                                                  home[min(e // experts_per_rank, n_ranks - 1)] += load
                                                                                                                                                                                                                              return 1 if any(h < target for h in home) else 0


                                                                                                                                                                                                                          class MoonEP:
                                                                                                                                                                                                                              """静态 shape 下的专家派发与汇总。


                                                                                                                                                                                                                              plan -> build_permutation -> dispatch/combine 三段式。由于每个 rank 都拿到
                                                                                                                                                                                                                              恰好 ``S*K`` 个 token,通信缓冲形状已知,permutation 一步到位(fuse 的
                                                                                                                                                                                                                              permute/unpermute),grouped GEMM 的形状也能在 launch 前确定。
                                                                                                                                                                                                                              """


                                                                                                                                                                                                                              def __init__(self, n_experts: int, n_ranks: int):
                                                                                                                                                                                                                                  self.n_experts = n_experts
                                                                                                                                                                                                                                  self.n_ranks = n_ranks
                                                                                                                                                                                                                                  self.experts_per_rank = -(-n_experts // n_ranks)
                                                                                                                                                                                                                                  self.last_plan: RedundancyPlan | None = None


                                                                                                                                                                                                                              # -- 规划 ----------------------------------------------------------------


                                                                                                                                                                                                                              def plan(self, expert_ids: Tensor) -> RedundancyPlan:
                                                                                                                                                                                                                                  """从一维路由专家 id 张量规划。


                                                                                                                                                                                                                                  Args:
                                                                                                                                                                                                                                      expert_ids: ``(N*K,)`` 每 token 的 K 个路由专家 id(扁平)。


                                                                                                                                                                                                                                  Returns:
                                                                                                                                                                                                                                      均衡计划。单进程实现不跨 rank 收集,loads 直接用 bincount。
                                                                                                                                                                                                                                  """
                                                                                                                                                                                                                                  loads = torch.bincount(expert_ids.reshape(-1), minlength=self.n_experts)
                                                                                                                                                                                                                                  plan = plan_redundant_experts(loads, self.n_ranks, experts_per_rank=self.experts_per_rank)
                                                                                                                                                                                                                                  self.last_plan = plan
                                                                                                                                                                                                                                  return plan


                                                                                                                                                                                                                              # -- 派发与合成 ----------------------------------------------------------


                                                                                                                                                                                                                              def build_permutation(
                                                                                                                                                                                                                                  self, expert_ids: Tensor, plan: RedundancyPlan
                                                                                                                                                                                                                              ) -> tuple[Tensor, Tensor, Tensor]:
                                                                                                                                                                                                                                  """返回 ``(order, destination_rank, expert_of_slot)``。


                                                                                                                                                                                                                                  - ``order``:把"扁平指派序列"重排为"按 rank / 按专家分组"的顺序,
                                                                                                                                                                                                                                    派发只需做一次 gather;
                                                                                                                                                                                                                                  - ``expert_of_slot``:目标槽位该算哪个专家,供 grouped GEMM 不看数据
                                                                                                                                                                                                                                    直接 launch。
                                                                                                                                                                                                                                  """
                                                                                                                                                                                                                                  flat = expert_ids.reshape(-1)


                                                                                                                                                                                                                                  # 每个 (rank, expert) 的剩余容量,直接来自 plan。
                                                                                                                                                                                                                                  remaining = [dict(h) for h in plan.holdings]
                                                                                                                                                                                                                                  dest = torch.empty_like(flat)
                                                                                                                                                                                                                                  cursor = {}
                                                                                                                                                                                                                                  for idx in range(flat.numel()):
                                                                                                                                                                                                                                      e = int(flat[idx])
                                                                                                                                                                                                                                      r = cursor.get(e)
                                                                                                                                                                                                                                      if r is None or remaining[r].get(e, 0) == 0:
                                                                                                                                                                                                                                          r = next(
                                                                                                                                                                                                                                              (rr for rr in range(self.n_ranks) if remaining[rr].get(e, 0) > 0),
                                                                                                                                                                                                                                              None,
                                                                                                                                                                                                                                          )
                                                                                                                                                                                                                                          if r is None:
                                                                                                                                                                                                                                              raise RuntimeError(f"专家 {e} 已无容量")
                                                                                                                                                                                                                                          cursor[e] = r
                                                                                                                                                                                                                                      remaining[r][e] -= 1
                                                                                                                                                                                                                                      dest[idx] = r


                                                                                                                                                                                                                                  # 按 (rank, expert) 排序 => 每个 rank 的切面连续、段内按专家连续,
                                                                                                                                                                                                                                  # 恰好构成一个 grouped GEMM。
                                                                                                                                                                                                                                  key = dest.to(torch.int64) * self.n_experts + flat.to(torch.int64)
                                                                                                                                                                                                                                  # 老 torch(1.11)的 argsort 不支持 stable=,加微小扰动保证原序内的稳定。
                                                                                                                                                                                                                                  idx = torch.arange(key.numel(), device=key.device, dtype=torch.int64)
                                                                                                                                                                                                                                  order = torch.argsort(key * key.numel() + idx)
                                                                                                                                                                                                                                  return order, dest, flat[order]


                                                                                                                                                                                                                              def dispatch(self, tokens: Tensor, order: Tensor) -> Tensor:
                                                                                                                                                                                                                                  """fused permute:一次 gather 进专家分组的槽位。"""
                                                                                                                                                                                                                                  return tokens.index_select(0, order)


                                                                                                                                                                                                                              def combine(self, expert_out: Tensor, order: Tensor) -> Tensor:
                                                                                                                                                                                                                                  """fused unpermute:dispatch 的精确逆操作。"""
                                                                                                                                                                                                                                  out = torch.empty_like(expert_out)
                                                                                                                                                                                                                                  return out.index_copy_(0, order, expert_out)


                                                                                                                                                                                                                              def static_shape(self, tokens_per_rank: int) -> tuple[int, ...]:
                                                                                                                                                                                                                                  """每个 rank 使用的计算 shape(launch 前已知)。"""
                                                                                                                                                                                                                                  return (tokens_per_rank,)


                                                                                                                                                                                                                          5.2 MoonEP-master 中的"决定拷贝哪些"与"实际拷贝"

                                                                                                                                                                                                                           

                                                                                                                                                                                                                          我们主要参考 MoonEP-master 的 Python 代码。

                                                                                                                                                                                                                          ”

                                                                                                                                                                                                                          这两件事被严格分离在两个文件里——这是 MoonEP 的核心设计:规划(planning)与执行(prefetch)解耦。

                                                                                                                                                                                                                          5.2.1 决定拷贝哪些专家:moonep/planning.py 的 PlanningKernel

                                                                                                                                                                                                                          生产实现是 CUDA kernel(planning.py:353class PlanningKernel,入口 :1294 launch_planning),可读性差。但仓库贴心地提供了语义等价的 Python 参考实现,决策逻辑一目了然:

                                                                                                                                                                                                                          tests/planning_reference.py:149-166 —— 这就是"决定拷贝哪些"的地方:

                                                                                                                                                                                                                            for d in range(R):                                    # :149  遍历每个 rank
                                                                                                                                                                                                                                local_start = d * epn
                                                                                                                                                                                                                                local_end = local_start + epn


                                                                                                                                                                                                                                # ① 筛出"该 rank 要算、但不是自己 home 的"专家 = 远端专家
                                                                                                                                                                                                                                remote_experts = [
                                                                                                                                                                                                                                    e for e in range(E)
                                                                                                                                                                                                                                    if alloc[e, d].item() > 0 and not (local_start <= e < local_end)
                                                                                                                                                                                                                                ]                                                 # :153-156


                                                                                                                                                                                                                                # ② 按 token 数降序排(tie-break 用 expert id 保证确定性)
                                                                                                                                                                                                                                remote_experts.sort(key=lambda e: (alloc[e, d].item(), e), reverse=True)   # :160


                                                                                                                                                                                                                                # ③ 只取前 B 个,写进 experts_to_copy
                                                                                                                                                                                                                                for b, e in enumerate(remote_experts[:B]):        # :162
                                                                                                                                                                                                                                    experts_to_copy[d, b] = e                     # :163  ★决策落盘
                                                                                                                                                                                                                                    remote_stats_all[e // epn, 1] += 1

                                                                                                                                                                                                                            决策规则三句话:

                                                                                                                                                                                                                            1. 候选:alloc[e,d] > 0 且 e 不属于 rank d 的 home 区间 → 远端专家(:153-156)

                                                                                                                                                                                                                            2. 排序:按该 rank 要为它算的 token 数降序(:160),注释 :158-159 说明动机:"Pick the B remote expert segments with the most tokens for VM prefetch"

                                                                                                                                                                                                                            3. 截断:只拷 前 B 个(:162,B = prefetch slot 数),其余远端专家走原路径

                                                                                                                                                                                                                            关键产物是 experts_to_copy,形状 [R, B],初值 -1(:139),-1 表示该 slot 空置。

                                                                                                                                                                                                                            紧接着 :166-193 用这个决策重排物理 token 顺序:VM group id 0..E-1 是全局专家组,E..E+B-1 是被选中远端专家的 prefetch slot(注释 :169-171);:177if g not in experts_to_prefetch 确保被 prefetch 的专家不在原位重复占空间。

                                                                                                                                                                                                                             

                                                                                                                                                                                                                            为什么按 token 数排序?因为拷权重的成本固定(H×H' 一份),而收益 ∝ 该 slot 要处理的 token 数。拷"最热"的远端专家,单位带宽换来的计算本地化收益最大。

                                                                                                                                                                                                                            ”

                                                                                                                                                                                                                            5.2.2 实际拷贝专家权重:moonep/prefetch.py

                                                                                                                                                                                                                            文件头 :4 一句话点题:

                                                                                                                                                                                                                             

                                                                                                                                                                                                                            "Copies selected remote expert weights from remote_expert[E, H, H'] into ..."

                                                                                                                                                                                                                            ”

                                                                                                                                                                                                                            入口:prefetch.py:317 launch_prefetch(...),签名第二个参数就是 experts_to_copy: torch.Tensor(:320),文档 :328 说明 "Entries are ... " ,并有断言 :340-341(必须 contiguous int32)、:351-352(长度必须等于 B)。注意这里是 [B](单 rank 视角),planning 出的是 [R,B],调用时切自己那一行。

                                                                                                                                                                                                                            实际搬运代码:PrefetchKernel.kernel(:138),分三段:

                                                                                                                                                                                                                            ① 压缩稀疏计划(:207-214)

                                                                                                                                                                                                                              n_active = Int32(0)
                                                                                                                                                                                                                              for b in cutlass.range_constexpr(B):
                                                                                                                                                                                                                                  e = experts[b]                    # experts = experts_to_copy
                                                                                                                                                                                                                                  if e >= Int32(0):                 # :210  跳过 -1 空槽
                                                                                                                                                                                                                                      exp_tab[n_active] = e         # :211  源专家 id
                                                                                                                                                                                                                                      slot_tab[n_active] = Int32(b) # :212  目标 slot 号
                                                                                                                                                                                                                                      n_active += Int32(1)
                                                                                                                                                                                                                              total_tiles = n_active * TILES_PER_EXPERT   # :214

                                                                                                                                                                                                                              注释 :202-203 说明动机:压缩后 tile 循环只访问活跃 slot,不必在 B * TILES_PER_EXPERT 个索引里空转。

                                                                                                                                                                                                                              ② 生产者 warp:远端 → shared memory(:216-237)

                                                                                                                                                                                                                                expert = exp_tab[i]                   # :226  查出源专家
                                                                                                                                                                                                                                src_mt = expert * MTILES + mt         # :229  ★源地址由 expert id 算出
                                                                                                                                                                                                                                cute.copy(tma_g2s, tSgS[(None,(src_mt,nt))], tSsS[...], tma_bar_ptr=...)  # :230-235


                                                                                                                                                                                                                                ③ 消费者 warp:shared memory → 本地 prefetch buffer(:239-277)

                                                                                                                                                                                                                                  b = slot_tab[i]                       # :253  查出目标 slot
                                                                                                                                                                                                                                  dst_mt = b * MTILES + mt              # :256  ★目标地址由 slot 号算出
                                                                                                                                                                                                                                  cute.copy(tma_s2g, tDsD[...], tDgD[(None,(dst_mt,nt))])                   # :257-261


                                                                                                                                                                                                                                  这就是真正的拷贝:TMA 双跳 G2S→S2G,按 (M_BLOCK, N_BLOCK) 分块流水(stages 级 pipeline,:194-200),BF16(:167)。:272-275 的 issued >= 2 早释放策略还专门注释了为什么不滞后 stages-1 组(避免 producer 只剩 ~1 个 in-flight load,把带宽打成 tile_bytes / remote_latency)。

                                                                                                                                                                                                                                  5.2.3 一张表总结 MoonEP-master

                                                                                                                                                                                                                                  关注点

                                                                                                                                                                                                                                  位置

                                                                                                                                                                                                                                  说明

                                                                                                                                                                                                                                  决定拷哪些

                                                                                                                                                                                                                                  (生产)

                                                                                                                                                                                                                                  moonep/planning.py:353PlanningKernel

                                                                                                                                                                                                                                  ,入口 :1294 launch_planning

                                                                                                                                                                                                                                  CUDA 实现

                                                                                                                                                                                                                                  决定拷哪些

                                                                                                                                                                                                                                  (可读参考)

                                                                                                                                                                                                                                  tests/planning_reference.py:149-166

                                                                                                                                                                                                                                  ★候选 :153-156 / 排序 :160 / 截断+落盘 :162-163

                                                                                                                                                                                                                                  决策产物

                                                                                                                                                                                                                                  experts_to_copy [R, B]

                                                                                                                                                                                                                                  ,初值 -1(:139)

                                                                                                                                                                                                                                  -1 = 空槽

                                                                                                                                                                                                                                  实际拷贝

                                                                                                                                                                                                                                  (入口)

                                                                                                                                                                                                                                  moonep/prefetch.py:317 launch_prefetch

                                                                                                                                                                                                                                  消费 experts_to_copy

                                                                                                                                                                                                                                  实际拷贝

                                                                                                                                                                                                                                  (kernel)

                                                                                                                                                                                                                                  prefetch.py:138 kernel

                                                                                                                                                                                                                                  压缩 :207-214、G2S :230、S2G :257

                                                                                                                                                                                                                                  源/目标寻址

                                                                                                                                                                                                                                  :229 src_mt = expert*MTILES+mt

                                                                                                                                                                                                                                   / :256 dst_mt = b*MTILES+mt

                                                                                                                                                                                                                                  expert id → slot 号的地址映射


                                                                                                                                                                                                                                  5.3 本项目 src/parallel/moonep.py 中的对应位置

                                                                                                                                                                                                                                  5.3.1 本项目只实现了规划层,没有实现权重拷贝

                                                                                                                                                                                                                                  这一点文件 docstring 已明确声明(moonep.py:34-37):本实现在 CPU 上把"规划层"完整落地(plan_redundant_experts → RedundancyPlan → build_permutation / dispatch / combine),并用数值实验验证"恒定 S*K 缓冲 vs 最坏 S*K*R"以及 M(T)<=E/R 的界。真实 GPU 上的对称内存 / zero-copy dispatch / prefetch 等内核级优化不属于本教学实现的范围。

                                                                                                                                                                                                                                  所以问题二要分两半回答。

                                                                                                                                                                                                                                  5.3.2 决定拷贝哪些专家:plan_redundant_experts:170-183

                                                                                                                                                                                                                                  对应 MoonEP-master 的 planning 层,但算法不同(见下节):

                                                                                                                                                                                                                                    # 从 over 手里按"大专家优先"搬 need 个 token 给 under。
                                                                                                                                                                                                                                    # 大专家优先 => 尽可能少搬不同的专家 => 冗余副本数少。          :170-171
                                                                                                                                                                                                                                    for expert in sorted(plan.holdings[over], key=lambda e: -plan.holdings[over][e]):  # :172 ★选择
                                                                                                                                                                                                                                        if need == 0:
                                                                                                                                                                                                                                            break
                                                                                                                                                                                                                                        take = min(plan.holdings[over][expert], need)      # :175
                                                                                                                                                                                                                                        plan.holdings[over][expert] -= take                # :176  源减
                                                                                                                                                                                                                                        if plan.holdings[over][expert] == 0:
                                                                                                                                                                                                                                            del plan.holdings[over][expert]                # :177-178
                                                                                                                                                                                                                                        plan.holdings[under][expert] = plan.holdings[under].get(expert, 0) + take  # :179 目标加
                                                                                                                                                                                                                                        # 非本地专家级别才计入冗余。
                                                                                                                                                                                                                                        if expert // experts_per_rank != under:            # :181  ★判定是否为冗余副本
                                                                                                                                                                                                                                            plan.redundant[under].add(expert)              # :182  ★决策落盘
                                                                                                                                                                                                                                        need -= take                                       # :183


                                                                                                                                                                                                                                    决策落盘处:plan.redundant[under].add(expert)(:182)——这个集合就是本项目版本的 experts_to_copy。数据结构定义在 :64-65:

                                                                                                                                                                                                                                      #: 每个 rank 计算的**非本地**(redundant)专家集合。
                                                                                                                                                                                                                                      redundant: list[set[int]] | None = None

                                                                                                                                                                                                                                      选择规则::172 的 sorted(..., key=lambda e: -holdings[over][e]) —— 大专家优先,注释 :171 给了理由:"大专家优先 => 尽可能少搬不同的专家 => 冗余副本数少"。

                                                                                                                                                                                                                                      谁给谁搬由主循环决定(:159-168):

                                                                                                                                                                                                                                        under = next((r for r in range(n_ranks) if current[r] < target), None)  # :161 欠载 rank
                                                                                                                                                                                                                                        over  = max(range(n_ranks), key=lambda r: current[r])                   # :165 最过载 rank
                                                                                                                                                                                                                                        need  = target - current[under]                                         # :168 精确补齐量


                                                                                                                                                                                                                                        5.3.3 "实际拷贝"的对应物:只有 token 搬运,没有权重拷贝

                                                                                                                                                                                                                                        本项目里唯一能称为"拷贝"的是 token 数的账面转移(:176-179 那四行加减法)以及数据的 gather/scatter:

                                                                                                                                                                                                                                          def dispatch(self, tokens, order):                     # :277
                                                                                                                                                                                                                                              return tokens.index_select(0, order)               # :279  fused permute


                                                                                                                                                                                                                                          def combine(self, expert_out, order):                  # :281
                                                                                                                                                                                                                                              out = torch.empty_like(expert_out)
                                                                                                                                                                                                                                              return out.index_copy_(0, order, expert_out)       # :284  fused unpermute

                                                                                                                                                                                                                                          但请注意:这是拷贝 token(激活),不是拷贝专家权重。MoonEP-master 的 prefetch.py 拷的是 remote_expert[E, H, H'] 这个权重张量。本项目没有任何对应代码——因为它是单进程 CPU 教学实现,所有专家权重本来就在同一块内存里,不存在"远端权重"这个概念。

                                                                                                                                                                                                                                          build_permutation(:239-275)里的 remaining/cursor 逻辑(:252-267)是在为每个路由指派挑一个有余量的 rank,然后 :271-274 按 (rank, expert) 排序让每个 rank 的切面连续、段内按专家连续——"恰好构成一个 grouped GEMM"(:269-270)。这对应 MoonEP-master 中 planning 的第二部分(planning_reference.py:166-199 那段重排物理 token 顺序、算 cu_seqlens 的逻辑),而不是 prefetch。

                                                                                                                                                                                                                                          5.3.4 本项目对应位置总表

                                                                                                                                                                                                                                          关注点

                                                                                                                                                                                                                                          位置

                                                                                                                                                                                                                                          说明

                                                                                                                                                                                                                                          决定拷贝哪些

                                                                                                                                                                                                                                          (主循环选 under/over)

                                                                                                                                                                                                                                          moonep.py:159-168:161

                                                                                                                                                                                                                                           欠载 rank、:165 最过载 rank、:168 精确补齐量

                                                                                                                                                                                                                                          决定拷贝哪些

                                                                                                                                                                                                                                          (选具体专家)

                                                                                                                                                                                                                                          moonep.py:172

                                                                                                                                                                                                                                          大专家优先排序,理由见注释 :170-171

                                                                                                                                                                                                                                          决策落盘moonep.py:181-182plan.redundant[under].add(expert)

                                                                                                                                                                                                                                          ,判定条件 expert // epr != under

                                                                                                                                                                                                                                          决策产物数据结构

                                                                                                                                                                                                                                          moonep.py:64-65redundant: list[set[int]]

                                                                                                                                                                                                                                          相当于 master 的 experts_to_copy

                                                                                                                                                                                                                                          token 账面转移moonep.py:176-179

                                                                                                                                                                                                                                          源减 / 目标加,四行加减法

                                                                                                                                                                                                                                          激活数据搬运moonep.py:277-284dispatch

                                                                                                                                                                                                                                          /combine

                                                                                                                                                                                                                                          index_select

                                                                                                                                                                                                                                           / index_copy_

                                                                                                                                                                                                                                          专家权重拷贝不存在

                                                                                                                                                                                                                                          见 docstring :34-37 显式声明超出范围


                                                                                                                                                                                                                                          5.3.5 两侧的实质差异(不只是"简化",而是解决不同问题)

                                                                                                                                                                                                                                          这是最容易误读的地方。表面看两边都在算"哪些专家要在非 home rank 上算",但优化目标完全不同:

                                                                                                                                                                                                                                          维度

                                                                                                                                                                                                                                          MoonEP-master

                                                                                                                                                                                                                                          本项目 moonep.py

                                                                                                                                                                                                                                          算法目标

                                                                                                                                                                                                                                          给定已有的 alloc[e,d],挑 B 个最热的远端专家做权重预取

                                                                                                                                                                                                                                          从零构造holdings

                                                                                                                                                                                                                                          ,使每 rank token 数严格相等

                                                                                                                                                                                                                                          alloc

                                                                                                                                                                                                                                           的来源

                                                                                                                                                                                                                                          输入(launch_planning 的上游已算好容量分配)

                                                                                                                                                                                                                                          输出(plan_redundant_experts 自己构造)

                                                                                                                                                                                                                                          筛选依据

                                                                                                                                                                                                                                          token 数降序取前 B(:160,:162)——B 是硬件 slot 数

                                                                                                                                                                                                                                          token 数降序尽量少搬(:172)——为压低冗余副本数

                                                                                                                                                                                                                                          约束B

                                                                                                                                                                                                                                           = prefetch buffer 槽位数(硬件预算)

                                                                                                                                                                                                                                          E/R

                                                                                                                                                                                                                                           = 附录 E 定理的理论界(:88-90 capacity)

                                                                                                                                                                                                                                          未入选的远端专家

                                                                                                                                                                                                                                          走原路径(token 跨 rank 传输,不预取权重)

                                                                                                                                                                                                                                          不存在"未入选"——规划保证总能在界内完成

                                                                                                                                                                                                                                          拷什么权重remote_expert[E,H,H']

                                                                                                                                                                                                                                          (prefetch.py:4)

                                                                                                                                                                                                                                          token/激活

                                                                                                                                                                                                                                          (dispatch/combine)

                                                                                                                                                                                                                                          验证方式

                                                                                                                                                                                                                                          tests/test_prefetch.py

                                                                                                                                                                                                                                          、test_planning.py

                                                                                                                                                                                                                                          is_balanced():92-95

                                                                                                                                                                                                                                          、respects_bound():97-99

                                                                                                                                                                                                                                          MoonEP-master 的 planning 回答"哪些远端专家的权重值得预取"(带宽换计算本地化,B 是硬件预算);本项目的 plan_redundant_experts 回答"如何复制专家使负载严格均衡"(复制换静态 shape,E/R 是理论界)。前者是执行层优化,后者是论文定理的构造性证明。

                                                                                                                                                                                                                                          本项目 docstring :21-32 把这个定理和它的证明都写清楚了:

                                                                                                                                                                                                                                           

                                                                                                                                                                                                                                          M(I) <= E/R 恒成立,且界基本是紧的 …… 因为每个 rank 至多被填一次,它收来的全部远端 token 来自同一个其他 rank,那个 rank 只 home E/R 个专家 —— 于是每 rank 冗余副本 ≤ E/R。

                                                                                                                                                                                                                                          ”

                                                                                                                                                                                                                                          这个"每 rank 至多被填一次"的性质正是 :161 用 next(...) 找第一个欠载 rank、且 :168 一次性精确补到 target 所保证的——填满后 current[u] == target,此后 :161 再也不会选中它。:187-188 的 moves > R*R 保险丝注释也写了"理论上不会触发"。


                                                                                                                                                                                                                                          5.3.6 如果要在本项目补上 prefetch 层

                                                                                                                                                                                                                                          按 master 的结构,缺的是这样一段:

                                                                                                                                                                                                                                            plan.redundant[rank]  ──►  按 holdings[rank][e] 降序取前 B 个  ──►  experts_to_copy[rank]
                                                                                                                                                                                                                                                                                                                    │
                                                                                                                                                                                                                                                                                    expert_weights[e] ──copy──► prefetch_buffer[b]

                                                                                                                                                                                                                                            即:在现有 RedundancyPlan 上加一个 select_prefetch(rank, B) 方法(对应 planning_reference.py:160-163),再加一个按 slot 搬权重的函数(对应 prefetch.py:230/:257 的两跳,CPU 版就是 buffer[b].copy_(expert_w[e]))。这样 before/after 对比就能展示"预取热专家权重 vs 跨 rank 传 token"的带宽差异。

                                                                                                                                                                                                                                            5.4 MoonEP 如何解决静态 shape 问题?

                                                                                                                                                                                                                                            核心思路:用"专家复制"换取"每 rank 恒定负载"。

                                                                                                                                                                                                                                            具体机制(见 src/models/llm/kimi_k3/parallel/moonep.py:1-37):

                                                                                                                                                                                                                                            1. 允许冗余专家副本:每个 rank 除了持有自己的 E/R 个本地专家,还预留最多 ⌈E/R⌉ 个冗余槽位(附录 E 定理保证这个界永远够用);

                                                                                                                                                                                                                                            2. 构造性规划(plan_redundant_experts,moonep.py:110-190):反复找"欠载 rank u" + "最过载 rank o",从 o 搬 target - load(u) 个 token 给 u,每轮填死一个 rank,至多 R-1 轮收敛;

                                                                                                                                                                                                                                            3. 结果:每个 rank 拿到恰好 S·K 个 token——不多不少。

                                                                                                                                                                                                                                            由此带来的静态 shape 三大好处:

                                                                                                                                                                                                                                            • 通信缓冲恒定 = S·K,而非最坏 S·K·R(见 fig_buffer_size 图);

                                                                                                                                                                                                                                            • grouped GEMM 的 shape 在 launch 前已知(每个 rank 知道每专家多少 token),无需 host-device 同步;

                                                                                                                                                                                                                                            • 无 hot rank,负载零波动。

                                                                                                                                                                                                                                            也就是说,MoonEP 不是预测 shape,而是用复制专家的余量空间,把任意不均衡的路由结果"摊平"到恒定 shape——这是把动态问题转化为静态问题的构造性解法。


                                                                                                                                                                                                                                            TransFormer-封面
                                                                                                                                                                                                                                            TransFormer-封面

                                                                                                                                                                                                                                            0xFF 参考

                                                                                                                                                                                                                                            阅读原文

                                                                                                                                                                                                                                            跳转微信打开

                                                                                                                                                                                                                                            •  

                                                                                                                                                                                                                                            【轻量化复刻大模型 / KIMI K3】MoE (Stable LatentMoE) 交互式演示文档

                                                                                                                                                                                                                                            原创 罗西的思考 2026-11-14 17:05 北京

                                                                                                                                                                                                                                            # 【轻量化复刻大模型 / KIMI K3】MoE (Stable LatentMoE) 交互式演示文档

                                                                                                                                                                                                                                            • 0x01 实现概述
                                                                                                                                                                                                                                              • 1.1 模块范围
                                                                                                                                                                                                                                              • 1.2 实现思路
                                                                                                                                                                                                                                              • 1.3 运行方式
                                                                                                                                                                                                                                            • 0x02 核心数学
                                                                                                                                                                                                                                              • 2.1 总体公式
                                                                                                                                                                                                                                              • 2.2 子机制分解
                                                                                                                                                                                                                                            • 0x03 每个 Tab 的详细说明
                                                                                                                                                                                                                                            • Tab 1:原理总览
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 2:Demo 四联图
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 调节建议
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 3:前向契约
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 4:潜空间 width 分离
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • 背景概念
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 5:RMSNorm 稳定性
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • 背景概念
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 调节建议
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 6:梯度稀疏性
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 调节建议
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 7:Dispatch 正确性
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • 背景概念
                                                                                                                                                                                                                                              • 设计思路
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 8:QB 语义
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • 背景概念
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 调节建议
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 9:QB 均衡效果
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 调节建议
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 10:QB 工程行为
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • 背景概念
                                                                                                                                                                                                                                              • 设计思路
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 11:896 专家压力测试
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • 背景概念
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 调节建议
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • Tab 12:SiTU-GLU
                                                                                                                                                                                                                                              • 目的
                                                                                                                                                                                                                                              • 背景概念
                                                                                                                                                                                                                                              • 幅值差异
                                                                                                                                                                                                                                              • UI 组件与参数影响
                                                                                                                                                                                                                                              • 输出图解读
                                                                                                                                                                                                                                              • 调节建议
                                                                                                                                                                                                                                              • 为什么重要
                                                                                                                                                                                                                                            • 0x04 附录
                                                                                                                                                                                                                                              • 4.1 Tab 与测试函数的对应关系
                                                                                                                                                                                                                                              • 4.2 已知参数限制
                                                                                                                                                                                                                                              • 4.3 默认配置下的典型数值

                                                                                                                                                                                                                                            0x01 实现概述

                                                                                                                                                                                                                                            注:

                                                                                                                                                                                                                                            • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

                                                                                                                                                                                                                                            • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

                                                                                                                                                                                                                                            • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

                                                                                                                                                                                                                                            • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

                                                                                                                                                                                                                                            • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

                                                                                                                                                                                                                                            • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

                                                                                                                                                                                                                                            • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                                                                                                                                            • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。

                                                                                                                                                                                                                                            1.1 模块范围

                                                                                                                                                                                                                                            本 Gradio 演示覆盖 K3 Stable LatentMoE 模块的全部核心机制,对应论文 §2.3 与附录 B/C/D,共 12 个交互 Tab:

                                                                                                                                                                                                                                            #

                                                                                                                                                                                                                                            Tab 名称

                                                                                                                                                                                                                                            验证对象

                                                                                                                                                                                                                                            核心命题

                                                                                                                                                                                                                                            代码来源

                                                                                                                                                                                                                                            1

                                                                                                                                                                                                                                            原理总览

                                                                                                                                                                                                                                            架构直觉

                                                                                                                                                                                                                                            width 分离 + shared/routed 双路径 + 三处 Stable 修复

                                                                                                                                                                                                                                            plot_moe_principle.py

                                                                                                                                                                                                                                            2

                                                                                                                                                                                                                                            Demo 四联图

                                                                                                                                                                                                                                            综合演示

                                                                                                                                                                                                                                            QB 均衡 / 直方图精度 / 激活有界 / RMSNorm 稳定

                                                                                                                                                                                                                                            demo_stable_latent_moe.py

                                                                                                                                                                                                                                            3

                                                                                                                                                                                                                                            前向契约

                                                                                                                                                                                                                                            形状与 Eq.11

                                                                                                                                                                                                                                            输出形状、路由契约、独立参考实现逐点一致

                                                                                                                                                                                                                                            test_moe.py

                                                                                                                                                                                                                                            4

                                                                                                                                                                                                                                            潜空间 width 分离

                                                                                                                                                                                                                                            瓶颈维度

                                                                                                                                                                                                                                            路由专家在 l 维、共享专家在 d 维

                                                                                                                                                                                                                                            test_moe.py

                                                                                                                                                                                                                                            5

                                                                                                                                                                                                                                            RMSNorm 稳定性

                                                                                                                                                                                                                                            §2.3.1

                                                                                                                                                                                                                                            放大专家权重不改变路由分支输出尺度

                                                                                                                                                                                                                                            test_moe.py

                                                                                                                                                                                                                                            6

                                                                                                                                                                                                                                            梯度稀疏性

                                                                                                                                                                                                                                            稀疏性

                                                                                                                                                                                                                                            只有被选中的专家获得梯度

                                                                                                                                                                                                                                            test_moe.py

                                                                                                                                                                                                                                            7

                                                                                                                                                                                                                                            Dispatch 正确性

                                                                                                                                                                                                                                            分组执行

                                                                                                                                                                                                                                            grouped 与 dense 逐点一致,且置换不变

                                                                                                                                                                                                                                            test_moe.py

                                                                                                                                                                                                                                            8

                                                                                                                                                                                                                                            QB 语义

                                                                                                                                                                                                                                            §2.3.3 语义

                                                                                                                                                                                                                                            cutoff / 偏置只导流不改权重 / 权重归一化

                                                                                                                                                                                                                                            test_router_qb.py

                                                                                                                                                                                                                                            9

                                                                                                                                                                                                                                            QB 均衡效果

                                                                                                                                                                                                                                            收敛性

                                                                                                                                                                                                                                            一步改善 / 单调收敛 / 直方图精度

                                                                                                                                                                                                                                            test_router_qb.py

                                                                                                                                                                                                                                            10

                                                                                                                                                                                                                                            QB 工程行为

                                                                                                                                                                                                                                            工程约定

                                                                                                                                                                                                                                            延迟更新 / mean-centring / 推理冻结 / 开关

                                                                                                                                                                                                                                            test_router_qb.py

                                                                                                                                                                                                                                            11

                                                                                                                                                                                                                                            896 专家压力测试

                                                                                                                                                                                                                                            论文规模

                                                                                                                                                                                                                                            QB 在近千专家规模下仍一步见效

                                                                                                                                                                                                                                            test_router_qb.py

                                                                                                                                                                                                                                            12

                                                                                                                                                                                                                                            SiTU-GLU

                                                                                                                                                                                                                                            §2.3.2 / 附录 B

                                                                                                                                                                                                                                            有界 + 光滑可导 + 原点匹配 SwiGLU

                                                                                                                                                                                                                                            test_situ_glu.py

                                                                                                                                                                                                                                            1.2 实现思路

                                                                                                                                                                                                                                            复用测试层的 measure 函数,零侵入构建可视化层:

                                                                                                                                                                                                                                            1. 每个模块的测试文件都导出 measure_* 纯函数,返回结构化 dict(数值 + 布尔 + 列表),不做 assert;同时服务 pytest 单元测试和演示层可视化。

                                                                                                                                                                                                                                            2. Gradio UI 层只做"取数 -> 画图 -> 写结论文本"三件事,不重复实现任何数学逻辑,保证演示数据与测试数据同宗同源。

                                                                                                                                                                                                                                            3. 左控制 / 右显示的统一布局:每个 Tab 左侧是参数滑块 + 运行按钮,右侧是 gr.Plot + gr.Textbox(结论)。点击"运行"后,滑块参数传入 tab_* 函数,调用对应的 measure_* 或 plot 脚本,返回 (fig, text)。

                                                                                                                                                                                                                                            4. before / after 对比:每个创新组件都有标准基线对照——

                                                                                                                                                                                                                                              • LatentMoE vs 全宽 MoE(Tab 1/4)

                                                                                                                                                                                                                                              • 有 RMSNorm vs 无 RMSNorm(Tab 5)

                                                                                                                                                                                                                                              • SiTU-GLU vs SwiGLU(Tab 12)

                                                                                                                                                                                                                                              • QB 前 vs QB 后(Tab 9/11)

                                                                                                                                                                                                                                              • grouped dispatch vs dense 评估(Tab 7)

                                                                                                                                                                                                                                              • histogram 近似 vs exact 分位数(Tab 9)

                                                                                                                                                                                                                                            1.3 运行方式

                                                                                                                                                                                                                                              cd Model-Viz/experiments/models/llm/kimi_k3/modules/moe


                                                                                                                                                                                                                                              # 方式 1:完整交互式演示(12 个 Tab)
                                                                                                                                                                                                                                              python gradio_moe_demo.py


                                                                                                                                                                                                                                              # 方式 2:单出图脚本(独立运行)
                                                                                                                                                                                                                                              python plot_moe_principle.py
                                                                                                                                                                                                                                              python demo_stable_latent_moe.py

                                                                                                                                                                                                                                              所有 Tab 均在 CPU 上实时计算,默认 2~4 线程,无需 GPU。


                                                                                                                                                                                                                                              0x02 核心数学

                                                                                                                                                                                                                                              2.1 总体公式

                                                                                                                                                                                                                                              Stable LatentMoE 的核心定义(论文 Eq. 11):

                                                                                                                                                                                                                                                # ===== 输入输出维度 =====
                                                                                                                                                                                                                                                #   x in R^{b x t x d}          # 输入 token 序列 (batch, seq_len, model_dim)
                                                                                                                                                                                                                                                #   y in R^{b x t x d}          # 输出(与输入同形)


                                                                                                                                                                                                                                                # ===== 路由决策 (QuantileBalancingRouter, Eq.13 / §2.3.3) =====
                                                                                                                                                                                                                                                #   s_i  = sigmoid(W_r . x_i)                            # 每个 token 的 per-expert 原始分数
                                                                                                                                                                                                                                                #   T_i  = topk(s_i + b, k)                              # Top-k 选中集, 偏置 b 只参与选择
                                                                                                                                                                                                                                                #   p_ij = s_ij / sum_{r in T_i} s_ir                    # 混合权重(不含偏置, Eq.13 的权重)
                                                                                                                                                                                                                                                #   a_i  = topk(s_i + b, k+1)[k]                         # cutoff = 第 k+1 个 biased score


                                                                                                                                                                                                                                                # ===== 潜空间路由分支 (width 分离, Eq.11 第一项) =====
                                                                                                                                                                                                                                                #   z_i = W_down . x_i                                    # W_down: d -> l, 降维到潜空间
                                                                                                                                                                                                                                                #   u_i = Σ_{j in T_i} p_ij . E_j^routed(z_i)             # E_j: SiTU-GLU(l, H, l), 在 l 维工作
                                                                                                                                                                                                                                                #   u_i = RMSNorm(u_i)                                    # §2.3.1 稳定化
                                                                                                                                                                                                                                                #   y_routed_i = W_up . u_i                               # W_up: l -> d, 升维回模型空间


                                                                                                                                                                                                                                                # ===== 共享分支 (全宽, Eq.11 第二项) =====
                                                                                                                                                                                                                                                #   y_shared_i = Σ_j E_j^shared(x_i)                      # E_j: SiTU-GLU(d, H, d), 在 d 维工作


                                                                                                                                                                                                                                                # ===== 最终输出 (Eq. 11) =====
                                                                                                                                                                                                                                                #   y_i = y_shared_i + y_routed_i                         # 残差式合并: 共享基底 + 路由增强


                                                                                                                                                                                                                                                # ===== SiTU-GLU 激活 (Eq.12 / 附录 B) =====
                                                                                                                                                                                                                                                #   softcap(z, β) = β . tanh(z / β)                      # 光滑软截断, |·| ≤ β
                                                                                                                                                                                                                                                #   SiTU-GLU(g, u; β_g, β_u)
                                                                                                                                                                                                                                                #     = softcap(g, β_g) . sigmoid(g) . softcap(u, β_u)    # 门分支(有界 Swish)× up 分支(有界线性)
                                                                                                                                                                                                                                                #     且 |SiTU-GLU| ≤ β_g . β_u                           # 全局有界


                                                                                                                                                                                                                                                # ===== Quantile Balancing 更新 (Eq.14 / 附录 C-D) =====
                                                                                                                                                                                                                                                #   r_ij   = a_i - s_ij                                   # 把专家 j 推到 cutoff 所需偏置
                                                                                                                                                                                                                                                #   b_hat_j = quantile(r_·j, k/n)                        # 第 k/n 分位 = 刚好让 q 个 token 越 cutoff
                                                                                                                                                                                                                                                #   b_j    = b_hat_j - mean(b_hat)                       # mean-centring, sum(b) = 0
                                                                                                                                                                                                                                                 

                                                                                                                                                                                                                                                关键洞察:Stable LatentMoE 的三处「Stable」修复——RMSNorm 去尺度敏感性、SiTU-GLU 去激活离群、Quantile Balancing 去负载失衡——每一处都对应一个独立的数值失稳模式,合起来才让 896 专家 × 16 激活的极端稀疏配置在 2.8T 规模上可训练。少任何一处,病态链都会在某个尺度上爆炸。

                                                                                                                                                                                                                                                ”

                                                                                                                                                                                                                                                2.2 子机制分解

                                                                                                                                                                                                                                                2.2.1 Width 分离(Latent Bottleneck)

                                                                                                                                                                                                                                                公式:

                                                                                                                                                                                                                                                  routed 参数 = E_routed × (2·l·H + H·l) = 3·E_routed·l·H    # 在 l 维工作
                                                                                                                                                                                                                                                  shared 参数 = E_shared × (2·d·H + H·d) = 3·E_shared·d·H    # 在 d 维工作
                                                                                                                                                                                                                                                  投影参数   = 2·d·l                                          # W_down + W_up
                                                                                                                                                                                                                                                  每 token FLOPs = E_shared·3dH + top_k·3lH + 2dl            # 只激活 top_k 个路由专家

                                                                                                                                                                                                                                                  直觉解释:把路由专家塞进更窄的潜空间,让「专家数量多」与「每个专家便宜」解耦——896 个专家听起来很夸张,但每个只在 3584 维而非 4096 维工作,叠加 top_k=16 的稀疏性,实际计算量远低于全宽稠密。

                                                                                                                                                                                                                                                  关键性质:

                                                                                                                                                                                                                                                  • 参数量节省 ≈ (1 - l/d) × 路由分支占比(K3 约 12.4% 参数、6.8% FLOPs)

                                                                                                                                                                                                                                                  • 稀疏度 = n_routed / top_k(K3 = 56)

                                                                                                                                                                                                                                                  • shared 路径始终稠密、始终有梯度,是训练的稳定基底

                                                                                                                                                                                                                                                  2.2.2 RMSNorm 稳定化(§2.3.1)

                                                                                                                                                                                                                                                  公式:

                                                                                                                                                                                                                                                    u' = RMSNorm(u) = u / RMS(u) × γ          # γ 为可学习增益
                                                                                                                                                                                                                                                    y  = W_up · u'

                                                                                                                                                                                                                                                    直觉解释:路由分支近似串了 4 个矩阵乘(W_down → 专家 FFN 两步 → W_up),这是一条病态链——专家权重的幅度、选了哪些专家、权重分配如何,都会放大成输出尺度的波动。RMSNorm 在聚合之后、上投影之前把尺度归一化,让下游永远接到单位 RMS 的信号。

                                                                                                                                                                                                                                                    关键性质:

                                                                                                                                                                                                                                                    • 尺度不敏感:experts.down 权重放大 k 倍,RMSNorm 输出不变(Tab 5 验证 ratio ≈ 1.0)

                                                                                                                                                                                                                                                    • 非可选:论文指出它本身也改善验证损失

                                                                                                                                                                                                                                                    • 与 shared 路径无关:shared 是全宽 SiTU-GLU,本身已经尺度可控

                                                                                                                                                                                                                                                    2.2.3 SiTU-GLU 有界激活(§2.3.2 / 附录 B)

                                                                                                                                                                                                                                                    公式:

                                                                                                                                                                                                                                                      softcap(z, β) = β · tanh(z/β)             # 光滑截断, |z|→∞ 时 → ±β
                                                                                                                                                                                                                                                      SiTU-GLU(g, u) = softcap(g, β_g) · σ(g) · softcap(u, β_u)

                                                                                                                                                                                                                                                      直觉解释:SwiGLU 的 gate × up 两个无界因子相乘,MoE 宽度又大,低精度下偶尔会撞上「两个坐标都很大」的巧合,产生离群点溢出 FP8。SiTU-GLU 给两边都套 softcap,乘积天然不超过 (K3 取 4×25=100,小于 FP8 E4M3 上限 448)。

                                                                                                                                                                                                                                                      关键性质:

                                                                                                                                                                                                                                                      • 全局有界:|SiTU-GLU| ≤ β_g·β_u(Tab 12 验证,输入再大也不超过上界)

                                                                                                                                                                                                                                                      • 原点匹配 SwiGLU:tanh(z) ≈ z - z³/(3β²),小输入下与 SwiGLU 一阶一致

                                                                                                                                                                                                                                                      • 光滑可导:softcap 用 tanh 而非硬 clamp,饱和区仍有 tanh' > 0 的梯度

                                                                                                                                                                                                                                                      • 负尾部归零:σ(g) 让负输入趋近 0,保留 Swish 的稀疏性

                                                                                                                                                                                                                                                      2.2.4 Quantile Balancing(§2.3.3 / 附录 C-D)

                                                                                                                                                                                                                                                      公式:

                                                                                                                                                                                                                                                        目标负载 q = m·k / n                      # m tokens 每 token 选 k 个, 均分到 n 专家
                                                                                                                                                                                                                                                        r_ij     = a_i - s_ij                    # 专家 j 达到 token i cutoff 所需偏置
                                                                                                                                                                                                                                                        b_hat_j  = quantile(r_·j, k/n)           # 第 q 个 required 值 = 刚好让 q 个 token 越 cutoff
                                                                                                                                                                                                                                                        b_j      = b_hat_j - mean(b_hat)         # mean-centring, sum(b) = 0

                                                                                                                                                                                                                                                        直觉解释:传统的「b ← b + γ·sign(target - load)」像用固定步长爬山,步长是超参,收敛慢。QB 换个角度想:既然 cutoff 固定,「要让专家 j 恰好吃到 q 个 token」等价于找一个偏置值,使得刚好有 q 个 token 的 s_ij + b_j ≥ a_i。这个值就是 required 的第 q 个分位数——一步到位,无需学习率。

                                                                                                                                                                                                                                                        关键性质:

                                                                                                                                                                                                                                                        • 一步收敛:单次 update_bias 就能把几十倍的失衡压到 2 倍以内(Tab 9 验证 51x → 1.95x)

                                                                                                                                                                                                                                                        • 单调收敛:迭代步数越多越均衡(Tab 9 验证)

                                                                                                                                                                                                                                                        • 无损失偏置:偏置只进 Top-k 选择、不进权重归一化,不扭曲路由器优化

                                                                                                                                                                                                                                                        • 直方图近似:大规模下用分箱直方图估分位数,误差 ≤ 1 个 bin 宽(Tab 9 验证 0.43 bin)

                                                                                                                                                                                                                                                        • 延迟更新:本批从不用本批算出的偏置路由自己,避免统计自洽性问题

                                                                                                                                                                                                                                                        • mean-centring 不动点:整体平移偏置不改变路由选择(Tab 10 验证)


                                                                                                                                                                                                                                                        0x03 每个 Tab 的详细说明

                                                                                                                                                                                                                                                        Tab 1:原理总览

                                                                                                                                                                                                                                                        目的

                                                                                                                                                                                                                                                        展示 Stable LatentMoE 的架构全景——数据流、width 分离节省的参数量/FLOPs、稀疏度与计算量的关系、以及层调度方式。建立整体直觉,为后续 11 个细节 Tab 做铺垫。

                                                                                                                                                                                                                                                        验证的是论文 §2.3 开篇的架构描述(Eqs. 11-14 的整体图景),不做数值断言,属于「一图看懂」级别的总览。

                                                                                                                                                                                                                                                        UI 组件与参数影响

                                                                                                                                                                                                                                                        参数

                                                                                                                                                                                                                                                        范围

                                                                                                                                                                                                                                                        默认

                                                                                                                                                                                                                                                        调节效果

                                                                                                                                                                                                                                                        -

                                                                                                                                                                                                                                                        -

                                                                                                                                                                                                                                                        -

                                                                                                                                                                                                                                                        无参数,点击按钮直接运行

                                                                                                                                                                                                                                                        此 Tab 无交互参数,固定使用 K3 报告的 2.8T 配置(d=4096, l=3584, H=3072, E=896, k=16, n_shared=2)。

                                                                                                                                                                                                                                                        输出图解读

                                                                                                                                                                                                                                                        tab-1
                                                                                                                                                                                                                                                        tab-1

                                                                                                                                                                                                                                                        2×2 四联图布局。

                                                                                                                                                                                                                                                        左上 (a):架构数据流图

                                                                                                                                                                                                                                                        • 图类型:方块箭头示意图

                                                                                                                                                                                                                                                        • 含义:展示 token x (d 维) 分流到两条路径——上支路为 shared experts(全宽 SiTU-GLU,n_shared=2),下支路为 W_down 降维 → routed experts(Top-k 路由 + SiTU-GLU,896 专家/激活 16/稀疏度 56) → RMSNorm(latent) → W_up 升维;两路最后在 d 维相加得到 y

                                                                                                                                                                                                                                                        • 颜色:蓝色=输入输出,橙色=投影,红色=路由分支,绿色=共享分支,紫色=RMSNorm

                                                                                                                                                                                                                                                        • 你该看什么:确认 width 分离的物理位置(W_down 之后才进入 routed experts)、三处 Stable 修复各自对应哪个环节

                                                                                                                                                                                                                                                        • 理想情况:图结构与 Eq. 11 逐字对应

                                                                                                                                                                                                                                                        • 异常指示:如果缺少 RMSNorm 模块,说明 rmsnorm_before_up 配置被关闭

                                                                                                                                                                                                                                                        右上 (b):width 分离参数量 / 计算量节省

                                                                                                                                                                                                                                                        • 图类型:分组柱状图

                                                                                                                                                                                                                                                        • X 轴:参数 (B)、每 token FLOPs (M)

                                                                                                                                                                                                                                                        • Y 轴:绝对数量(线性)

                                                                                                                                                                                                                                                        • 颜色:红色 = LatentMoE,灰色 = 全宽 MoE(基线)

                                                                                                                                                                                                                                                        • 你该看什么:对比红色柱与灰色柱的高度差,体会潜空间 + 稀疏的累计节省

                                                                                                                                                                                                                                                        • 理想情况:LatentMoE 的两柱都显著低于全宽基线(参数节省 ~12.4%,FLOPs 节省 ~6.8%)

                                                                                                                                                                                                                                                        • 异常指示:如果两柱等高,说明 l=d(width 分离未生效)

                                                                                                                                                                                                                                                        左下 (c):稀疏度 vs 计算量占比

                                                                                                                                                                                                                                                        • 图类型:双折线图,X 轴对数刻度

                                                                                                                                                                                                                                                        • X 轴:稀疏度 (n_routed / top_k),log scale

                                                                                                                                                                                                                                                        • Y 轴:占全宽 MoE 的比例 (%),线性

                                                                                                                                                                                                                                                        • 颜色:红色实线 = FLOPs,紫色虚线 = 参数;橙色竖线 = K3 配置(稀疏度=56)

                                                                                                                                                                                                                                                        • 你该看什么:随着稀疏度升高(top_k 减少),FLOPs 和参数量占比如何单调下降;K3 配置(56)在曲线的哪个位置

                                                                                                                                                                                                                                                        • 理想情况:两条曲线均单调递减,稀疏度越大越省

                                                                                                                                                                                                                                                        • 异常指示:若曲线呈平台或上升,说明稀疏度公式有误

                                                                                                                                                                                                                                                        右下 (d):K3 层调度(dense warm-up + MoE body)

                                                                                                                                                                                                                                                        • 图类型:堆叠柱状图

                                                                                                                                                                                                                                                        • X 轴:层编号(0~92)

                                                                                                                                                                                                                                                        • Y 轴:层类型激活状态(0/1)

                                                                                                                                                                                                                                                        • 颜色:蓝色 = DenseFFN(前 2 层 warm-up),红色 = StableLatentMoE(后续 91 层主体)

                                                                                                                                                                                                                                                        • 你该看什么:前 n_dense_layers=2 层是全宽稠密 FFN,过渡到 MoE 主体

                                                                                                                                                                                                                                                        • 理想情况:第 0-1 层为蓝色(稠密),第 2-92 层为红色(MoE)

                                                                                                                                                                                                                                                        • 异常指示:若所有层都是同色,说明层调度配置错误

                                                                                                                                                                                                                                                        为什么重要

                                                                                                                                                                                                                                                        此 Tab 是整个演示的导航图——读者对 LatentMoE 的整体直觉都从这里建立。后续 11 个 Tab 的细节验证,都需要回溯到这张全景图来定位:width 分离在哪、RMSNorm 在哪、QB 在哪、SiTU-GLU 在哪。没有这张图,读者看到后面的数值验证会缺乏上下文。


                                                                                                                                                                                                                                                        Tab 2:Demo 四联图

                                                                                                                                                                                                                                                        目的

                                                                                                                                                                                                                                                        用最小的配置一次性展示 Stable LatentMoE 的四个标志性效果:QB 负载均衡前后对比、直方图分位数估计精度、SiTU-GLU 有界性 vs SwiGLU 发散、RMSNorm 的尺度不敏感性。这是整个模块的「快速概览」四联图,对应 demo_stable_latent_moe.py 的默认演示。

                                                                                                                                                                                                                                                        验证的是论文 §2.3 的四个核心论断(§2.3.1 RMSNorm、§2.3.2 SiTU-GLU、§2.3.3 QB)在同一微型配置下的综合表现。

                                                                                                                                                                                                                                                        UI 组件与参数影响

                                                                                                                                                                                                                                                        参数

                                                                                                                                                                                                                                                        范围

                                                                                                                                                                                                                                                        默认

                                                                                                                                                                                                                                                        调节效果

                                                                                                                                                                                                                                                        n_experts

                                                                                                                                                                                                                                                        4-64

                                                                                                                                                                                                                                                        8

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 专家更多,初始失衡更严重,QB 改善幅度可能更大

                                                                                                                                                                                                                                                        top_k

                                                                                                                                                                                                                                                        1-8

                                                                                                                                                                                                                                                        2

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 每 token 选更多专家,稀疏度下降,负载更天然均匀

                                                                                                                                                                                                                                                        n_batches

                                                                                                                                                                                                                                                        10-100

                                                                                                                                                                                                                                                        40

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 统计样本更多,直方图估计更精确,误差更小

                                                                                                                                                                                                                                                        batch

                                                                                                                                                                                                                                                        100-1000

                                                                                                                                                                                                                                                        200

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 同 n_batches,样本量增加

                                                                                                                                                                                                                                                        bins

                                                                                                                                                                                                                                                        128-1024

                                                                                                                                                                                                                                                        256

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 直方图分箱更细,分位数估计误差更小(以内存为代价)

                                                                                                                                                                                                                                                        hot_experts

                                                                                                                                                                                                                                                        字符串

                                                                                                                                                                                                                                                        "0,1"

                                                                                                                                                                                                                                                        调整热门专家 id(逗号分隔),决定初始失衡的来源

                                                                                                                                                                                                                                                        hot_experts 对应的专家权重行被放大 6 倍,使其天然获得更多路由;这些专家就是 QB 要降温的对象。

                                                                                                                                                                                                                                                         

                                                                                                                                                                                                                                                        注意:子图 (c)(d)(SiTU-GLU 曲线 / RMSNorm 缩放)使用固定的内部配置,不响应 n_experts / top_k / hot_experts 等路由参数的调节;这两个子图展示的是激活函数与归一化本身的性质。

                                                                                                                                                                                                                                                        ”

                                                                                                                                                                                                                                                        输出图解读

                                                                                                                                                                                                                                                        tab-2
                                                                                                                                                                                                                                                        tab-2

                                                                                                                                                                                                                                                        2×2 四联图布局。

                                                                                                                                                                                                                                                        左上 (a):Quantile Balancing 前后负载

                                                                                                                                                                                                                                                        • 图类型:分组柱状图

                                                                                                                                                                                                                                                        • X 轴:expert id(0 到 n_experts-1)

                                                                                                                                                                                                                                                        • Y 轴:token 被路由次数

                                                                                                                                                                                                                                                        • 颜色:蓝色 = before QB,橙色 = after QB

                                                                                                                                                                                                                                                        • 你该看什么:before 中热门专家(如 0、1)的柱子明显高于其他专家;after 后所有柱子高度接近一致

                                                                                                                                                                                                                                                        • 理想情况:after 的 max/min ratio ≈ 1.5 左右(默认配置下从 ~3.7 降到 ~1.5)

                                                                                                                                                                                                                                                        • 异常指示:after 仍有专家柱子显著高于其他 → QB 未生效或样本不足

                                                                                                                                                                                                                                                        右上 (b):分位数估计 exact vs histogram

                                                                                                                                                                                                                                                        • 图类型:双折线对比图

                                                                                                                                                                                                                                                        • X 轴:expert id

                                                                                                                                                                                                                                                        • Y 轴:偏置值 b

                                                                                                                                                                                                                                                        • 颜色/线型:蓝色实线圆点 = exact 分位数(torch.quantile 真值),橙色虚线方块 = histogram 估计

                                                                                                                                                                                                                                                        • 你该看什么:两条线几乎重合,说明直方图近似的精度损失很小

                                                                                                                                                                                                                                                        • 理想情况:max diff < 0.01(默认 256 bins 下约 0.003),且 diff 以 bin 宽计 < 1.5

                                                                                                                                                                                                                                                        • 异常指示:两条线明显分叉 → 直方图实现有 bug 或 bins 太少

                                                                                                                                                                                                                                                        左下 (c):SwiGLU vs SiTU-GLU 激活幅值

                                                                                                                                                                                                                                                        • 图类型:双折线图,X 轴对数刻度

                                                                                                                                                                                                                                                        • X 轴:输入 scale(0.5 → 8),log scale

                                                                                                                                                                                                                                                        • Y 轴:max|activation|(线性)

                                                                                                                                                                                                                                                        • 颜色:蓝色 = SwiGLU(无界),橙色 = SiTU-GLU(有界);红色虚线 = 上界 beta_g·beta_u = 100

                                                                                                                                                                                                                                                        • 你该看什么:SwiGLU 随输入 scale 增长而单调上升(发散),SiTU-GLU 很快就趋于平稳(被钳住)

                                                                                                                                                                                                                                                        • 理想情况:SiTU-GLU 的曲线在上界附近水平,SwiGLU 持续上升

                                                                                                                                                                                                                                                        • 异常指示:SiTU-GLU 也随 scale 增长 → softcap 未生效

                                                                                                                                                                                                                                                        右下 (d):RMSNorm 尺度不敏感性

                                                                                                                                                                                                                                                        • 图类型:双折线图

                                                                                                                                                                                                                                                        • X 轴:down 权放大倍数(1 → 50)

                                                                                                                                                                                                                                                        • Y 轴:输出幅值比 (放大/原始)

                                                                                                                                                                                                                                                        • 颜色:蓝色 = 无 latent_norm(随 factor 线性增长),橙色 = 有 latent_norm(保持 ≈1.0)

                                                                                                                                                                                                                                                        • 你该看什么:有 RMSNorm 的线几乎水平(在 1.0 附近),无 RMSNorm 的线 45 度上升

                                                                                                                                                                                                                                                        • 理想情况:有 norm 的比值 ≈ 1.0(误差 < 1e-3),无 norm 的比值 ≈ factor

                                                                                                                                                                                                                                                        • 异常指示:两条线都接近 1 → 权重放大未生效;两条线都增长 → RMSNorm 被关闭

                                                                                                                                                                                                                                                        调节建议

                                                                                                                                                                                                                                                        • 想看「QB 改善更夸张」→ 调 n_experts 到 32、hot_experts 到 "0,1,2,3"

                                                                                                                                                                                                                                                        • 想看「直方图估计更精确」→ 调 bins 到 1024、n_batches 到 100

                                                                                                                                                                                                                                                        • 想看「SwiGLU 完全爆炸」→ 此 Tab 内置 scale 上限为 8,想看更大 scale 请去 Tab 12

                                                                                                                                                                                                                                                        为什么重要

                                                                                                                                                                                                                                                        这是读者接触模块的第一个综合印象——四个子图各代表一处核心创新,看完这 Tab 就知道 LatentMoE 到底解决了哪四个问题、每个问题的效果量级有多大。它是后续深入 Tab 的钩子和索引。


                                                                                                                                                                                                                                                        Tab 3:前向契约

                                                                                                                                                                                                                                                        目的

                                                                                                                                                                                                                                                        验证 StableLatentMoE 层的前向输出契约:形状正确、路由结构存在、与独立 Eq.11 参考实现逐点一致、梯度只流向被选中专家。这是模块实现正确性的主锚点——所有其他性质的验证都建立在前向算对了的基础上。

                                                                                                                                                                                                                                                        对应测试 est_forward_shape_and_routing / est_matches_an_independent_eq11_reference / est_only_selected_experts_receive_gradient。

                                                                                                                                                                                                                                                        UI 组件与参数影响

                                                                                                                                                                                                                                                        参数

                                                                                                                                                                                                                                                        范围

                                                                                                                                                                                                                                                        默认

                                                                                                                                                                                                                                                        调节效果

                                                                                                                                                                                                                                                        dim

                                                                                                                                                                                                                                                        8-128

                                                                                                                                                                                                                                                        32

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 模型维度更大,输出尺寸成比例变化

                                                                                                                                                                                                                                                        batch

                                                                                                                                                                                                                                                        1-8

                                                                                                                                                                                                                                                        3

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 输出 batch 维变大,总 token 数 = batch×seq

                                                                                                                                                                                                                                                        seq_len

                                                                                                                                                                                                                                                        2-16

                                                                                                                                                                                                                                                        6

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 序列更长,总 token 数增多

                                                                                                                                                                                                                                                        seed

                                                                                                                                                                                                                                                        0-10

                                                                                                                                                                                                                                                        0

                                                                                                                                                                                                                                                        随机种子,改变具体权重和输入,但不影响性质结论

                                                                                                                                                                                                                                                        输出图解读

                                                                                                                                                                                                                                                        tab-3
                                                                                                                                                                                                                                                        tab-3

                                                                                                                                                                                                                                                        1×3 三联图布局。

                                                                                                                                                                                                                                                        左 (a):前向形状检查

                                                                                                                                                                                                                                                        • 图类型:柱状图

                                                                                                                                                                                                                                                        • X 轴:hidden_dim、n_indices、n_tokens

                                                                                                                                                                                                                                                        • Y 轴:数值

                                                                                                                                                                                                                                                        • 颜色:蓝/橙/绿三色柱

                                                                                                                                                                                                                                                        • 你该看什么:hidden_dim 应等于 dim(32),n_indices 应等于 batch×seq×top_k(18 = 3×6×2 中的前两个维度乘 top_k),n_tokens 等于 batch×seq

                                                                                                                                                                                                                                                        • 理想情况:hidden_shape = (batch, seq, dim),indices_shape = (batch*seq, top_k)

                                                                                                                                                                                                                                                        • 异常指示:hidden_dim ≠ dim → 投影层维度错;indices 形状不对 → top_k 或 flatten 逻辑错

                                                                                                                                                                                                                                                        中 (b):Eq.11 参考实现 vs MoE 对拍

                                                                                                                                                                                                                                                        eq-11
                                                                                                                                                                                                                                                        eq-11
                                                                                                                                                                                                                                                        • 图类型:柱状图(两个误差指标)

                                                                                                                                                                                                                                                        • X 轴:max_abs_diff、mean_abs_diff

                                                                                                                                                                                                                                                        • Y 轴:绝对误差

                                                                                                                                                                                                                                                        • 颜色:红/橙

                                                                                                                                                                                                                                                        • 你该看什么:两个柱子都几乎贴地(接近 0),说明模块输出与独立手写的 Eq.11 参考实现逐点一致

                                                                                                                                                                                                                                                        • 理想情况:max_abs_diff < 1e-5,mean_abs_diff < 1e-6

                                                                                                                                                                                                                                                        • 异常指示:柱子明显升高(> 1e-3)→ 模块实现与公式有偏差,可能是 SiTU-GLU 参数用错、加权方式反了、或共享专家漏加

                                                                                                                                                                                                                                                        右 (c):梯度稀疏性检查

                                                                                                                                                                                                                                                        • 图类型:柱状图

                                                                                                                                                                                                                                                        • X 轴:touched_experts(有梯度的专家数)、n_routed(总路由专家数)

                                                                                                                                                                                                                                                        • Y 轴:count

                                                                                                                                                                                                                                                        • 颜色:绿/蓝

                                                                                                                                                                                                                                                        • 你该看什么:touched_experts 应小于 n_routed(因为 top_k=1,只有被选中的那些专家有梯度),且 touched 是 used 的子集

                                                                                                                                                                                                                                                        • 理想情况:touched < n_routed,且 touched_subset_of_used = True

                                                                                                                                                                                                                                                        • 异常指示:touched == n_routed → 所有专家都有梯度,说明 dispatch 走了 dense 路径而非稀疏路径

                                                                                                                                                                                                                                                        为什么重要

                                                                                                                                                                                                                                                        这是实现正确性的底线验证。如果前向契约不成立——形状错了、输出与公式对不上、梯度不稀疏——后续所有性质验证都没有意义。此 Tab 是整个演示的信任锚点,建议每次改动代码后先跑它确认基础正确。


                                                                                                                                                                                                                                                        Tab 4:潜空间 width 分离

                                                                                                                                                                                                                                                        目的

                                                                                                                                                                                                                                                        直观展示 LatentMoE 的核心结构特征——路由专家工作在潜空间 l 维,共享专家工作在全宽 d 维(width 分离)。验证的是论文 §2.3 开篇的 width separation 定义(Eq. 11 的 W_down 投影)。

                                                                                                                                                                                                                                                        对应测试 est_latent_bottleneck_is_where_routed_experts_live。

                                                                                                                                                                                                                                                        背景概念

                                                                                                                                                                                                                                                        Width 分离:常规 MoE 中所有专家都是全宽(d 维)的,专家越多参数量和计算量线性放大。LatentMoE 在路由专家前加一个 W_down 投影,把 token 从 d 维降到 l 维(l < d),路由专家全部在 l 维工作,最后 W_up 再升回 d 维。这样路由专家的参数和计算量都从 d 级降到 l 级,K3 中 l=3584、d=4096,约节省 12.4% 的专家侧参数。

                                                                                                                                                                                                                                                        代码位置:moe.py:StableLatentMoE.__init__ 中的 down_proj(d→l)、experts(l→H→l)、up_proj(l→d)。

                                                                                                                                                                                                                                                        UI 组件与参数影响

                                                                                                                                                                                                                                                        参数

                                                                                                                                                                                                                                                        范围

                                                                                                                                                                                                                                                        默认

                                                                                                                                                                                                                                                        调节效果

                                                                                                                                                                                                                                                        dim (d)

                                                                                                                                                                                                                                                        16-512

                                                                                                                                                                                                                                                        64

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 全宽维度变大,shared_gate_in_features 随之变大,width 节省比例上升

                                                                                                                                                                                                                                                        latent_dim (l)

                                                                                                                                                                                                                                                        8-256

                                                                                                                                                                                                                                                        16

                                                                                                                                                                                                                                                        显示值不变(当前实现使用小配置 latent_dim=16 固定值,此滑块暂未接入)

                                                                                                                                                                                                                                                        n_routed

                                                                                                                                                                                                                                                        2-64

                                                                                                                                                                                                                                                        8

                                                                                                                                                                                                                                                        显示值不变(同上,固定为 8)

                                                                                                                                                                                                                                                        n_shared

                                                                                                                                                                                                                                                        1-8

                                                                                                                                                                                                                                                        2

                                                                                                                                                                                                                                                        显示值不变(同上,固定为 2)

                                                                                                                                                                                                                                                        expert_hidden

                                                                                                                                                                                                                                                        8-128

                                                                                                                                                                                                                                                        24

                                                                                                                                                                                                                                                        显示值不变(同上,固定为 24)

                                                                                                                                                                                                                                                         

                                                                                                                                                                                                                                                        注意:此 Tab 的 latent_dim / n_routed / n_shared / expert_hidden 四个滑块当前仅为占位,底层 measure_latent_bottleneck_dimensions 函数只接收 dim 参数,内部使用固定的 small_cfg() 配置(latent_dim=16, n_routed=8, n_shared=2, expert_hidden=24)。只有 dim 滑块真正影响输出。

                                                                                                                                                                                                                                                        ”

                                                                                                                                                                                                                                                        输出图解读

                                                                                                                                                                                                                                                        tab-4
                                                                                                                                                                                                                                                        tab-4

                                                                                                                                                                                                                                                        1×2 双联图布局。

                                                                                                                                                                                                                                                        左 (a):维度对比

                                                                                                                                                                                                                                                        • 图类型:柱状图

                                                                                                                                                                                                                                                        • X 轴:experts_dim(路由专家门控输入维)、down_dim(路由专家降维输出维)、shared_in(共享专家门控输入维)

                                                                                                                                                                                                                                                        • Y 轴:特征维度

                                                                                                                                                                                                                                                        • 颜色:红/绿/蓝

                                                                                                                                                                                                                                                        • 你该看什么:experts_dim 和 down_dim 应该远小于 shared_in——路由专家在窄的潜空间(l=16)工作,共享专家在宽的全空间(d=64)工作

                                                                                                                                                                                                                                                        • 理想情况:experts_dim = latent_dim(16),shared_in = dim(64),节省比例 = (1 - 16/64) = 75%

                                                                                                                                                                                                                                                        • 异常指示:experts_dim == shared_in → 没有 width 分离(l=d),路由专家与共享专家宽度相同

                                                                                                                                                                                                                                                        右 (b):专家数量

                                                                                                                                                                                                                                                        • 图类型:柱状图

                                                                                                                                                                                                                                                        • X 轴:n_routed(路由专家数)、n_shared(共享专家数)

                                                                                                                                                                                                                                                        • Y 轴:count

                                                                                                                                                                                                                                                        • 颜色:红/绿

                                                                                                                                                                                                                                                        • 你该看什么:路由专家远多于共享专家(K3 是 896 vs 2;小配置是 8 vs 2)

                                                                                                                                                                                                                                                        • 理想情况:n_routed > n_shared

                                                                                                                                                                                                                                                        • 异常指示:n_routed == 0 → 没有路由专家,退化为纯共享 FFN

                                                                                                                                                                                                                                                        为什么重要

                                                                                                                                                                                                                                                        Width 分离是 LatentMoE 的灵魂——没有它,896 个专家的参数和计算量会爆炸到不可接受。此 Tab 把「路由专家在窄带、共享专家在宽带」这件事用柱状图直观展示出来,是理解 K3 为什么能支撑近千专家的第一个关键点。


                                                                                                                                                                                                                                                        Tab 5:RMSNorm 稳定性

                                                                                                                                                                                                                                                        目的

                                                                                                                                                                                                                                                        验证 §2.3.1 的核心论断——在 up-projection 前加 RMSNorm 可以消除路由分支的尺度敏感性:放大专家权重若干倍,有 RMSNorm 的输出几乎不变,无 RMSNorm 的输出随之线性放大。

                                                                                                                                                                                                                                                        对应测试 est_rmsnorm_before_up_projection_removes_scale_sensitivity。

                                                                                                                                                                                                                                                        背景概念

                                                                                                                                                                                                                                                        病态链问题:LatentMoE 的路由分支把 W_down → 专家 FFN(两步 matmul)→ 加权聚合 → W_up 串成近似 4 个连续矩阵乘。在 2.8T 规模下,这条链的条件数很差——专家权重的幅度、选了哪些专家、权重如何分配,都会放大成输出尺度的波动。RMSNorm 在聚合之后、上投影之前做归一化(u / RMS(u)),把输出尺度固定下来,下游永远接到单位 RMS 的信号。

                                                                                                                                                                                                                                                        UI 组件与参数影响

                                                                                                                                                                                                                                                        参数

                                                                                                                                                                                                                                                        范围

                                                                                                                                                                                                                                                        默认

                                                                                                                                                                                                                                                        调节效果

                                                                                                                                                                                                                                                        dim

                                                                                                                                                                                                                                                        8-128

                                                                                                                                                                                                                                                        32

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 维度更大,但比例关系不变(比值应仍接近 1.0 / factor)

                                                                                                                                                                                                                                                        down 权重放大倍数

                                                                                                                                                                                                                                                        2-100

                                                                                                                                                                                                                                                        50

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 无 RMSNorm 的输出比值线性增大;有 RMSNorm 的仍保持 ≈1.0

                                                                                                                                                                                                                                                        seed

                                                                                                                                                                                                                                                        0-10

                                                                                                                                                                                                                                                        0

                                                                                                                                                                                                                                                        随机种子,不影响性质结论

                                                                                                                                                                                                                                                        输出图解读

                                                                                                                                                                                                                                                        tab-5
                                                                                                                                                                                                                                                        tab-5

                                                                                                                                                                                                                                                        单图布局(1 个柱状图)。

                                                                                                                                                                                                                                                        中心图:RMSNorm 尺度敏感性

                                                                                                                                                                                                                                                        • 图类型:双柱状图

                                                                                                                                                                                                                                                        • X 轴:有 RMSNorm (ratio)、无 RMSNorm (ratio)

                                                                                                                                                                                                                                                        • Y 轴:output ratio(放大后幅值 / 原始幅值)

                                                                                                                                                                                                                                                        • 颜色:绿色 = 有 RMSNorm,红色 = 无 RMSNorm;灰色虚线 = 理想值 1.0

                                                                                                                                                                                                                                                        • 你该看什么:绿色柱子几乎贴在 1.0 线上(有 RMSNorm 放大 50 倍后输出几乎不变),红色柱子远超 1.0(接近 50)

                                                                                                                                                                                                                                                        • 理想情况:ratio_with_norm ≈ 1.0(误差 < 1e-3),ratio_no_norm ≈ factor(50 左右)

                                                                                                                                                                                                                                                        • 异常指示:两根柱子都接近 1.0 → 权重放大未生效;两根柱子都接近 50 → RMSNorm 被关闭或失效

                                                                                                                                                                                                                                                        调节建议

                                                                                                                                                                                                                                                        • 想看「极端对比」→ 调 factor 到 100,无 norm 柱子会升到 100,有 norm 仍贴地

                                                                                                                                                                                                                                                        • 想看「小倍率下的微差」→ 调 factor 到 2,两根柱子分别约为 2.0 和 1.0

                                                                                                                                                                                                                                                        为什么重要

                                                                                                                                                                                                                                                        这是「Stable LatentMoE」之所以叫 Stable 的第一根支柱。没有 RMSNorm,路由分支的输出尺度会随路由决策剧烈波动,在大模型规模下会引发数值失稳。RMSNorm 不是可选项——论文指出它本身也改善验证损失。在生产中,如果发现训练不稳定,第一个要排查的就是 RMSNorm 是否被意外关闭。


                                                                                                                                                                                                                                                        Tab 6:梯度稀疏性

                                                                                                                                                                                                                                                        目的

                                                                                                                                                                                                                                                        验证稀疏 MoE 的核心性质——只有被路由选中的专家会获得梯度,未被选中的专家梯度为 0。这是 MoE 能节省训练计算量的本质原因:每一步只有 top_k 个专家更新权重。

                                                                                                                                                                                                                                                        对应测试 est_only_selected_experts_receive_gradient。

                                                                                                                                                                                                                                                        UI 组件与参数影响

                                                                                                                                                                                                                                                        参数

                                                                                                                                                                                                                                                        范围

                                                                                                                                                                                                                                                        默认

                                                                                                                                                                                                                                                        调节效果

                                                                                                                                                                                                                                                        dim

                                                                                                                                                                                                                                                        4-64

                                                                                                                                                                                                                                                        16

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 维度更大,但稀疏性比例不变

                                                                                                                                                                                                                                                        n_routed

                                                                                                                                                                                                                                                        2-32

                                                                                                                                                                                                                                                        8

                                                                                                                                                                                                                                                        显示值不变(当前实现使用小配置 n_routed=8 固定值,此滑块暂未接入)

                                                                                                                                                                                                                                                        top_k

                                                                                                                                                                                                                                                        1-4

                                                                                                                                                                                                                                                        1

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 每 token 选更多专家,touched_experts 数量增加(稀疏度下降)

                                                                                                                                                                                                                                                        seed

                                                                                                                                                                                                                                                        0-10

                                                                                                                                                                                                                                                        0

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 不同随机种子会选中不同的专家,但稀疏性性质不变

                                                                                                                                                                                                                                                         

                                                                                                                                                                                                                                                        注意:n_routed 滑块当前未接入底层函数(measure 内部使用 small_cfg 的 8 个专家),调节它不会改变结果。实际有效的参数是 dim、top_k、seed。

                                                                                                                                                                                                                                                        ”

                                                                                                                                                                                                                                                        输出图解读

                                                                                                                                                                                                                                                        tab-6
                                                                                                                                                                                                                                                        tab-6

                                                                                                                                                                                                                                                        单图布局(1 个柱状图)。

                                                                                                                                                                                                                                                        中心图:梯度稀疏性

                                                                                                                                                                                                                                                        • 图类型:三柱状图

                                                                                                                                                                                                                                                        • X 轴:used_experts(路由选中的专家数)、touched_experts(有梯度的专家数)、n_routed(总路由专家数)

                                                                                                                                                                                                                                                        • Y 轴:专家数量

                                                                                                                                                                                                                                                        • 颜色:蓝/绿/红

                                                                                                                                                                                                                                                        • 你该看什么:touched_experts 应该等于 used_experts(有梯度的恰好就是被选中的那些),且都远小于 n_routed

                                                                                                                                                                                                                                                        • 理想情况:touched_subset_of_used = True,touched_experts = top_k 左右(seq_len 个 token 可能选中不同专家,所以通常是 top_k~top_k×seq 之间)

                                                                                                                                                                                                                                                        • 异常指示:touched_experts == n_routed → 所有专家都有梯度,说明走了 dense 路径,MoE 稀疏性失效

                                                                                                                                                                                                                                                        调节建议

                                                                                                                                                                                                                                                        • 想看「极端稀疏」→ 调 top_k 到 1,只有 1 个专家有梯度

                                                                                                                                                                                                                                                        • 想看「接近稠密」→ 调 top_k 到 4,更多专家获得梯度(但仍 < n_routed)

                                                                                                                                                                                                                                                        为什么重要

                                                                                                                                                                                                                                                        梯度稀疏性是 MoE 架构的本质收益来源——如果未被选中的专家也有梯度,那 MoE 就退化为了全连接(只是更慢)。此 Tab 验证 dispatch 实现的正确性:index_add 只对被选中的专家加权累加,未选中专家的权重梯度严格为零。在生产中,如果发现训练速度远慢于理论稀疏度,第一个排查点就是梯度稀疏性。


                                                                                                                                                                                                                                                        Tab 7:Dispatch 正确性

                                                                                                                                                                                                                                                        目的

                                                                                                                                                                                                                                                        验证 GroupedExperts 的 orward_indexed(按专家分组 dispatch)与 orward_all(稠密评估)逐点一致,且对 token 顺序置换不变。这是 MoE 专家执行层的数值正确性验证。

                                                                                                                                                                                                                                                        对应测试 est_grouped_dispatch_matches_dense_evaluation / est_dispatch_is_permutation_invariant。

                                                                                                                                                                                                                                                        背景概念

                                                                                                                                                                                                                                                        Dispatch:把 (tokens, dim_in) 的 token 按 expert_ids 分配给各自对应的专家执行。生产中这会被优化为 grouped GEMM(一次矩阵乘法覆盖所有被选中的专家)。CPU 教学实现里使用「按专家排序 → 分段稠密 matmul → 回填原始顺序」的朴素方式,但数值上必须与「所有专家对所有 token 计算再按 id 取行」完全等价。

                                                                                                                                                                                                                                                        代码位置:moe.py:GroupedExperts.forward_indexed。

                                                                                                                                                                                                                                                        设计思路

                                                                                                                                                                                                                                                        背景:Dispatch 是 MoE 的"心脏手术"

                                                                                                                                                                                                                                                        MoE 的 forward_indexed 是生产路径——它把 token 按专家分组(torch.argsort(expert_ids) 让同专家的 token 连续),然后每专家只做自己那部分的 GEMM,最后 scatter 回原顺序。这个流程有 3 个容易出错的地方:

                                                                                                                                                                                                                                                        1. 分组时专家权重寻址错(用了错的 W_e)

                                                                                                                                                                                                                                                        2. scatter 回填顺序错(结果对不上原 token 顺序)

                                                                                                                                                                                                                                                        3. 排序/反排序不对称(导致结果依赖输入排列)

                                                                                                                                                                                                                                                        Tab 7 设计两个图分别对应 2 个独立验证场景:

                                                                                                                                                                                                                                                        左图:grouped vs dense(验证"专家寻址正确性")

                                                                                                                                                                                                                                                        场景:同一个 token 批次,用两种方式计算:

                                                                                                                                                                                                                                                        • grouped 路径(forward_indexed):生产实现,分组 + 分组 GEMM + 回填

                                                                                                                                                                                                                                                        • dense 路径(forward_all):教科书参考,每个 token 过所有 n_experts 个专家,再按 ids[i] 选第 i 个 token 对应的专家输出

                                                                                                                                                                                                                                                        为什么这么设计:

                                                                                                                                                                                                                                                        • dense 路径不可能错——它不用排序、不用分组、不用 scatter,就是简单的 einsum('ne,tnd->ted') 然后按索引取

                                                                                                                                                                                                                                                        • 如果 grouped 和 dense 不一致,说明 grouped 的"每专家取自己的权重子矩阵"逻辑有 bug

                                                                                                                                                                                                                                                        • 数学等价性:forward_indexed(x, ids)[i] = forward_all(x)[ids[i], i],恒等式

                                                                                                                                                                                                                                                        典型 bug 它能抓到:

                                                                                                                                                                                                                                                        • argsort 后没记录逆置换 → scatter 回填顺序错

                                                                                                                                                                                                                                                        • 专家权重 W_e 在分组时取错(比如第 3 组用了第 4 个专家的权重)

                                                                                                                                                                                                                                                        右图:置换不变性(验证"排序/反排序对称性")

                                                                                                                                                                                                                                                        场景:同一批 token,先按原顺序 dispatch 得 direct;把 token 按随机置换 perm 打乱后再 dispatch 得 shuffled;最后检查 direct[perm] == shuffled。

                                                                                                                                                                                                                                                        为什么这么设计:

                                                                                                                                                                                                                                                        • dispatch 内部用了 argsort(排序),但结果应该与输入顺序无关——token i 的输出只取决于 x[i] 和 ids[i],不应该因为"它排在第几个"而不同

                                                                                                                                                                                                                                                        • 这是强性质检验:即使 grouped vs dense 通过,如果排序/反排序不对称,特定排列下仍可能出错

                                                                                                                                                                                                                                                        • 能抓到 grouped vs dense 抓不到的 bug:比如 scatter 时把 inverse_perm 写成了 perm(正向用了反向)

                                                                                                                                                                                                                                                        典型 bug 它能抓到:

                                                                                                                                                                                                                                                        • scatter_index = perm 而不是 scatter_index = inverse_perm → 大部分情况下结果碰巧对(dense 验证通过),但某些排列下错

                                                                                                                                                                                                                                                        • 分组时按 ids 排序,回填时按 ids[perm] 排序 → 两个排序不一致

                                                                                                                                                                                                                                                        两图互补

                                                                                                                                                                                                                                                        图

                                                                                                                                                                                                                                                        验证性质

                                                                                                                                                                                                                                                        抓什么 bug

                                                                                                                                                                                                                                                        抓不到什么

                                                                                                                                                                                                                                                        grouped vs dense

                                                                                                                                                                                                                                                        专家寻址正确

                                                                                                                                                                                                                                                        权重寻址错、scatter 顺序错(与排列无关的那种)

                                                                                                                                                                                                                                                        排序/反排序不对称

                                                                                                                                                                                                                                                        置换不变性

                                                                                                                                                                                                                                                        排序/反排序对称

                                                                                                                                                                                                                                                        排序用错、回填用错、两个排序不一致

                                                                                                                                                                                                                                                        与排列无关的寻址错

                                                                                                                                                                                                                                                        一个过、一个不过的情况恰好能定位 bug 类型:

                                                                                                                                                                                                                                                        • 左过右不过 → 排序/反排序不对称

                                                                                                                                                                                                                                                        • 左不过右过 → 寻址错但碰巧对称(罕见)

                                                                                                                                                                                                                                                        • 都不过 → 多重 bug

                                                                                                                                                                                                                                                        UI 组件与参数影响

                                                                                                                                                                                                                                                        参数

                                                                                                                                                                                                                                                        范围

                                                                                                                                                                                                                                                        默认

                                                                                                                                                                                                                                                        调节效果

                                                                                                                                                                                                                                                        n_experts

                                                                                                                                                                                                                                                        2-32

                                                                                                                                                                                                                                                        6

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 更多专家参与,dispatch 的排序和分段更复杂

                                                                                                                                                                                                                                                        dim_in

                                                                                                                                                                                                                                                        4-32

                                                                                                                                                                                                                                                        8

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 输入维度更大

                                                                                                                                                                                                                                                        hidden

                                                                                                                                                                                                                                                        8-64

                                                                                                                                                                                                                                                        12

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 专家内部隐藏层更宽

                                                                                                                                                                                                                                                        dim_out

                                                                                                                                                                                                                                                        4-32

                                                                                                                                                                                                                                                        8

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 输出维度更大

                                                                                                                                                                                                                                                        n_tokens

                                                                                                                                                                                                                                                        8-128

                                                                                                                                                                                                                                                        20

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 更多 token 参与 dispatch

                                                                                                                                                                                                                                                        seed

                                                                                                                                                                                                                                                        0-10

                                                                                                                                                                                                                                                        0

                                                                                                                                                                                                                                                        随机种子,不影响性质结论

                                                                                                                                                                                                                                                        输出图解读

                                                                                                                                                                                                                                                        tab-7
                                                                                                                                                                                                                                                        tab-7

                                                                                                                                                                                                                                                        1×2 双联图布局。

                                                                                                                                                                                                                                                        左 (a):grouped vs dense

                                                                                                                                                                                                                                                        • 图类型:双柱状图,Y 轴对数刻度

                                                                                                                                                                                                                                                        • X 轴:max_abs_diff、mean_abs_diff

                                                                                                                                                                                                                                                        • Y 轴:abs diff(log scale,1e-12 起)

                                                                                                                                                                                                                                                        • 颜色:红/橙;灰色虚线 = 1e-6 容差线

                                                                                                                                                                                                                                                        • 你该看什么:两根柱子都远低于 1e-6 容差线(在 1e-8 ~ 1e-9 量级),说明分组 dispatch 与稠密 oracle 的误差是浮点舍入级别,可视为逐点一致

                                                                                                                                                                                                                                                        • 理想情况:max_abs_diff ~ 1e-7 ~ 1e-8,mean_abs_diff 比 max 小 1~2 个数量级,两者均 << 1e-6

                                                                                                                                                                                                                                                        • 异常指示:任何一根柱子高于 1e-6 容差线 → dispatch 实现有 bug(排序索引错位、回填顺序错、或专家权重寻址错)

                                                                                                                                                                                                                                                        • 可视化陷阱:max 与 mean 差 ~40 倍,线性刻度下 mean 会几乎看不见;log 刻度下两者都能看清

                                                                                                                                                                                                                                                        右 (b):置换不变性

                                                                                                                                                                                                                                                        • 图类型:双柱状图,Y 轴对数刻度

                                                                                                                                                                                                                                                        • X 轴:max_abs_diff、mean_abs_diff

                                                                                                                                                                                                                                                        • Y 轴:abs diff(log scale)

                                                                                                                                                                                                                                                        • 颜色:蓝/紫;灰色虚线 = 1e-6 容差线

                                                                                                                                                                                                                                                        • 你该看什么:两根柱子都远低于 1e-6 容差线,说明打乱 token 顺序后再 dispatch、再还原,结果与原顺序逐点一致

                                                                                                                                                                                                                                                        • 理想情况:max_abs_diff ~ 1e-8 或更小(纯索引置换通常误差为 0)

                                                                                                                                                                                                                                                        • 异常指示:柱子高于 1e-6 容差线 → dispatch 的排序/回填逻辑不对称(比如 gather 是 argsort 但 scatter 用错了索引)

                                                                                                                                                                                                                                                        • 可视化陷阱:若 max_abs_diff 为 0(精确相等),柱子会落到 1e-12 下限(0 值替换为 1e-12 避免 log(0))

                                                                                                                                                                                                                                                        为什么重要

                                                                                                                                                                                                                                                        Dispatch 是 MoE 的执行核心。如果 grouped 与 dense 不一致,说明专家权重的寻址或 token 的排列/逆排列有 bug——在大模型下这种误差会被专家数和层数放大,训练出来的模型与公式定义完全不同。置换不变性是更强的验证:如果同一批 token 换个顺序结果就变了,说明实现有状态污染或索引错误。


                                                                                                                                                                                                                                                        Tab 8:QB 语义

                                                                                                                                                                                                                                                        目的

                                                                                                                                                                                                                                                        验证 Quantile Balancing 路由器的三项核心语义:cutoff 等于第 k+1 个 biased score、偏置只导流不改权重、输出权重归一化。这是 QB 算法的语义基础——如果这些性质不成立,后续的均衡效果无从谈起。

                                                                                                                                                                                                                                                        对应测试 est_top_k_plus_one_yields_the_cutoff / est_bias_steers_dispatch_but_not_the_mixture_weights / est_weights_sum_to_one。

                                                                                                                                                                                                                                                        背景概念

                                                                                                                                                                                                                                                        QB 语义三件套:

                                                                                                                                                                                                                                                        1. cutoff 语义:路由器用 Top-(k+1) 选择,前 k 个是实际路由,第 k+1 个 biased score 就是 cutoff α——一个专家的 biased score 必须超过 α 才会进入 Top-k。cutoff 取自路由本身,省去了单独的 token 侧分位数计算。

                                                                                                                                                                                                                                                        2. 偏置只导流不改权重:偏置 b 只加在 biased score 上参与 Top-k 选择,但混合权重 p_ij = s_ij / Σs_ir 只用原始分数 s(不含 b)。这就是「无损失」(auxiliary-loss-free)的含义——负载均衡不扭曲路由器的优化目标。

                                                                                                                                                                                                                                                        3. 权重归一化:每个 token 的 k 个被选专家的权重加起来等于 1,构成一个概率分布。

                                                                                                                                                                                                                                                        UI 组件与参数影响

                                                                                                                                                                                                                                                        参数

                                                                                                                                                                                                                                                        范围

                                                                                                                                                                                                                                                        默认

                                                                                                                                                                                                                                                        调节效果

                                                                                                                                                                                                                                                        n_experts

                                                                                                                                                                                                                                                        4-32

                                                                                                                                                                                                                                                        8

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 专家更多,cutoff 与选中集的差距可能更明显

                                                                                                                                                                                                                                                        top_k

                                                                                                                                                                                                                                                        1-8

                                                                                                                                                                                                                                                        3

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 选更多专家,cutoff 是第 k+1 个

                                                                                                                                                                                                                                                        dim

                                                                                                                                                                                                                                                        4-64

                                                                                                                                                                                                                                                        16

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 维度更大,但语义性质不变

                                                                                                                                                                                                                                                        n_tokens

                                                                                                                                                                                                                                                        16-256

                                                                                                                                                                                                                                                        64

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 更多 token 样本,归一化误差统计更稳定

                                                                                                                                                                                                                                                        bias_std

                                                                                                                                                                                                                                                        0.5-4.0

                                                                                                                                                                                                                                                        2.0

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 偏置扰动更大,但 weights 应仍与 scores 归一化一致

                                                                                                                                                                                                                                                        seed

                                                                                                                                                                                                                                                        0-10

                                                                                                                                                                                                                                                        0

                                                                                                                                                                                                                                                        随机种子,不影响性质结论

                                                                                                                                                                                                                                                        输出图解读

                                                                                                                                                                                                                                                        tab-8
                                                                                                                                                                                                                                                        tab-8

                                                                                                                                                                                                                                                        1×3 三联图布局。

                                                                                                                                                                                                                                                        左 (a):cutoff 语义

                                                                                                                                                                                                                                                        • 图类型:双柱状图(布尔值)

                                                                                                                                                                                                                                                        • X 轴:cutoff_matches_topk、selected_above_cutoff

                                                                                                                                                                                                                                                        • Y 轴:bool(1=True,0=False)

                                                                                                                                                                                                                                                        • 颜色:绿/蓝

                                                                                                                                                                                                                                                        • 你该看什么:两根柱子都应该是 1(True),即 cutoff 恰好等于第 k 个排序后的 biased score,且所有被选中专家的 biased score 都 ≥ cutoff

                                                                                                                                                                                                                                                        • 理想情况:两项均为 True,min_gap > 0(选中专家与 cutoff 之间有正间隙)

                                                                                                                                                                                                                                                        • 异常指示:任何一项为 False → Top-(k+1) 选择或 cutoff 语义实现错误

                                                                                                                                                                                                                                                        中 (b):bias 只导流不改权重

                                                                                                                                                                                                                                                        • 图类型:双柱状图(布尔值)

                                                                                                                                                                                                                                                        • X 轴:scores_unchanged、weights_match_scores

                                                                                                                                                                                                                                                        • Y 轴:bool(1=True,0=False)

                                                                                                                                                                                                                                                        • 颜色:均为绿色(表示应该通过)

                                                                                                                                                                                                                                                        • 你该看什么:两根柱子都为 1——加偏置前后 scores 完全不变(scores 与 bias 无关),weights 等于选中集内 scores 归一化

                                                                                                                                                                                                                                                        • 理想情况:两项均为 True

                                                                                                                                                                                                                                                        • 异常指示:scores_unchanged = False → bias 错误地进入了分数计算;weights_match_scores = False → 权重归一化时混入了 bias

                                                                                                                                                                                                                                                        右 (c):权重归一化误差

                                                                                                                                                                                                                                                        • 图类型:双柱状图,Y 轴对数刻度

                                                                                                                                                                                                                                                        • X 轴:max_err、mean_err

                                                                                                                                                                                                                                                        • Y 轴:|sum(weights) - 1|(log scale,1e-12 起)

                                                                                                                                                                                                                                                        • 颜色:红/橙;灰色虚线 = 1e-5 容差线

                                                                                                                                                                                                                                                        • 你该看什么:两根柱子都远低于 1e-5 容差线(在 1e-7 ~ 1e-9 量级),说明权重和非常接近 1

                                                                                                                                                                                                                                                        • 理想情况:max_err ~ 1e-7 或更小,mean_err 比 max_err 小 1~2 个数量级

                                                                                                                                                                                                                                                        • 异常指示:max_err 高于 1e-5 容差线 → 权重归一化有 bug(可能是分母计算错了或数值溢出)

                                                                                                                                                                                                                                                        • 可视化陷阱:max 与 mean 差几十倍,线性刻度下 mean 会几乎看不见;log 刻度下两者都能看清

                                                                                                                                                                                                                                                        调节建议

                                                                                                                                                                                                                                                        • 想看「偏置很大但权重仍正确」→ 调 bias_std 到 4.0,验证权重归一化对偏置幅度不敏感

                                                                                                                                                                                                                                                        • 想看「极端小 top_k 的 cutoff 语义」→ 调 top_k 到 1,cutoff 就是第 2 个 biased score

                                                                                                                                                                                                                                                        为什么重要

                                                                                                                                                                                                                                                        这是 QB 算法的语义地基。如果偏置同时影响了权重(扭曲优化)、或者 cutoff 语义不对(均衡推导的前提不成立)、或者权重不归一(输出尺度不对),那么后续所有关于均衡效果的讨论都没有意义。此 Tab 是 QB 正确性的第一道关口。


                                                                                                                                                                                                                                                        Tab 9:QB 均衡效果

                                                                                                                                                                                                                                                        目的

                                                                                                                                                                                                                                                        展示 Quantile Balancing 的负载均衡效果:一步改善有多大、是否单调收敛、直方图估计与精确分位数的误差有多少。这是 QB 论文 §2.3.3 的核心卖点——「一步到达目标负载,无需学习率」。

                                                                                                                                                                                                                                                        对应测试 est_one_update_collapses_severe_imbalance / est_convergence_is_monotone / est_histogram_matches_the_exact_quantile。

                                                                                                                                                                                                                                                        UI 组件与参数影响

                                                                                                                                                                                                                                                        参数

                                                                                                                                                                                                                                                        范围

                                                                                                                                                                                                                                                        默认

                                                                                                                                                                                                                                                        调节效果

                                                                                                                                                                                                                                                        n_experts

                                                                                                                                                                                                                                                        4-64

                                                                                                                                                                                                                                                        16

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 专家更多,初始失衡更严重,一步改善更明显

                                                                                                                                                                                                                                                        top_k

                                                                                                                                                                                                                                                        1-8

                                                                                                                                                                                                                                                        2

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 选更多专家,天然负载更均匀,改善空间更小

                                                                                                                                                                                                                                                        dim

                                                                                                                                                                                                                                                        8-128

                                                                                                                                                                                                                                                        32

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 维度更大,但均衡效果主要由输入偏斜度决定

                                                                                                                                                                                                                                                        bins

                                                                                                                                                                                                                                                        500-4000

                                                                                                                                                                                                                                                        2000

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 直方图分箱更细,分位数估计误差更小(右下子图更接近)

                                                                                                                                                                                                                                                        tokens

                                                                                                                                                                                                                                                        1024-8192

                                                                                                                                                                                                                                                        4096

                                                                                                                                                                                                                                                        增大

                                                                                                                                                                                                                                                         → 样本更多,统计更稳定

                                                                                                                                                                                                                                                        seed

                                                                                                                                                                                                                                                        0-10

                                                                                                                                                                                                                                                        0

                                                                                                                                                                                                                                                        随机种子,影响初始失衡程度

                                                                                                                                                                                                                                                        输出图解读

                                                                                                                                                                                                                                                        tab-9
                                                                                                                                                                                                                                                        tab-9

                                                                                                                                                                                                                                                        2×2 四联图布局。

                                                                                                                                                                                                                                                        左上 (a):一步均衡 max/min 负载比

                                                                                                                                                                                                                                                        • 图类型:双柱状图

                                                                                                                                                                                                                                                        • X 轴:before、after 1 step

                                                                                                                                                                                                                                                        • Y 轴:max_min_ratio(最忙专家 / 最闲专家)

                                                                                                                                                                                                                                                        • 颜色:红色 = before,绿色 = after

                                                                                                                                                                                                                                                        • 你该看什么:before 柱子很高(严重失衡),after 柱子显著降低(接近均衡)

                                                                                                                                                                                                                                                        • 理想情况:before/after 比值改善 > 10 倍(默认配置下约 51 → 1.95,改善 26 倍)

                                                                                                                                                                                                                                                        • 异常指示:after 仍很高(> 5)→ QB 未生效或样本太少

                                                                                                                                                                                                                                                        右上 (b):单调收敛曲线

                                                                                                                                                                                                                                                        • 图类型:折线图

                                                                                                                                                                                                                                                        • X 轴:均衡步数(1/2/4/8)

                                                                                                                                                                                                                                                        • Y 轴:max_min_ratio

                                                                                                                                                                                                                                                        • 颜色/标记:紫色实线圆点

                                                                                                                                                                                                                                                        • 你该看什么:曲线单调下降——步数越多,负载比越低,越接近 1.0

                                                                                                                                                                                                                                                        • 理想情况:is_monotone_descending = True,总改善 > 1.5 倍

                                                                                                                                                                                                                                                        • 异常指示:曲线先升后降或震荡 → 直方图估计噪声过大,或 update 逻辑有 bug

                                                                                                                                                                                                                                                        左下 (c):直方图 vs 精确分位数

                                                                                                                                                                                                                                                        • 图类型:双折线对比图

                                                                                                                                                                                                                                                        • X 轴:expert id

                                                                                                                                                                                                                                                        • Y 轴:bias 偏置值

                                                                                                                                                                                                                                                        • 颜色/线型:蓝色实线圆点 = exact,橙色虚线方块 = histogram

                                                                                                                                                                                                                                                        • 你该看什么:两条线几乎重合,说明直方图近似的精度损失很小

                                                                                                                                                                                                                                                        • 理想情况:max_diff < 0.001(2000 bins 下约 0.0004),diff_in_units_of_bin < 1.5

                                                                                                                                                                                                                                                        • 异常指示:两条线明显分叉 → 直方图实现有 bug 或 bins 太少

                                                                                                                                                                                                                                                        右下 (d):负载变异系数 CV

                                                                                                                                                                                                                                                        • 图类型:双柱状图

                                                                                                                                                                                                                                                        • X 轴:before、after 1 step

                                                                                                                                                                                                                                                        • Y 轴:cv(标准差 / 均值)

                                                                                                                                                                                                                                                        • 颜色:红色 = before,绿色 = after

                                                                                                                                                                                                                                                        • 你该看什么:CV 从较高值降到很低,说明负载分布从偏斜变平坦

                                                                                                                                                                                                                                                        • 理想情况:after cv < 0.3(默认配置下约 0.1~0.2 级别)

                                                                                                                                                                                                                                                        • 异常指示:CV 下降很少 → 均衡效果差

                                                                                                                                                                                                                                                        调节建议

                                                                                                                                                                                                                                                        • 想看「最夸张的一步改善」→ 调 n_experts 到 64、tokens 到 8192,before 的 max_min_ratio 会非常高

                                                                                                                                                                                                                                                        • 想看「直方图高精度」→ 调 bins 到 4000,exact 与 histogram 几乎重合

                                                                                                                                                                                                                                                        • 想看「稀疏度极高时的均衡」→ 调 top_k 到 1,每 token 只选 1 个专家,均衡更有挑战性

                                                                                                                                                                                                                                                        为什么重要

                                                                                                                                                                                                                                                        这是 QB 的卖点验证——传统固定步长方法需要很多步缓慢收敛,QB 一步就把几十倍的失衡压到 2 倍以内。在 K3 896 专家的规模下,这种一步收敛的特性直接决定了 EP 训练是否能稳定跑起来。单调收敛和直方图精度则分别验证了算法的稳定性和大规模可部署性。


                                                                                                                                                                                                                                                        Tab 10:QB 工程行为

                                                                                                                                                                                                                                                        目的

                                                                                                                                                                                                                                                        验证 Quantile Balancing 的工程约定:延迟一步更新、mean-centring 不动点、推理冻结、可关闭开关。这些是生产部署中的硬约束——任何一项不满足,QB 就不能安全地用在真实训练中。

                                                                                                                                                                                                                                                        对应测试 est_bias_update_is_deferred_by_one_step / est_mean_centring_does_not_change_selection / est_bias_is_mean_centred / est_frozen_at_inference / est_disabled_router_leaves_the_bias_at_zero。

                                                                                                                                                                                                                                                        背景概念

                                                                                                                                                                                                                                                        QB 的 4 项工程约定:

                                                                                                                                                                                                                                                        1. 延迟一步更新:forward 只统计数据(_accumulate),不修改 bias;bias 只有在调用 update_bias() 后才改变。这保证了「某批算出的偏置不会用来路由同一批」,避免统计自洽性问题。

                                                                                                                                                                                                                                                        2. mean-centring 不动点:整体平移 bias(b → b + c)不改变路由选择(indices 和 weights 都不变),只会整体平移 cutoff。因此 QB 更新时做 mean-centring(b - mean(b))是零副作用的。

                                                                                                                                                                                                                                                        3. 推理冻结:eval 模式下 forward 不 _accumulate,histogram 和 token_count 保持为 0。推理时偏置是训练收敛的死常数。

                                                                                                                                                                                                                                                        4. 可关闭:enabled=False 时,即使 train 模式下 update_bias() 也不会改变 bias(始终为 0),干净地旁路 QB。

                                                                                                                                                                                                                                                        设计思路

                                                                                                                                                                                                                                                        背景:QB(Quantile Balancing)是 K3 的"无损失负载均衡"

                                                                                                                                                                                                                                                        传统 MoE 用辅助损失(load balancing loss)推动专家均衡,但损失函数会改变主任务梯度。K3 用 QB:只调 bias,不改 loss——通过直方图估计分位数,把"拥挤专家"的 bias 调低、"冷清专家"的 bias 调高。

                                                                                                                                                                                                                                                        QB 是有状态的(bias、histogram、token_count),工程上有 5 个关键不变量必须保证,否则训练会污染或不可复现。Tab 10 设计 7 个 case 对应 5 个工程场景:

                                                                                                                                                                                                                                                        Case 1-2: 延迟一步更新(measure_deferred_update)

                                                                                                                                                                                                                                                        场景:训练循环里,forward 和 update_bias() 的时序关系。

                                                                                                                                                                                                                                                        为什么重要:绝不能"用某批算出的 bias 去路由同批"——否则该批的 Top-k 选择与 cutoff 统计互相污染(第 5 个 token 的路由受前 4 个 token 的影响,但前 4 个又是基于旧 bias 路由的)。

                                                                                                                                                                                                                                                        设计:两个检查点:

                                                                                                                                                                                                                                                        1. unchanged_after_forward:forward 后 bias 不变(本批只是累积统计,没动 bias)

                                                                                                                                                                                                                                                        2. changed_after_update:update_bias() 后 bias 确实变了(更新生效)

                                                                                                                                                                                                                                                        抓什么 bug:如果 forward 里就改了 bias,说明时序错了;如果 update_bias() 没改 bias,说明更新逻辑失效。

                                                                                                                                                                                                                                                        Case 3-4: 平移不动点(measure_mean_centring_invariance)

                                                                                                                                                                                                                                                        场景:update_bias() 里会做 b ← b - mean(b)(mean-centring),控制 bias 整体尺度。

                                                                                                                                                                                                                                                        为什么重要:mean-centring 必须零副作用于路由语义——整体平移 bias 不应该改变 Top-k 排序(因为 cutoff 也随动)。

                                                                                                                                                                                                                                                        设计:把 bias 整体 +7.25,检查: 3. indices_unchanged:Top-k 索引不变 4. weights_unchanged:路由权重不变(因为 weights 只看原始 scores,不看 bias)

                                                                                                                                                                                                                                                        抓什么 bug:如果 mean-centring 改了路由,说明 cutoff 没随 bias 平移,或者 weights 计算混入了 bias。

                                                                                                                                                                                                                                                        Case 5: mean-centring 生效(measure_bias_mean_centred)

                                                                                                                                                                                                                                                        场景:update_bias() 后 bias 的均值应该接近 0。

                                                                                                                                                                                                                                                        为什么重要:mean-centring 防止"所有 bias 同时漂移"(全局正偏),否则多卡训练时各 rank 的 bias 尺度会发散。

                                                                                                                                                                                                                                                        设计:5. |mean(bias)| < 1e-5

                                                                                                                                                                                                                                                        抓什么 bug:漏了 mean-centring 这一步。

                                                                                                                                                                                                                                                        Case 6: 推理冻结(measure_inference_frozen)

                                                                                                                                                                                                                                                        场景:eval 模式下,路由器的 histogram 和 token_count 应该保持 0——推理时不累积统计。

                                                                                                                                                                                                                                                        为什么重要:推理时 bias 是训练收敛的"死常数",如果还持续累积统计(或更糟,调用 update_bias()),会把线上流量当成训练数据、污染已收敛的 bias。

                                                                                                                                                                                                                                                        设计:6. histogram.sum() == 0(forward 后直方图仍为空)

                                                                                                                                                                                                                                                        抓什么 bug:eval 模式下 _accumulate() 没被跳过。

                                                                                                                                                                                                                                                        Case 7: 关闭开关彻底(measure_disabled_router)

                                                                                                                                                                                                                                                        场景:enabled=False 时,QB 完全旁路——bias 恒为 0,即使训练模式下也无效。

                                                                                                                                                                                                                                                        为什么重要:QB 是可选机制,必须能干净关闭(比如先用辅助损失训练的阶段,或做对比实验)。关闭不彻底会让"partial 均衡"悄悄进入模型,测试结果不可复现。

                                                                                                                                                                                                                                                        设计:7. bias.all() == 0(即使 update_bias() 后)

                                                                                                                                                                                                                                                        抓什么 bug:enabled=False 时 _accumulate 或 update_bias 没短路。

                                                                                                                                                                                                                                                        5 个场景覆盖 QB 的完整生命周期

                                                                                                                                                                                                                                                          训练 forward ──→ 累积统计(Case 1, 6 的反向)
                                                                                                                                                                                                                                                               ↓
                                                                                                                                                                                                                                                          update_bias() ──→ 改 bias(Case 2)
                                                                                                                                                                                                                                                               ↓
                                                                                                                                                                                                                                                          mean-centring ──→ 零副作用(Case 3, 4, 5)
                                                                                                                                                                                                                                                               ↓
                                                                                                                                                                                                                                                          推理 forward ──→ 冻结统计(Case 6)
                                                                                                                                                                                                                                                               ↓
                                                                                                                                                                                                                                                          enabled=False ──→ 完全旁路(Case 7)

                                                                                                                                                                                                                                                          7 个 case 全过 = QB 的工程实现可信,任何一条挂了都指向具体子系统的 bug。

                                                                                                                                                                                                                                                          UI 组件与参数影响

                                                                                                                                                                                                                                                          参数

                                                                                                                                                                                                                                                          范围

                                                                                                                                                                                                                                                          默认

                                                                                                                                                                                                                                                          调节效果

                                                                                                                                                                                                                                                          dim

                                                                                                                                                                                                                                                          4-32

                                                                                                                                                                                                                                                          16

                                                                                                                                                                                                                                                          增大

                                                                                                                                                                                                                                                           → 维度更大,但工程行为不变

                                                                                                                                                                                                                                                          n_experts

                                                                                                                                                                                                                                                          4-32

                                                                                                                                                                                                                                                          8

                                                                                                                                                                                                                                                          增大

                                                                                                                                                                                                                                                           → 专家更多,但工程行为不变

                                                                                                                                                                                                                                                          top_k

                                                                                                                                                                                                                                                          1-4

                                                                                                                                                                                                                                                          2

                                                                                                                                                                                                                                                          增大

                                                                                                                                                                                                                                                           → 选更多专家,但工程行为不变

                                                                                                                                                                                                                                                          n_tokens

                                                                                                                                                                                                                                                          32-256

                                                                                                                                                                                                                                                          128

                                                                                                                                                                                                                                                          增大

                                                                                                                                                                                                                                                           → 更多 token 样本

                                                                                                                                                                                                                                                          平移量

                                                                                                                                                                                                                                                          1.0-15.0

                                                                                                                                                                                                                                                          7.25

                                                                                                                                                                                                                                                          增大

                                                                                                                                                                                                                                                           → 测试 mean-centring 不动点的平移幅度更大,但结果应仍不变

                                                                                                                                                                                                                                                          seed

                                                                                                                                                                                                                                                          0-10

                                                                                                                                                                                                                                                          0

                                                                                                                                                                                                                                                          随机种子,不影响性质结论

                                                                                                                                                                                                                                                          输出图解读

                                                                                                                                                                                                                                                          tab-10
                                                                                                                                                                                                                                                          tab-10

                                                                                                                                                                                                                                                          单图布局(横向条形图,7 项检查)。

                                                                                                                                                                                                                                                          中心图:QB 工程行为检查

                                                                                                                                                                                                                                                          • 图类型:横向条形图(7 项 PASS/FAIL 检查)

                                                                                                                                                                                                                                                          • Y 轴:7 项检查名称

                                                                                                                                                                                                                                                          • X 轴:是/否(0 或 1)

                                                                                                                                                                                                                                                          • 颜色:绿色 = PASS(1),红色 = FAIL(0)

                                                                                                                                                                                                                                                          • 你该看什么:所有 7 条都应该是绿色(PASS)

                                                                                                                                                                                                                                                          • 7 项检查内容:

                                                                                                                                                                                                                                                            1. forward 后 bias 不变(延迟更新)

                                                                                                                                                                                                                                                            2. update 后 bias 改变(延迟更新)

                                                                                                                                                                                                                                                            3. 平移不改变 indices(mean-centring 不动点)

                                                                                                                                                                                                                                                            4. 平移不改变 weights(mean-centring 不动点)

                                                                                                                                                                                                                                                            5. 更新后 bias 均值 ≈ 0(mean-centring)

                                                                                                                                                                                                                                                            6. 推理冻结:histogram_sum == 0

                                                                                                                                                                                                                                                            7. 关闭后 bias 全 0

                                                                                                                                                                                                                                                          • 理想情况:7/7 PASS,全部绿色

                                                                                                                                                                                                                                                          • 异常指示:任何一项红色(FAIL)→ 对应工程约定被破坏,需要排查

                                                                                                                                                                                                                                                          为什么重要

                                                                                                                                                                                                                                                          这些是 QB 能安全部署在生产训练中的硬约束。延迟更新保证统计口径自洽;mean-centring 不动点保证偏置去中心化没有副作用;推理冻结保证线上行为确定可复现;可关闭开关支持消融实验与分阶段训练。少任何一项,在多卡分布式训练中都可能出难以排查的问题。


                                                                                                                                                                                                                                                          Tab 11:896 专家压力测试

                                                                                                                                                                                                                                                          目的

                                                                                                                                                                                                                                                          在论文规模(896 专家、top_k=16、稀疏度 56)下验证 Quantile Balancing 仍然有效——一步就有显著改善、几步就收敛到极致均匀。这是 QB 能支撑 K3 极端稀疏配置的直接证据。

                                                                                                                                                                                                                                                          对应测试 est_scales_to_the_papers_expert_count。

                                                                                                                                                                                                                                                          背景概念

                                                                                                                                                                                                                                                          论文规模:K3 每层有 896 个 routed experts,每 token 激活 16 个(稀疏度 56)。在这种近千专家的规模下,传统固定步长均衡方法收敛极慢,容易造成持续的 EP 负载失衡——有的专家忙到爆、有的专家闲到饿死,训练效率和效果都受影响。QB 的设计动机就是在这种规模下仍能一步均衡。

                                                                                                                                                                                                                                                          UI 组件与参数影响

                                                                                                                                                                                                                                                          参数

                                                                                                                                                                                                                                                          范围

                                                                                                                                                                                                                                                          默认

                                                                                                                                                                                                                                                          调节效果

                                                                                                                                                                                                                                                          dim

                                                                                                                                                                                                                                                          16-128

                                                                                                                                                                                                                                                          64

                                                                                                                                                                                                                                                          增大

                                                                                                                                                                                                                                                           → 维度更大,运行时间增加,但效果趋势不变

                                                                                                                                                                                                                                                          n_experts

                                                                                                                                                                                                                                                          128-896

                                                                                                                                                                                                                                                          896

                                                                                                                                                                                                                                                          增大

                                                                                                                                                                                                                                                           → 专家越多,初始失衡越严重,一步改善越明显

                                                                                                                                                                                                                                                          top_k

                                                                                                                                                                                                                                                          4-32

                                                                                                                                                                                                                                                          16

                                                                                                                                                                                                                                                          增大

                                                                                                                                                                                                                                                           → 激活专家更多,稀疏度下降,天然更均衡

                                                                                                                                                                                                                                                          bins

                                                                                                                                                                                                                                                          500-2000

                                                                                                                                                                                                                                                          1000

                                                                                                                                                                                                                                                          增大

                                                                                                                                                                                                                                                           → 分箱更细,直方图精度更高

                                                                                                                                                                                                                                                          tokens

                                                                                                                                                                                                                                                          2048-16384

                                                                                                                                                                                                                                                          8192

                                                                                                                                                                                                                                                          增大

                                                                                                                                                                                                                                                           → 样本更多,统计更稳定

                                                                                                                                                                                                                                                          seed

                                                                                                                                                                                                                                                          0-10

                                                                                                                                                                                                                                                          0

                                                                                                                                                                                                                                                          随机种子,影响初始失衡程度

                                                                                                                                                                                                                                                          输出图解读

                                                                                                                                                                                                                                                          tab-11
                                                                                                                                                                                                                                                          tab-11

                                                                                                                                                                                                                                                          1×3 三联图布局。

                                                                                                                                                                                                                                                          左 (a):max_min_ratio(对数刻度)

                                                                                                                                                                                                                                                          • 图类型:三柱状图

                                                                                                                                                                                                                                                          • X 轴:初始失衡、1 步后、5 步后

                                                                                                                                                                                                                                                          • Y 轴:max_min_ratio(log scale)

                                                                                                                                                                                                                                                          • 颜色:红/橙/绿

                                                                                                                                                                                                                                                          • 你该看什么:初始值极高(上百甚至上千),1 步后显著下降,5 步后降到很低

                                                                                                                                                                                                                                                          • 理想情况:before > 100,one_step 大幅下降,converged 接近 1(< 2)

                                                                                                                                                                                                                                                          • 异常指示:1 步后下降不多 → QB 在大规模下失效

                                                                                                                                                                                                                                                          中 (b):max_over_mean

                                                                                                                                                                                                                                                          • 图类型:三柱状图

                                                                                                                                                                                                                                                          • X 轴:初始失衡、1 步后、5 步后

                                                                                                                                                                                                                                                          • Y 轴:max_over_mean(最忙专家 / 平均负载)

                                                                                                                                                                                                                                                          • 颜色:红/橙/绿

                                                                                                                                                                                                                                                          • 你该看什么:5 步后 max_over_mean 应接近 1.0(1.1 以下)

                                                                                                                                                                                                                                                          • 理想情况:converged max_over_mean < 1.1

                                                                                                                                                                                                                                                          • 异常指示:5 步后仍 > 1.3 → 收敛不足

                                                                                                                                                                                                                                                          右 (c):cv(变异系数)

                                                                                                                                                                                                                                                          • 图类型:三柱状图

                                                                                                                                                                                                                                                          • X 轴:初始失衡、1 步后、5 步后

                                                                                                                                                                                                                                                          • Y 轴:cv = std / mean

                                                                                                                                                                                                                                                          • 颜色:红/橙/绿

                                                                                                                                                                                                                                                          • 你该看什么:cv 从 0.9 左右降到 0.03 以下,说明负载分布从高度偏斜变成几乎平坦

                                                                                                                                                                                                                                                          • 理想情况:converged cv < 0.03

                                                                                                                                                                                                                                                          • 异常指示:cv 下降很少 → 均衡效果差

                                                                                                                                                                                                                                                          调节建议

                                                                                                                                                                                                                                                          • 想看「极端初始失衡」→ n_experts 拉到 896、tokens 拉到 16384,初始 max_min_ratio 可能达到几百

                                                                                                                                                                                                                                                          • 想看「低稀疏度下的均衡」→ top_k 拉到 32,稀疏度=28,初始失衡会小一些

                                                                                                                                                                                                                                                          • 想看「直方图精度影响」→ bins 降到 500,看收敛是否变慢或变差

                                                                                                                                                                                                                                                          为什么重要

                                                                                                                                                                                                                                                          这是 QB 的「压力测试」——论文中所有关于 QB 的好处(一步收敛、无需学习率)都是在大规模下才有意义。如果在 896 专家规模下 QB 不能一步见效,那整个设计动机就不成立。此 Tab 直接验证了 QB 在 K3 真实配置下的有效性,是整个模块最接近「生产指标」的验证。


                                                                                                                                                                                                                                                          Tab 12:SiTU-GLU

                                                                                                                                                                                                                                                          目的

                                                                                                                                                                                                                                                          全面验证 SiTU-GLU(Sigmoid Tanh Unit GLU)的数学性质:有界性、与 SwiGLU 的曲线对比、原点匹配、饱和区梯度(softcap vs 硬 clamp)、模块级有界性、以及同权重下 SwiGLU 离群 vs SiTU-GLU 守界的对比。这是「Stable」的第二根支柱——用有界激活消除 FP8 溢出风险。

                                                                                                                                                                                                                                                          对应测试 test_output_is_bounded / test_matches_swiglu_near_the_origin / test_gradients_survive_saturation / test_module_shapes_and_bound / test_swiglu_baseline_explodes_where_situ_does_not。

                                                                                                                                                                                                                                                          背景概念

                                                                                                                                                                                                                                                          SwiGLU 的离群点问题:SwiGLU = silu(gate) × up = sigmoid(gate) × gate × up。gate 和 up 两个因子都是无界的,在 MoE 这种极宽网络中,偶尔会有某个神经元的 gate 与 up 同时取到大值,二者乘积产生离群点(outlier)。在低精度(FP8/BF16)下,这些离群点会溢出或严重损失精度。

                                                                                                                                                                                                                                                          SiTU-GLU 的解决方案: 给 gate 和 up 各套一个 softcap(β · tanh(z/β)),让两个因子都有界,因此乘积也有界(≤ β_g × β_u)。K3 取 β_g=4、β_u=25,上界恰好为 100,小于 FP8 E4M3 的表示上限 448,保证 FP8 激活不溢出。

                                                                                                                                                                                                                                                          幅值差异

                                                                                                                                                                                                                                                          SiTU-GLU 是一个有界的 GLU 变体,SwiGLU 无界。相同权重、相同输入下,两者在小输入时几乎一样,幅值差异随输入增大而拉开。

                                                                                                                                                                                                                                                          公式对比(Kimi K3 的定义)

                                                                                                                                                                                                                                                            SwiGLU(x)  = Swish(W_g x) ⊙ (W_u x) = [ W_g x · σ(W_g x) ] ⊙ (W_u x)
                                                                                                                                                                                                                                                            SiTU-GLU(x)= [ β₁·tanh(W_g x/β₁) ⊙ σ(W_g x) ] ⊙ [ β₂·tanh(W_u x/β₂) ]
                                                                                                                                                                                                                                                            其中 Kimi K3 取 β₁=4(门分支)、β₂=25(up 分支)

                                                                                                                                                                                                                                                            也就是说,SiTU-GLU 对 gate 分支和 up 分支各加了一个 scaled tanh 软封顶(softcap)。

                                                                                                                                                                                                                                                            三个层面的幅值差异

                                                                                                                                                                                                                                                            1. 门分支的幅值 ——SiTU 有上界,SwiGLU 无界

                                                                                                                                                                                                                                                            • Swish (g) = g・σ(g):g 很大时 σ(g)→1,Swish ≈ g,无上界(g=100 → 幅值≈100)。

                                                                                                                                                                                                                                                            • SiTU 门 = β₁・tanh (g/β₁)・σ(g):tanh 把它封在 ±β₁,正大值时趋于 β₁=4。

                                                                                                                                                                                                                                                            • 数例:g=4 → Swish≈3.93 vs SiTU 门≈2.99;g=10 → Swish≈10 vs SiTU 门≈3.95(已经封顶在 4 附近)。

                                                                                                                                                                                                                                                            2. up 分支的幅值 ——SiTU 有界,SwiGLU 线性

                                                                                                                                                                                                                                                            • SwiGLU 的 up = W_u x,线性、无上界。

                                                                                                                                                                                                                                                            • SiTU 的 up = β₂・tanh (W_u x/β₂),封在 ±β₂=±25。

                                                                                                                                                                                                                                                            • 数例:u=50 → SwiGLU up=50 vs SiTU up≈24.1(趋近 25);u=100 → 100 vs ≈24.98。

                                                                                                                                                                                                                                                            3. 输出乘积幅值 —— 本质区别

                                                                                                                                                                                                                                                            • SwiGLU 输出 = Swish (g)・u,两个因子都无界 → 整体无上界,可爆。

                                                                                                                                                                                                                                                            • SiTU-GLU 输出 = [有界门]・[有界 up],| 输出 | ≤ β₁・β₂ = 4×25 = 100,严格有界。

                                                                                                                                                                                                                                                            关键:差异是 "随输入增大而放大",不是全程不同

                                                                                                                                                                                                                                                            scaled tanh 在原点附近近似线性(β・tanh (x/β)≈x),所以:

                                                                                                                                                                                                                                                            • 小输入(线性区):SiTU-GLU 与 SwiGLU 的激活幅值几乎一致 —— 这正是 Kimi 论文里说的 "保留 SwiGLU 的局部响应"。

                                                                                                                                                                                                                                                            • 大输入(饱和区):SiTU-GLU 被软封顶(门≤4、up≤±25、输出≤100),SwiGLU 线性放大 ——幅值差异随 | 输入 | 增大而系统性放大。

                                                                                                                                                                                                                                                            为什么这么设计

                                                                                                                                                                                                                                                            SiTU-GLU 的动机就是防止激活爆炸、控制幅值上界:在大规模 / 深栈(Kimi K3 还配了 Attention Residuals)、低精度量化、以及需要数值稳定的场景下,SwiGLU 无界的大幅值容易成为不稳定源;把两个因子都软封顶后,模型在保留 SwiGLU 小信号行为的同时,保证任意输入下激活幅值不越界。

                                                                                                                                                                                                                                                            一句话:有区别,且是有意的—— 局部响应相同,大信号幅值 SiTU-GLU 被封顶(β₁、β₂、β₁β₂ 三个上界),SwiGLU 无界;相同权重同输入下,越大的输入两者幅值差得越多。

                                                                                                                                                                                                                                                            示意图(两分支的幅值对比)

                                                                                                                                                                                                                                                            门分支 gate(β₁=4)

                                                                                                                                                                                                                                                              幅值
                                                                                                                                                                                                                                                                   7┤                                  S ───────────  Swish≈g,无上界,越走越高
                                                                                                                                                                                                                                                                   6┤                              ··
                                                                                                                                                                                                                                                                   5┤                          ··
                                                                                                                                                                                                                                                                   4┤  ·························o────────────────────  ← β₁=4 封顶线(SiTU 门饱和)
                                                                                                                                                                                                                                                                   3┤                    o···::
                                                                                                                                                                                                                                                                   2┤               o···:
                                                                                                                                                                                                                                                                   1┤          o···:
                                                                                                                                                                                                                                                                   0┤ ····o··o··o····o·····:
                                                                                                                                                                                                                                                                -0.3┤o·····:
                                                                                                                                                                                                                                                                    └────┬────┬────┬────┬────┬────┬────┬────┬──→ g
                                                                                                                                                                                                                                                                        -6   -4   -2    0    2    4    6


                                                                                                                                                                                                                                                                · = Swish(g) = g·σ(g)          o = SiTU门 = 4·tanh(g/4)·σ(g)
                                                                                                                                                                                                                                                                小输入(线性区)两者几乎重合;随 |g| 增大,Swish 无界走高,SiTU 门封顶在 4
                                                                                                                                                                                                                                                              up 分支(β₂=25)

                                                                                                                                                                                                                                                                幅值
                                                                                                                                                                                                                                                                +25┤─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ← 上界 +β₂=25
                                                                                                                                                                                                                                                                   │                         o ── SiTU = 25·tanh(u/25) 封顶
                                                                                                                                                                                                                                                                   │                      o
                                                                                                                                                                                                                                                                   │                   o
                                                                                                                                                                                                                                                                  0┤──────o────────────────────────────────────── (u=0)
                                                                                                                                                                                                                                                                   │           o
                                                                                                                                                                                                                                                                   │        o
                                                                                                                                                                                                                                                                -25┤─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ← 下界 -β₂=25
                                                                                                                                                                                                                                                                   └────┬────┬────┬────┬────┬────┬────┬────┬──→ u
                                                                                                                                                                                                                                                                       -30  -20  -10   0   10   20   30


                                                                                                                                                                                                                                                                  SwiGLU up = u(线性,无界)   vs   SiTU up(封在 ±25)
                                                                                                                                                                                                                                                                  小输入两者重合;大输入 SiTU 饱和、SwiGLU 线性放大
                                                                                                                                                                                                                                                                结论

                                                                                                                                                                                                                                                                  输出幅值:|SiTU-GLU| ≤ β₁·β₂ = 4×25 = 100(严格有界)
                                                                                                                                                                                                                                                                           SwiGLU = Swish(g)·u,两个因子都无界 → 整体无界(可爆炸)
                                                                                                                                                                                                                                                                  小输入(线性区):两者几乎一致(β·tanh≈x,保留 SwiGLU 局部响应)
                                                                                                                                                                                                                                                                  大输入(饱和区):SiTU 门→4、up→±25,幅值差异随 |输入| 增大而放大

                                                                                                                                                                                                                                                                  UI 组件与参数影响

                                                                                                                                                                                                                                                                  参数

                                                                                                                                                                                                                                                                  范围

                                                                                                                                                                                                                                                                  默认

                                                                                                                                                                                                                                                                  调节效果

                                                                                                                                                                                                                                                                  beta_gate

                                                                                                                                                                                                                                                                  1.0-10.0

                                                                                                                                                                                                                                                                  4.0

                                                                                                                                                                                                                                                                  增大

                                                                                                                                                                                                                                                                   → 上界线性增大,原点匹配误差减小(softcap 更接近恒等),饱和区梯度变化更缓

                                                                                                                                                                                                                                                                  beta_up

                                                                                                                                                                                                                                                                  5.0-50.0

                                                                                                                                                                                                                                                                  25.0

                                                                                                                                                                                                                                                                  增大

                                                                                                                                                                                                                                                                   → 上界线性增大,激活曲线整体更高

                                                                                                                                                                                                                                                                  x_range

                                                                                                                                                                                                                                                                  2.0-30.0

                                                                                                                                                                                                                                                                  10.0

                                                                                                                                                                                                                                                                  增大

                                                                                                                                                                                                                                                                   → 曲线展示范围更宽,能看到更远处的饱和行为

                                                                                                                                                                                                                                                                  input_scale

                                                                                                                                                                                                                                                                  10.0-100.0

                                                                                                                                                                                                                                                                  40.0

                                                                                                                                                                                                                                                                  增大

                                                                                                                                                                                                                                                                   → 模块级有界测试中输入更大,SwiGLU 离群更严重(右下图对比更悬殊)

                                                                                                                                                                                                                                                                  seed

                                                                                                                                                                                                                                                                  0-10

                                                                                                                                                                                                                                                                  0

                                                                                                                                                                                                                                                                  随机种子,影响模块权重初始化和爆炸测试的具体数值

                                                                                                                                                                                                                                                                  输出图解读

                                                                                                                                                                                                                                                                  tab-12
                                                                                                                                                                                                                                                                  tab-12

                                                                                                                                                                                                                                                                  2×2 四联图布局。

                                                                                                                                                                                                                                                                  左上 (a):激活曲线 SiTU-GLU vs SwiGLU

                                                                                                                                                                                                                                                                  • 图类型:双折线图

                                                                                                                                                                                                                                                                  • X 轴:x(输入标量)

                                                                                                                                                                                                                                                                  • Y 轴:SiTU-GLU(x, x) / SwiGLU(x, x)

                                                                                                                                                                                                                                                                  • 颜色:绿色实线 = SiTU-GLU(有界),红色实线 = SwiGLU(无界);灰色虚线 = 上界 ±β_g·β_u

                                                                                                                                                                                                                                                                  • 你该看什么:在原点附近两条线几乎重合(原点匹配);x 增大后 SiTU-GLU 趋于平坦(被 softcap 钳住),而 SwiGLU 继续上升

                                                                                                                                                                                                                                                                  • 理想情况:|x| 大时 SiTU-GLU 接近水平直线(在上界附近),SwiGLU 持续增长;原点附近二者偏差 < 1%

                                                                                                                                                                                                                                                                  • 异常指示:SiTU-GLU 也随 x 线性增长 → softcap 未生效或 beta 设置过大

                                                                                                                                                                                                                                                                  右上 (b):饱和区梯度 softcap vs 硬 clamp

                                                                                                                                                                                                                                                                  • 图类型:分组柱状图

                                                                                                                                                                                                                                                                  • X 轴:不同 z 值(如 z=20/50/100)

                                                                                                                                                                                                                                                                  • Y 轴:梯度值

                                                                                                                                                                                                                                                                  • 颜色:绿色 = softcap 梯度,红色 = 硬 clamp 梯度

                                                                                                                                                                                                                                                                  • 你该看什么:softcap 梯度在饱和区仍为正值(虽然很小),硬 clamp 梯度为 0

                                                                                                                                                                                                                                                                  • 理想情况:softcap_grad > 0 且 softcap_grad > hard_clamp_grad(后者在饱和区为 0)

                                                                                                                                                                                                                                                                  • 异常指示:softcap 梯度也为 0 → 可能用了 clamp 而非 tanh

                                                                                                                                                                                                                                                                  左下 (c):核心性质验证(横向条形图)

                                                                                                                                                                                                                                                                  • 图类型:横向条形图(4 项性质检查)

                                                                                                                                                                                                                                                                  • Y 轴:4 项性质(上界可达、原点匹配、模块级有界、SwiGLU/SiTU 比)

                                                                                                                                                                                                                                                                  • X 轴:0/1(PASS/FAIL)或比值

                                                                                                                                                                                                                                                                  • 颜色:绿色 = PASS,橙色 = 数值展示项

                                                                                                                                                                                                                                                                  • 你该看什么:上界可达(rel_err ≈ 0)、原点匹配误差很小(< 0.001)、模块级 all_finite = True、SwiGLU 离群是 SiTU-GLU 的几十倍

                                                                                                                                                                                                                                                                  • 理想情况:4 项都通过,SwiGLU/SiTU 比 > 10

                                                                                                                                                                                                                                                                  • 异常指示:任何一项红色 FAIL → 对应性质不成立

                                                                                                                                                                                                                                                                  右下 (d):同权重同输入下的激活幅值对比

                                                                                                                                                                                                                                                                  • 图类型:双柱状图,Y 轴对数刻度

                                                                                                                                                                                                                                                                  • X 轴:SiTU-GLU max、SwiGLU max

                                                                                                                                                                                                                                                                  • Y 轴:max|activation|(log scale)

                                                                                                                                                                                                                                                                  • 颜色:绿色 = SiTU-GLU,红色 = SwiGLU;灰色虚线 = 上界 β_g·β_u

                                                                                                                                                                                                                                                                  • 你该看什么:SiTU-GLU 柱在上界附近(不超过),SwiGLU 柱远超上界(高几个数量级)

                                                                                                                                                                                                                                                                  • 理想情况:SiTU max ≤ β_g·β_u,SwiGLU max >> β_g·β_u(比 SiTU 大 10x 以上)

                                                                                                                                                                                                                                                                  • 异常指示:SiTU-GLU 也远超上界 → softcap 未生效;两根柱子接近 → 输入不够极端或 beta 太大

                                                                                                                                                                                                                                                                  调节建议

                                                                                                                                                                                                                                                                  • 想看「上界更高 + 更接近 SwiGLU」→ 调 beta_gate 到 10、beta_up 到 50,上界升至 500,原点匹配误差更小

                                                                                                                                                                                                                                                                  • 想看「极端离群对比」→ 调 input_scale 到 100,SwiGLU 的 max 会非常夸张,SiTU-GLU 仍守在上界

                                                                                                                                                                                                                                                                  • 想看「饱和区梯度差异最明显」→ 调 beta_gate 到 1,softcap 更早饱和,与硬 clamp 的梯度差更突出

                                                                                                                                                                                                                                                                  为什么重要

                                                                                                                                                                                                                                                                  SiTU-GLU 是「Stable LatentMoE」的第二根支柱。在 K3 的 FP8 推理场景中,如果激活无界,就需要额外的量化缩放和溢出处理,既慢又损失精度。SiTU-GLU 的有界性从数学上保证了激活永远不会超出 FP8 表示范围,是 K3 能高效跑 FP8 推理的关键前提。此 Tab 把有界、光滑、原点匹配三项核心性质一次性验证清楚。


                                                                                                                                                                                                                                                                  0x04 附录

                                                                                                                                                                                                                                                                  4.1 Tab 与测试函数的对应关系

                                                                                                                                                                                                                                                                  Tab

                                                                                                                                                                                                                                                                  测试文件

                                                                                                                                                                                                                                                                  measure/test 函数

                                                                                                                                                                                                                                                                  1 原理总览

                                                                                                                                                                                                                                                                  -

                                                                                                                                                                                                                                                                  plot_moe_principle.py:plot_moe_principle_four

                                                                                                                                                                                                                                                                  2 Demo 四联图

                                                                                                                                                                                                                                                                  -

                                                                                                                                                                                                                                                                  demo_stable_latent_moe.py:plot_demo_four

                                                                                                                                                                                                                                                                  3 前向契约

                                                                                                                                                                                                                                                                  test_moe.py

                                                                                                                                                                                                                                                                  measure_forward_shape_and_routing, measure_eq11_reference_consistency, measure_expert_gradient_sparsity

                                                                                                                                                                                                                                                                  4 潜空间 width 分离

                                                                                                                                                                                                                                                                  test_moe.py

                                                                                                                                                                                                                                                                  measure_latent_bottleneck_dimensions

                                                                                                                                                                                                                                                                  5 RMSNorm 稳定性

                                                                                                                                                                                                                                                                  test_moe.py

                                                                                                                                                                                                                                                                  measure_rmsnorm_scale_sensitivity

                                                                                                                                                                                                                                                                  6 梯度稀疏性

                                                                                                                                                                                                                                                                  test_moe.py

                                                                                                                                                                                                                                                                  measure_expert_gradient_sparsity

                                                                                                                                                                                                                                                                  7 Dispatch 正确性

                                                                                                                                                                                                                                                                  test_moe.py

                                                                                                                                                                                                                                                                  measure_grouped_dispatch_vs_dense, measure_dispatch_permutation_invariance

                                                                                                                                                                                                                                                                  8 QB 语义

                                                                                                                                                                                                                                                                  test_router_qb.py

                                                                                                                                                                                                                                                                  measure_cutoff_semantics, measure_bias_steering, measure_weights_normalization

                                                                                                                                                                                                                                                                  9 QB 均衡效果

                                                                                                                                                                                                                                                                  test_router_qb.py

                                                                                                                                                                                                                                                                  measure_one_step_balance, measure_monotonic_convergence, measure_histogram_vs_exact

                                                                                                                                                                                                                                                                  10 QB 工程行为

                                                                                                                                                                                                                                                                  test_router_qb.py

                                                                                                                                                                                                                                                                  measure_deferred_update, measure_mean_centring_invariance, measure_bias_mean_centred, measure_inference_frozen, measure_disabled_router

                                                                                                                                                                                                                                                                  11 896 专家压力测试

                                                                                                                                                                                                                                                                  test_router_qb.py

                                                                                                                                                                                                                                                                  measure_paper_scale_performance

                                                                                                                                                                                                                                                                  12 SiTU-GLU

                                                                                                                                                                                                                                                                  test_situ_glu.py

                                                                                                                                                                                                                                                                  measure_situ_vs_swiglu_curve, measure_situ_bound, measure_origin_match, measure_saturation_gradients, measure_module_bound, measure_swiglu_explodes_vs_situ

                                                                                                                                                                                                                                                                  4.2 已知参数限制

                                                                                                                                                                                                                                                                  以下 Tab 中的部分滑块当前仅为占位,未接入底层 measure 函数:

                                                                                                                                                                                                                                                                  Tab

                                                                                                                                                                                                                                                                  未接入参数

                                                                                                                                                                                                                                                                  说明

                                                                                                                                                                                                                                                                  4

                                                                                                                                                                                                                                                                  latent_dim / n_routed / n_shared / expert_hidden

                                                                                                                                                                                                                                                                  measure 函数使用固定 small_cfg,仅 dim 有效

                                                                                                                                                                                                                                                                  6

                                                                                                                                                                                                                                                                  n_routed

                                                                                                                                                                                                                                                                  同上,仅 dim / top_k / seed 有效

                                                                                                                                                                                                                                                                  4.3 默认配置下的典型数值

                                                                                                                                                                                                                                                                  默认参数、seed=0 的实测值(供参考):

                                                                                                                                                                                                                                                                  • Tab 5 RMSNorm:有 norm ratio = 1.000, 无 norm ratio = 50.000

                                                                                                                                                                                                                                                                  • Tab 9 QB 均衡:max_min_ratio 51.16 → 1.95(26x 改善),直方图误差 0.43 bin 宽

                                                                                                                                                                                                                                                                  • Tab 11 论文规模:初始 358.7x → 1 步 max/mean 1.326 → 5 步 max/mean 1.046, cv 0.0149

                                                                                                                                                                                                                                                                  • Tab 12 SiTU-GLU:上界 100 (rel_err=0.0),原点匹配误差 0.02%,SwiGLU/SiTU 比 42.9x


                                                                                                                                                                                                                                                                  TransFormer-封面
                                                                                                                                                                                                                                                                  TransFormer-封面

                                                                                                                                                                                                                                                                  阅读原文

                                                                                                                                                                                                                                                                  跳转微信打开

                                                                                                                                                                                                                                                                  •  

                                                                                                                                                                                                                                                                  【轻量化复刻大模型 / KIMI K3】Stable LatentMoE 梳理

                                                                                                                                                                                                                                                                  原创 罗西的思考 2026-11-13 21:51 北京

                                                                                                                                                                                                                                                                  【轻量化复刻大模型 / KIMI K3】Stable LatentMoE 梳理

                                                                                                                                                                                                                                                                  • 0x00 概要
                                                                                                                                                                                                                                                                  • 0x01. 演进脉络与定位
                                                                                                                                                                                                                                                                    • 1.1 前身与痛点
                                                                                                                                                                                                                                                                    • 1.2 同期方案对比
                                                                                                                                                                                                                                                                    • 1.3 一句话定位
                                                                                                                                                                                                                                                                  • 0x02. 原理讲解
                                                                                                                                                                                                                                                                    • 2.1 直觉类比
                                                                                                                                                                                                                                                                    • 2.2 准专业水平视角
                                                                                                                                                                                                                                                                    • 2.3 专家视角
                                                                                                                                                                                                                                                                  • 0x03 架构
                                                                                                                                                                                                                                                                    • 3.1 类与职责
                                                                                                                                                                                                                                                                    • 3.2 详细架构
                                                                                                                                                                                                                                                                    • 3.3 依赖图(谁用谁)
                                                                                                                                                                                                                                                                    • 3.4 数据流(前向,tensor 生命周期)
                                                                                                                                                                                                                                                                    • 3.5 执行流(forward 步骤细节)
                                                                                                                                                                                                                                                                    • 3.6 关键类/函数速查表
                                                                                                                                                                                                                                                                    • 3.7 宽分离(shared 全宽 / routed 窄宽)如何做到
                                                                                                                                                                                                                                                                  • 0x04. 子知识点深度分析
                                                                                                                                                                                                                                                                    • 4.1 总体结构与共享抽象
                                                                                                                                                                                                                                                                    • 4.2 子知识点拆解(依赖树)
                                                                                                                                                                                                                                                                    • 4.3 子知识点 1:SiTU-GLU(有界激活)
                                                                                                                                                                                                                                                                    • 4.4 子知识点 2:RMSNorm Before Up(尺度稳定)
                                                                                                                                                                                                                                                                    • 4.5 子知识点 3:Quantile Balancing(无辅助负载均衡)
                                                                                                                                                                                                                                                                    • 4.6 子知识点 5:其他稳定性 / 工程细节
                                                                                                                                                                                                                                                                    • 4.7 计算复杂度
                                                                                                                                                                                                                                                                  • 0x05 验证实验
                                                                                                                                                                                                                                                                  • 附录A. MoE实现
                                                                                                                                                                                                                                                                    • A.1 GroupedExperts
                                                                                                                                                                                                                                                                    • A.2 Output
                                                                                                                                                                                                                                                                    • A.3 StableLatentMoE
                                                                                                                                                                                                                                                                  • 附录B. Quantile Balancing
                                                                                                                                                                                                                                                                    • B.1 三视角解读
                                                                                                                                                                                                                                                                    • B.2 架构
                                                                                                                                                                                                                                                                    • B.3 实现
                                                                                                                                                                                                                                                                    • B.4 深入分析
                                                                                                                                                                                                                                                                    • B.5 逐专家 sigmoid vs softmax:为何 sigmoid 更好
                                                                                                                                                                                                                                                                    • B.6 样例
                                                                                                                                                                                                                                                                  • 0xFF 参考

                                                                                                                                                                                                                                                                  0x00 概要

                                                                                                                                                                                                                                                                  原始论文

                                                                                                                                                                                                                                                                  • 主论文:Kimi K3 Technical Report(月之暗面 Kimi K3,2026)。

                                                                                                                                                                                                                                                                  关键信息补齐

                                                                                                                                                                                                                                                                  • LatentMoE 并非 K3 原创,论文自引《LatentMoE: Toward Optimal Accuracy per FLOP and Parameter in Mixture of Experts》(arXiv 2601.18089)。

                                                                                                                                                                                                                                                                  • 无辅助损失负载均衡的"分配/分位数"思想,来自苏剑林《MoE 环游记》系列与 K2 的 Loss-Free 均衡——两者都是 K3 Quantile Balancing 的直接前身与贡献者。

                                                                                                                                                                                                                                                                  注:

                                                                                                                                                                                                                                                                  • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

                                                                                                                                                                                                                                                                  • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

                                                                                                                                                                                                                                                                  • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

                                                                                                                                                                                                                                                                  • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

                                                                                                                                                                                                                                                                  • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

                                                                                                                                                                                                                                                                  • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

                                                                                                                                                                                                                                                                  • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                                                                                                                                                                  • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。


                                                                                                                                                                                                                                                                  0x01. 演进脉络与定位

                                                                                                                                                                                                                                                                  1.1 前身与痛点

                                                                                                                                                                                                                                                                  本知识点由标准稀疏 MoE(Top-K)演化而来。标准实现如下:

                                                                                                                                                                                                                                                                    y = Σ_{e ∈ topk_k(x)} softmax(s)[e] · FFN_e(x)

                                                                                                                                                                                                                                                                    它在本知识点语境下暴露的痛点:

                                                                                                                                                                                                                                                                    痛点

                                                                                                                                                                                                                                                                    说明

                                                                                                                                                                                                                                                                    通信/权重流量随路由倍数放大

                                                                                                                                                                                                                                                                    每个被选中专家接收完整 d 维 token,路由 token 越多带宽消耗越大。

                                                                                                                                                                                                                                                                    数值失稳

                                                                                                                                                                                                                                                                    专家层内 W_gate·x 与 W_up·x 两组无界乘法,同一 token 激活同向对齐时形成 O(‖x‖⁴) 离群点,fp8 下直接溢出。

                                                                                                                                                                                                                                                                    负载失衡

                                                                                                                                                                                                                                                                    无法平衡 10² 量级越级专家;传统 Loss-Free 定长步长更新在专家多时收敛慢。

                                                                                                                                                                                                                                                                    无效算力

                                                                                                                                                                                                                                                                    896 个专家但每 token 只取队 16 个s,不压缩 latent 时专家核心宽度仍 = 模型宽度 d,全部专家 FLOP 仍随 d 线性扩展。

                                                                                                                                                                                                                                                                    1.2 同期方案对比

                                                                                                                                                                                                                                                                    方案

                                                                                                                                                                                                                                                                    核心机制

                                                                                                                                                                                                                                                                    优势

                                                                                                                                                                                                                                                                    劣势

                                                                                                                                                                                                                                                                    标准 TopK MoE(Mixtral/Qwen-MoE)

                                                                                                                                                                                                                                                                    softmax 门控 + topk + SwiGLU 专家

                                                                                                                                                                                                                                                                    简单、生态成熟

                                                                                                                                                                                                                                                                    专家宽=d、参数量随 topk 放大、激活无界

                                                                                                                                                                                                                                                                    LatentMoE(Latent)

                                                                                                                                                                                                                                                                    down→topk→up 潜空间专家

                                                                                                                                                                                                                                                                    同 FLOP/参数下效果更好

                                                                                                                                                                                                                                                                    4 个矩阵连乘形成病态链,训练不稳定

                                                                                                                                                                                                                                                                    Stable LatentMoE(K3)

                                                                                                                                                                                                                                                                    潜空间 + RMSNorm 前置 + SiTU-GLU + QB

                                                                                                                                                                                                                                                                    稳定 + 效果好 + 稀疏 56

                                                                                                                                                                                                                                                                    3 处稳定性修正,实现略复杂

                                                                                                                                                                                                                                                                    DeepSeek-V4 类

                                                                                                                                                                                                                                                                    MLA + 压缩注意力 + SwiGLU

                                                                                                                                                                                                                                                                    稳健,扎实

                                                                                                                                                                                                                                                                    与 K3 路线不同,仅参考对比

                                                                                                                                                                                                                                                                    1.3 一句话定位

                                                                                                                                                                                                                                                                    区别于"全宽专家 + softmax 门控"的标准 MoE,K3 通过下潜 → 稀疏路由 → 上潜把专家算力落到潜空间,并叠加 RMSNorm 稳定化、SiTU-GLU 有界激活、Quantile Balancing 分位数均衡 三个小改动,实现 896 路选 16(稀疏 56)且全程稳定、无辅助 loss 的负载均衡。


                                                                                                                                                                                                                                                                    0x02. 原理讲解

                                                                                                                                                                                                                                                                    2.1 直觉类比

                                                                                                                                                                                                                                                                    想象一家拥有 896 位专家的"咨询中心"。每次来一位客人,若每位专家都收到客人的完整档案(全宽 d 维),成本暴涨。Stable LatentMoE 的做法:门口接笔人(W_down 下投影)先把客人的诉求浓缩成一张"概要卡"(潜宽 l),只把卡片交给(最对口的 few 位专家看(路由 topk),专家的答复再由汇总员(W_up 上投影)翻译回完整档案输出。

                                                                                                                                                                                                                                                                    同时设三条"护栏"防止中心被少数热专家挤爆:

                                                                                                                                                                                                                                                                    1. 汇总员先把各专家答复按标准模板(RMSNorm)统一口径再翻回;

                                                                                                                                                                                                                                                                    2. 专家答复里加一个可调的"安全阀"(SiTU 有界激活)限制单次最大幅度;

                                                                                                                                                                                                                                                                    3. 定期统计每位专家接待量,直接用统计学把偏热专家的门槛抬高、偏冷专家的门槛拉低——不靠痛苦试错,一步校准到目标负载。

                                                                                                                                                                                                                                                                    2.2 准专业水平视角

                                                                                                                                                                                                                                                                    记 token 为 x ∈ ℝ^d,d=4096(K3 实际配置),潜宽 l=3584。

                                                                                                                                                                                                                                                                    • 路径:

                                                                                                                                                                                                                                                                      • W_down: ℝ^d → ℝ^l 下潜投影;

                                                                                                                                                                                                                                                                      • 打分 s = σ(W_r · x)(逐专家 sigmoid,非 softmax);

                                                                                                                                                                                                                                                                      • 选择 T = argtopk_k(s + b)(b 为逐专家 bias,只参与选择、不参与权重);

                                                                                                                                                                                                                                                                      • 权重 p_i = s_i / Σ_{j∈T} s_j 对选中 k 个内部归一;

                                                                                                                                                                                                                                                                      • 被选专家做潜空间 FFN,得 u ∈ ℝ^l;

                                                                                                                                                                                                                                                                      • u 先过 RMSNorm,再由 W_up: ℝ^l → ℝ^d 上潜投影。

                                                                                                                                                                                                                                                                      1. 共享专家路径:全宽 SiTU-GLU FFN,n_shared=2 个恒参与;

                                                                                                                                                                                                                                                                      2. 路由专家路径:

                                                                                                                                                                                                                                                                    • 最终输出(Eq. 11, 12):

                                                                                                                                                                                                                                                                      y = Σ_{j=1}^{n_shared} FFN_j(x) + W_up · RMSNorm(Σ_{i∈T} p_i · E_i(latent))

                                                                                                                                                                                                                                                                      与标准 MoE 的公式级对比:

                                                                                                                                                                                                                                                                      维度

                                                                                                                                                                                                                                                                      标准 MoE

                                                                                                                                                                                                                                                                      Stable LatentMoE

                                                                                                                                                                                                                                                                      专家核心宽

                                                                                                                                                                                                                                                                      d

                                                                                                                                                                                                                                                                      l<d

                                                                                                                                                                                                                                                                      激活

                                                                                                                                                                                                                                                                      SwiGLU:x·SiLU(x),无上界

                                                                                                                                                                                                                                                                      SiTU-GLU,全局 ≤100

                                                                                                                                                                                                                                                                      权重

                                                                                                                                                                                                                                                                      softmax 全专家耦合

                                                                                                                                                                                                                                                                      sigmoid 解耦 + 块内归一

                                                                                                                                                                                                                                                                      偏置

                                                                                                                                                                                                                                                                      辅助 loss / 固定步长

                                                                                                                                                                                                                                                                      QB 分位数一步到位

                                                                                                                                                                                                                                                                      输出稳定

                                                                                                                                                                                                                                                                      无

                                                                                                                                                                                                                                                                      RMSNorm(latent 聚合) 后过 W_up

                                                                                                                                                                                                                                                                      2.3 专家视角

                                                                                                                                                                                                                                                                      1. 为什么潜空间化能显著断提升效率:专家从"满宽函数"缩为"潜空间函数",参数量与每 FLOP 大幅下降(latent_dim=3584 < d=4096)。

                                                                                                                                                                                                                                                                      2. 为什么"4 个矩阵连乘"会不稳定:latent 路径 ≈ W_down · E(·) · W_up,连续多仿射矩阵相乘,初始权重随机独立时中间因子可能被意外放大,链上输出尺度失控。RMSNorm 将 W_up 之前的中间因子拉回单位刻度,使 W_up 输入不依赖"路由选谁"与"加权权重"。

                                                                                                                                                                                                                                                                      3. QB 的理论定位:QB 是最优均衡指派 LP 的对偶问题的坐标最小化解,因而无需学习率——不是梯度下降,一步精确读取(k+1)-th cut 与分位数即可。业界称为 loss-free + loss-less 新一代均衡器。论文未解决的问题:直方图近似误差与 expert/token 数的关系(K3 经验选 1000 bins)。


                                                                                                                                                                                                                                                                      0x03 架构

                                                                                                                                                                                                                                                                      3.1 类与职责

                                                                                                                                                                                                                                                                      类与职责
                                                                                                                                                                                                                                                                      类与职责

                                                                                                                                                                                                                                                                      3.2 详细架构

                                                                                                                                                                                                                                                                      详细架构
                                                                                                                                                                                                                                                                      详细架构

                                                                                                                                                                                                                                                                        关键张量维度:
                                                                                                                                                                                                                                                                          flat   (bt, d)      latent (bt, l)       rows  (bt·k, l)   out (bt·k, l)
                                                                                                                                                                                                                                                                          u      (bt, l)      W_down (d, l)         W_up  (l, d)     权重: (E,l,H)x3


                                                                                                                                                                                                                                                                        各组件超参(MoEConfig 默认 config.py:58-70):
                                                                                                                                                                                                                                                                          n_routed=896  n_shared=2  top_k=16  latent_dim=3584  expert_hidden=3072
                                                                                                                                                                                                                                                                          shared_hidden=3072  situ_beta_gate=4.0  situ_beta_up=25.0
                                                                                                                                                                                                                                                                          rmsnorm_before_up=True  qb_enabled=True  bins=1000  ema=0.0

                                                                                                                                                                                                                                                                        3.3 依赖图(谁用谁)

                                                                                                                                                                                                                                                                        依赖图
                                                                                                                                                                                                                                                                        依赖图

                                                                                                                                                                                                                                                                        依赖本质:StableLatentMoE 是组合根 —— 它聚合 (router, down, experts, norm, up, shared);这些叶子模块彼此 不互相依赖(只有外层单点)。

                                                                                                                                                                                                                                                                        3.4 数据流(前向,tensor 生命周期)

                                                                                                                                                                                                                                                                          x (b,t,d)
                                                                                                                                                                                                                                                                           └→ flatten (bt,d)
                                                                                                                                                                                                                                                                           ·→ 两路 fork
                                                                                                                                                                                                                                                                           │  L: router(flat) → scores (bt,E), indices (bt,16), weights (bt,16), cutoff
                                                                                                                                                                                                                                                                           │  R: down_proj(flat) = latent (bt,l)
                                                                                                                                                                                                                                                                           └→  merge  @ rows
                                                                                                                                                                                                                                                                                rows = t.repeat_interleave(16) → latent[rows] (bt·16, l)
                                                                                                                                                                                                                                                                                expert_ids = indices.ravel → forward_indexed
                                                                                                                                                                                                                                                                                      ↓
                                                                                                                                                                                                                                                                                 out (bt·16, l)
                                                                                                                                                                                                                                                                                 ↓  ×weights →  index_add → u (bt, l)
                                                                                                                                                                                                                                                                                 ↓
                                                                                                                                                                                                                                                                                 latent_norm(u) (bt, l)
                                                                                                                                                                                                                                                                                 ↓
                                                                                                                                                                                                                                                                                 up_proj → y (bt, d)
                                                                                                                                                                                                                                                                                 ↓
                                                                                                                                                                                                                                                                                 + shared Σ (flat) → y (bt, d)   (moe.py:306-308)
                                                                                                                                                                                                                                                                                 ↓
                                                                                                                                                                                                                                                                                 reshape (b,t,d) + outgoing MoEOutput(hidden, router)

                                                                                                                                                                                                                                                                          3.5 执行流(forward 步骤细节)

                                                                                                                                                                                                                                                                            StableLatentMoE.forward(x)
                                                                                                                                                                                                                                                                              │ 1. x.flatten → flat                      (moe.py:291-292)
                                                                                                                                                                                                                                                                              │ 2. route = self.router(flat)             (294)
                                                                                                                                                                                                                                                                              │      ├─ QB 训练时在内部 _accumulate(见 §9 执行流)
                                                                                                                                                                                                                                                                              │ 3. latent = down_proj(flat)              (295)  d→l
                                                                                                                                                                                                                                                                              │ 4. rows = repeat_interleave(k)           (298)
                                                                                                                                                                                                                                                                              │      expert_ids = route.indices.ravel    (299)
                                                                                                                                                                                                                                                                              │ 5. expert_out = experts.forward_indexed( latent[rows], expert_ids )  (302)
                                                                                                                                                                                                                                                                              │ ─ 内部 sorted/counts/loop 见下
                                                                                                                                                                                                                                                                              │ 6. u = zeros; u.index_add_(rows, p·out)  (303-304)
                                                                                                                                                                                                                                                                              │ 7. y = up_proj(latent_norm(u))            (306)
                                                                                                                                                                                                                                                                              │ 8. for e in shared: y += e(flat)          (307-308)
                                                                                                                                                                                                                                                                              │ 9. MoEOutput(y.view(b,t,d), route)         (309)

                                                                                                                                                                                                                                                                            3.6 关键类/函数速查表

                                                                                                                                                                                                                                                                            类/函数

                                                                                                                                                                                                                                                                            作用一句话

                                                                                                                                                                                                                                                                            MoEOutput

                                                                                                                                                                                                                                                                            形状化返回(hidden + router 元数据)

                                                                                                                                                                                                                                                                            DenseFFN

                                                                                                                                                                                                                                                                            dense 前缀的全宽 FFN(无路由)

                                                                                                                                                                                                                                                                            GroupedExperts

                                                                                                                                                                                                                                                                            896 专家打成 gate/up/down 三张权重,支持 grouped GEMM

                                                                                                                                                                                                                                                                            GroupedExperts.forward_indexed

                                                                                                                                                                                                                                                                            行按专家分组排序→各段 dense→回填(性能关键路径)

                                                                                                                                                                                                                                                                            GroupedExperts.forward_all

                                                                                                                                                                                                                                                                            全专家计算每个 token(oracle,仅供测试与小 cfg)

                                                                                                                                                                                                                                                                            StableLatentMoE

                                                                                                                                                                                                                                                                            组合根:路由+潜空间+专家+norm+共享

                                                                                                                                                                                                                                                                            StableLatentMoE.forward

                                                                                                                                                                                                                                                                            正式数据流(§8.3)

                                                                                                                                                                                                                                                                            QuantileBalancingRouter

                                                                                                                                                                                                                                                                            打分→Top-(k+1)→权重→QB 直方图

                                                                                                                                                                                                                                                                            SiTUGLU

                                                                                                                                                                                                                                                                            有界 GLU 模块(可独立用)

                                                                                                                                                                                                                                                                            依赖方向总结:DenseFFN/GroupedExperts → situ_glu.situ_glu 功能性依赖;StableLatentMoE → router/down/norm/experts/shared 组合依赖;无回环。

                                                                                                                                                                                                                                                                            3.7 宽分离(shared 全宽 / routed 窄宽)如何做到

                                                                                                                                                                                                                                                                            两条并行的"任务管线"

                                                                                                                                                                                                                                                                            关键在 他们将两个宽度硬编码成独立路径,互不建立 scale 耦合:

                                                                                                                                                                                                                                                                            任务管线
                                                                                                                                                                                                                                                                            任务管线

                                                                                                                                                                                                                                                                            "如何做到"的三个机制

                                                                                                                                                                                                                                                                            1. 维度由出参决定,不共享张量:

                                                                                                                                                                                                                                                                              • shared 的 SiTUGLU 宽度 = (dim=d, hidden=shared_hidden)(moe.py:269-273)

                                                                                                                                                                                                                                                                              • routed 的 GroupedExperts 宽度 = (dim_in=l, hidden=expert_hidden, dim_out=l)(moe.py:261-268)

                                                                                                                                                                                                                                                                              • 两组参数内存完全独立,唯一的接点是最终 y = y + shared(flat) 的加法。

                                                                                                                                                                                                                                                                            2. 路由降维投影只施加在 routed 支路;shared 支路直接吃原始 flat(moe.py:308 expert(flat))。

                                                                                                                                                                                                                                                                            3. scale 解耦靠的是除法 + 独立初始化:

                                                                                                                                                                                                                                                                              • 路由支亮度加权后经 latent_norm(RMSNorm)再进 W_up(moe.py:306);

                                                                                                                                                                                                                                                                              • shared 支路不乘任何路由,天然稳定;

                                                                                                                                                                                                                                                                              • 两路输出相加,scale 各自受控 → 不会一边 10⁴ 一边 10⁻⁴。

                                                                                                                                                                                                                                                                            为什么这能"不爆炸"

                                                                                                                                                                                                                                                                            K3 的 896 专家 + 16 激活 = 稀疏 56。若 all experts 都是全宽 FFN(d→H→d),每 token 要广播 16× d-维输入给专家且所有专家的 FLOP 都按 d 展开。

                                                                                                                                                                                                                                                                            LatentMoE 把活跃专家的输入/输出降到 l=3584,乘以 16 的路由扩量也仍在 l 带宽内(而非 d)。这正是论文 §2.2 的"width-separation"的收益构成。


                                                                                                                                                                                                                                                                            0x04. 子知识点深度分析

                                                                                                                                                                                                                                                                            4.1 总体结构与共享抽象

                                                                                                                                                                                                                                                                            • 符号:N tokens,d 模型维度,l latent 宽,k=topk,n = n_shared + n_routed。

                                                                                                                                                                                                                                                                            • 抽象之一"宽分离":共享专家全宽 + 路由专家窄宽,互不影响 — 这样 routed 数可涨到 896 而不爆炸。

                                                                                                                                                                                                                                                                            • 抽象之二"路由 bias 与权重解耦":b 只进选择(推断 topk)不进权重(renormalize 的自带分数),这是 QB 思想的实现基础。

                                                                                                                                                                                                                                                                            4.2 子知识点拆解(依赖树)

                                                                                                                                                                                                                                                                              StableLatentMoE (moe.py:231 class, forward:279)
                                                                                                                                                                                                                                                                                  ├── 共享专家路径                       (moe.py:259-267, n_shared 个 SiTU-GLU)
                                                                                                                                                                                                                                                                                  ├── 下潜投影 W_down                    (moe.py:238 nn.Linear(d, l, bias=False))
                                                                                                                                                                                                                                                                                  ├── 路由系统 QuantileBalancingRouter   (router_qb.py:123 class)
                                                                                                                                                                                                                                                                                  │   ├── 打分 sigmoid(W_r x)            (router_qb.py:167)
                                                                                                                                                                                                                                                                                  │   ├── top-(k+1) 与 cutoff            (router_qb.py:170-131)
                                                                                                                                                                                                                                                                                  │   ├── Renormalize weights            (router_qb.py:132-135)
                                                                                                                                                                                                                                                                                  │   └── QB 均衡
                                                                                                                                                                                                                                                                                  │       ├── exact Eq.14                (router_qb.py:287 update_bias_exact)
                                                                                                                                                                                                                                                                                  │       ├── histogram(bin 直方图)     (router_qb.py:198-232 _accumulate/update_bias)
                                                                                                                                                                                                                                                                                  │       └── 负载统计指标               (router_qb.py:301 load_balance_stats)
                                                                                                                                                                                                                                                                                  ├── 路由专家 GroupedExperts             (moe.py:101-228)
                                                                                                                                                                                                                                                                                  │   ├── gate / up / down 三组权重       (moe.py:116-128)
                                                                                                                                                                                                                                                                                  │   ├── forward_indexed 分调度          (moe.py:162)
                                                                                                                                                                                                                                                                                  │   └── SiTU-GLU 主循环                 (moe.py:183-207 / situ_glu.py)
                                                                                                                                                                                                                                                                                  ├── RMSNorm 稳定化                      (moe.py:240-242 latent_norm)
                                                                                                                                                                                                                                                                                  ├── W_up 上潜投影                       (moe.py:238-243)
                                                                                                                                                                                                                                                                                  └── MoEOutput 封装                      (moe.py:70-80 class)

                                                                                                                                                                                                                                                                              依赖关系:

                                                                                                                                                                                                                                                                              • GroupedExperts 依赖 situ_glu.situ_glu;

                                                                                                                                                                                                                                                                              • router 输出的 indices/weights 决定 GroupedExperts 的 dispatch;

                                                                                                                                                                                                                                                                              • latent_norm 依赖 modules.norm.RMSNorm;

                                                                                                                                                                                                                                                                              • config.MoEConfig 提供全部超参(n_routed=896、n_shared=2、top_k=16、latent_dim=3584、qb_bins=1000 等)。

                                                                                                                                                                                                                                                                              对照实现:

                                                                                                                                                                                                                                                                              • kimi3-master/kimi3/modules/moe.py 及 router_qb.py(本项目镜像源)

                                                                                                                                                                                                                                                                              • kimi-k3-pytorch-main/src/stable_latent_moe/*(模块化参考)

                                                                                                                                                                                                                                                                              • sglang-.../srt/models/inkling_common/moe.py(SGLang 生产形态)

                                                                                                                                                                                                                                                                              具体如下表所示。

                                                                                                                                                                                                                                                                              环节

                                                                                                                                                                                                                                                                              本项目

                                                                                                                                                                                                                                                                              kimi-k3-pytorch

                                                                                                                                                                                                                                                                              SGLang

                                                                                                                                                                                                                                                                              专家组织

                                                                                                                                                                                                                                                                              GroupedExperts 三组权重

                                                                                                                                                                                                                                                                              独立 Expert list

                                                                                                                                                                                                                                                                              FusedMoE(E 融合)

                                                                                                                                                                                                                                                                              门控

                                                                                                                                                                                                                                                                              sigmoid + topk

                                                                                                                                                                                                                                                                              TopKRouter

                                                                                                                                                                                                                                                                              InklingGate

                                                                                                                                                                                                                                                                              权重

                                                                                                                                                                                                                                                                              selected 内 renorm

                                                                                                                                                                                                                                                                              renorm

                                                                                                                                                                                                                                                                              logsigmoid renorm

                                                                                                                                                                                                                                                                              均衡

                                                                                                                                                                                                                                                                              histogram + exact

                                                                                                                                                                                                                                                                              Histogram/Exact

                                                                                                                                                                                                                                                                              训练用 /(推理冻结)

                                                                                                                                                                                                                                                                              latent

                                                                                                                                                                                                                                                                              down/up 保留

                                                                                                                                                                                                                                                                              保留

                                                                                                                                                                                                                                                                              无(flat + shared sink)

                                                                                                                                                                                                                                                                              SGLang 生产形态为"双层无 latent"(看 inkling_common/moe.py),与论文"latent 压缩"存在差异。这解释了生产与教学实现的差异:教学保持论文式 latent 压缩便于抽象展示;SGLang 变体则贴近 kernel 轻量化。

                                                                                                                                                                                                                                                                              差异原因:数组 kernel 化后 flat 让 BW/permute 更高效,代价是不再用 latent。

                                                                                                                                                                                                                                                                              4.3 子知识点 1:SiTU-GLU(有界激活)

                                                                                                                                                                                                                                                                              原理:

                                                                                                                                                                                                                                                                              • SwiGLU 的乘法器无界(W_gate·x 与 W_up·x 同时越级放大 → O(‖x‖⁴) 离群)。

                                                                                                                                                                                                                                                                              • SiTU 在乘积前对路与线性分支同时做 softcap。

                                                                                                                                                                                                                                                                              • 数学形态:SiTU(x) = β·tanh(x/β) · σ(x)(β=4 时与 SigLU 形式一致,但侧重点在"有界"而非"一致")。

                                                                                                                                                                                                                                                                              • K3 实际更强:SiTU-GLU = σ(gate) · softcap(gate, β₁) · softcap(up, β₂),β₁=4、β₂=25 → 全局 ≤ β₁·β₂ = 100。

                                                                                                                                                                                                                                                                              对比基线:

                                                                                                                                                                                                                                                                              维度

                                                                                                                                                                                                                                                                              标准 SwiGLU

                                                                                                                                                                                                                                                                              SiTU-GLU

                                                                                                                                                                                                                                                                              数值上界

                                                                                                                                                                                                                                                                              无界

                                                                                                                                                                                                                                                                              ≤100

                                                                                                                                                                                                                                                                              稳定性

                                                                                                                                                                                                                                                                              差(fp8 溢出)

                                                                                                                                                                                                                                                                              好(处处有界)

                                                                                                                                                                                                                                                                              梯度

                                                                                                                                                                                                                                                                              可在边界处骤减

                                                                                                                                                                                                                                                                              softcap 处处可导

                                                                                                                                                                                                                                                                              demo 实测(scale=8):SwiGLU 输出 max=50.0,SiTU-GLU 输出 max=21.3(有界有效)。

                                                                                                                                                                                                                                                                              4.3.1 实现

                                                                                                                                                                                                                                                                              具体代码如下:

                                                                                                                                                                                                                                                                                # -*- coding: utf-8 -*-
                                                                                                                                                                                                                                                                                """Sigmoid Tanh Unit GLU(SiTU-GLU)激活,K3 技术报告 §2.3.2 / 附录 B。


                                                                                                                                                                                                                                                                                背景:SwiGLU(``silu(x) * x``,LLaMA 系默认)的两个因子都是**无界**的。在 MoE
                                                                                                                                                                                                                                                                                这种极宽网络里,gate 与 up 的投影坐标常同时落在很大的数值上,二者的乘积会产生
                                                                                                                                                                                                                                                                                激活离群点(outlier),进而在低精度(FP8/BF16)下溢出或严重损失精度 —— 这是
                                                                                                                                                                                                                                                                                K3 用 FP8 做专家推理时最头疼的数值问题之一。


                                                                                                                                                                                                                                                                                SiTU-GLU 的解决思路是给两个因子分别套一个**平滑的软截断**:
                                                                                                                                                                                                                                                                                ``softcap(z, beta) = beta * tanh(z / beta)``,即


                                                                                                                                                                                                                                                                                    SiTU-GLU(g, u) = [beta_g * tanh(g/beta_g) * sigmoid(g)] * [beta_u * tanh(u/beta_u)]
                                                                                                                                                                                                                                                                                                        └────── 门分支(gate)──────┘             └──── up 分支 ────┘


                                                                                                                                                                                                                                                                                核心性质(附录 B):
                                                                                                                                                                                                                                                                                - 有界:``|SiTU-GLU(x)| <= beta_g * beta_u``。论文取 ``beta_g=4, beta_u=25``,
                                                                                                                                                                                                                                                                                  于是上界恰为 100 —— 这个数特意选得**小于 FP8 E4M3 的表示上限(448)**,保证
                                                                                                                                                                                                                                                                                  FP8 激活不会溢出。
                                                                                                                                                                                                                                                                                - 原点近似恒等:``tanh(z) = z - z^3/3 + ...``,故 ``beta*tanh(z/beta) = z - z^3/(3*beta^2)``,
                                                                                                                                                                                                                                                                                  到一阶与 SwiGLU 一致(``|x| <= beta1*beta2`` 附近都匹配 SwiGLU 的形状)。
                                                                                                                                                                                                                                                                                - 光滑可导:相比硬 clamp(``torch.clamp``),softcap 在饱和区仍有非零梯度
                                                                                                                                                                                                                                                                                  (``tanh' > 0``),不会把梯度完全掐断,训练更稳。
                                                                                                                                                                                                                                                                                - 门分支保留 sigmoid:sigmoid 负责把负响应压向 0(像 Swish 一样),softcap 只负责
                                                                                                                                                                                                                                                                                  限制大的正激活 —— 二者叠加既保留了 Swish 的稀疏性,又加上了有界性。


                                                                                                                                                                                                                                                                                与 SGLang 的对应:SGLang 把 `beta*tanh(g/beta)*sigmoid(g)` 与 `beta_u*tanh(u/beta_u)`
                                                                                                                                                                                                                                                                                融合进单个 CUDA kernel ``situ_and_mul``(``kernels/jit/csrc/kimi_k3/situ_and_mul.cuh``),
                                                                                                                                                                                                                                                                                输入 ``[*, 2D]``(前半 gate、后半 up),一次遍历输出 ``[*, D]``;FP8 变体正是
                                                                                                                                                                                                                                                                                利用上述有界性(``|输出| < FP8_E4M3_MAX``)省去了额外的 swiglu_limit clamp。
                                                                                                                                                                                                                                                                                """


                                                                                                                                                                                                                                                                                def softcap(x: Tensor, beta: float) -> Tensor:
                                                                                                                                                                                                                                                                                    """``beta * tanh(x / beta)`` —— 光滑、以 ``beta`` 为上界、原点附近近似恒等。


                                                                                                                                                                                                                                                                                    当 ``|x|`` 很小:``softcap(x) ≈ x``;当 ``|x| -> inf``:``softcap(x) -> ±beta``。
                                                                                                                                                                                                                                                                                    """
                                                                                                                                                                                                                                                                                    return beta * torch.tanh(x / beta)



                                                                                                                                                                                                                                                                                def situ_glu(gate: Tensor, up: Tensor, beta_gate: float, beta_up: float) -> Tensor:
                                                                                                                                                                                                                                                                                    """对 gate/up 预激活施加 SiTU-GLU(Eq. 12)。


                                                                                                                                                                                                                                                                                    - ``gate`` 分支:``softcap(gate, beta_gate) * sigmoid(gate)``(有界 Swish);
                                                                                                                                                                                                                                                                                    - ``up`` 分支:``softcap(up, beta_up)``(有界线性因子)。
                                                                                                                                                                                                                                                                                    """
                                                                                                                                                                                                                                                                                    return softcap(gate, beta_gate) * torch.sigmoid(gate) * softcap(up, beta_up)



                                                                                                                                                                                                                                                                                class SiTUGLU(nn.Module):
                                                                                                                                                                                                                                                                                    """使用 SiTU-GLU 的门控前馈网络(FFN/MoE 专家)。


                                                                                                                                                                                                                                                                                    结构与其他 GLU FFN 一致:``down(situ_glu(gate(x), up(x)))``。
                                                                                                                                                                                                                                                                                    ``dim_out`` 默认等于 ``dim_in``;StableLatentMoE 的路由专家用它做"潜空间窄宽"
                                                                                                                                                                                                                                                                                    (``latent_dim -> expert_hidden -> latent_dim``),共享专家则用模型全宽。
                                                                                                                                                                                                                                                                                    ``beta_gate / beta_up`` 为不可学习的常量(来自 MoEConfig,默认 4.0 / 25.0)。
                                                                                                                                                                                                                                                                                    """


                                                                                                                                                                                                                                                                                    def __init__(
                                                                                                                                                                                                                                                                                        self,
                                                                                                                                                                                                                                                                                        dim_in: int,
                                                                                                                                                                                                                                                                                        hidden: int,
                                                                                                                                                                                                                                                                                        dim_out: int | None = None,
                                                                                                                                                                                                                                                                                        *,
                                                                                                                                                                                                                                                                                        beta_gate: float = 4.0,
                                                                                                                                                                                                                                                                                        beta_up: float = 25.0,
                                                                                                                                                                                                                                                                                        bias: bool = False,
                                                                                                                                                                                                                                                                                    ):
                                                                                                                                                                                                                                                                                        super().__init__()
                                                                                                                                                                                                                                                                                        dim_out = dim_out if dim_out is not None else dim_in
                                                                                                                                                                                                                                                                                        self.beta_gate = beta_gate
                                                                                                                                                                                                                                                                                        self.beta_up = beta_up
                                                                                                                                                                                                                                                                                        self.gate_proj = nn.Linear(dim_in, hidden, bias=bias)   # W_g:门预激活
                                                                                                                                                                                                                                                                                        self.up_proj = nn.Linear(dim_in, hidden, bias=bias)     # W_u:up 预激活
                                                                                                                                                                                                                                                                                        self.down_proj = nn.Linear(hidden, dim_out, bias=bias)  # W_o:输出投影


                                                                                                                                                                                                                                                                                    def forward(self, x: Tensor) -> Tensor:
                                                                                                                                                                                                                                                                                        return self.down_proj(
                                                                                                                                                                                                                                                                                            situ_glu(self.gate_proj(x), self.up_proj(x), self.beta_gate, self.beta_up)
                                                                                                                                                                                                                                                                                        )


                                                                                                                                                                                                                                                                                    def extra_repr(self) -> str:
                                                                                                                                                                                                                                                                                        return f"beta_gate={self.beta_gate}, beta_up={self.beta_up}"



                                                                                                                                                                                                                                                                                class SwiGLU(nn.Module):
                                                                                                                                                                                                                                                                                    """SwiGLU 基线,仅用于驱动 SiTU-GLU 的消融对比(见 tests/math/test_situ_glu.py)。


                                                                                                                                                                                                                                                                                    与 SiTUGLU 参数结构完全相同,仅非线性不同:``silu(gate) * up``(无界)。
                                                                                                                                                                                                                                                                                    保留它是为了让"有界 vs 无界"的数值对比在同结构上公平进行。
                                                                                                                                                                                                                                                                                    """


                                                                                                                                                                                                                                                                                    def __init__(self, dim_in: int, hidden: int, dim_out: int | None = None, *, bias: bool = False):
                                                                                                                                                                                                                                                                                        super().__init__()
                                                                                                                                                                                                                                                                                        dim_out = dim_out if dim_out is not None else dim_in
                                                                                                                                                                                                                                                                                        self.gate_proj = nn.Linear(dim_in, hidden, bias=bias)
                                                                                                                                                                                                                                                                                        self.up_proj = nn.Linear(dim_in, hidden, bias=bias)
                                                                                                                                                                                                                                                                                        self.down_proj = nn.Linear(hidden, dim_out, bias=bias)


                                                                                                                                                                                                                                                                                    def forward(self, x: Tensor) -> Tensor:
                                                                                                                                                                                                                                                                                        return self.down_proj(F.silu(self.gate_proj(x)) * self.up_proj(x))

                                                                                                                                                                                                                                                                                4.3.2 softcap

                                                                                                                                                                                                                                                                                定义(situ_glu.py)

                                                                                                                                                                                                                                                                                  softcap(x, β) = β · tanh(x / β)
                                                                                                                                                                                                                                                                                  • 处处可导、光滑有界:|softcap| ≤ β

                                                                                                                                                                                                                                                                                  • 渐进线性:|x|≪β 时 softcap(x) ≈ x(保持 Swish 形态)

                                                                                                                                                                                                                                                                                  • 只要 β 有限就有硬上限 —— 即"有界激活"

                                                                                                                                                                                                                                                                                  在 SiTU-GLU 中的作用

                                                                                                                                                                                                                                                                                    SiTU-GLU(gate, up) = σ(gate) · softcap(gate, β_g) · softcap(up, β_u)

                                                                                                                                                                                                                                                                                    K3 参数 β_g=4.0, β_u=25.0 → 全局 |SiTU-GLU| ≤ 4×25 = 100。

                                                                                                                                                                                                                                                                                    为什么"有界"更好(vs SwiGLU / 硬截断)

                                                                                                                                                                                                                                                                                    SwiGLU:两个无界因子相乘 → O(‖x‖⁴) 离群点("同向大坐标对齐"场景),fp8 直接溢出。softcap 用硬界的 soft 形式替代硬截断:

                                                                                                                                                                                                                                                                                    特性

                                                                                                                                                                                                                                                                                    SwiGLU

                                                                                                                                                                                                                                                                                    硬截断 (clamp)

                                                                                                                                                                                                                                                                                    softcap(K3)

                                                                                                                                                                                                                                                                                    数值上界

                                                                                                                                                                                                                                                                                    无

                                                                                                                                                                                                                                                                                    有(截断点)

                                                                                                                                                                                                                                                                                    有(≤β)

                                                                                                                                                                                                                                                                                    单调性

                                                                                                                                                                                                                                                                                    单调

                                                                                                                                                                                                                                                                                    截断后平

                                                                                                                                                                                                                                                                                    单调(tanh)

                                                                                                                                                                                                                                                                                    导数

                                                                                                                                                                                                                                                                                    处处非零

                                                                                                                                                                                                                                                                                    截断点导数=0(卡死)

                                                                                                                                                                                                                                                                                    处处非零且平滑

                                                                                                                                                                                                                                                                                    fp8 友好

                                                                                                                                                                                                                                                                                    否

                                                                                                                                                                                                                                                                                    半(导数中断)

                                                                                                                                                                                                                                                                                    是(有界 + 连续)

                                                                                                                                                                                                                                                                                    "soft" 的关键:有界但不破坏梯度连续性(tanh' 永不触零),既防爆又在饱和区仍可学。这是它比"直接 clamp"更好的唯一原因;有界非线性还会带来"等效深度"的增益;后者无法用 clamp 得到。

                                                                                                                                                                                                                                                                                    4.4 子知识点 2:RMSNorm Before Up(尺度稳定)

                                                                                                                                                                                                                                                                                    动机:潜空间链路的中间输出 u 幅度随"路由选谁、加权大小"漂移;若直接过 W_up,输出 scale 不可预测。在 W_up 之前加 RMSNorm,把 u 归一为单位 RMS,W_up 输入即不可随机变大。

                                                                                                                                                                                                                                                                                    消融结论:RMSNorm 放在上潜之前才是本质必要;下潜前的 Norm 可省(down 输入端的 Hx 已被后续正常白处理)。

                                                                                                                                                                                                                                                                                    代码位置:moe.py(latent_norm,rmsnorm_before_up 开关默认 True)。

                                                                                                                                                                                                                                                                                    demo 实测:将 down 输出放大 50 倍——无 Norm 时输出 scale 也放大 50 倍;有 Norm 时输出保持 ≈1.0003。结论:一个 Norm + 固定 W_up scale 即可。

                                                                                                                                                                                                                                                                                    4.5 子知识点 3:Quantile Balancing(无辅助负载均衡)

                                                                                                                                                                                                                                                                                    4.5.1 原理:精确版

                                                                                                                                                                                                                                                                                    统计思想:

                                                                                                                                                                                                                                                                                      margin_ij = s_ij - α_i            (α_i 为 token i 将 (k+1)-th 选取出的 biased 分数)
                                                                                                                                                                                                                                                                                      b_hat_j   = -quantile_{1-k/n}(margin[:, j] )
                                                                                                                                                                                                                                                                                      b         = b_hat - mean(b_hat)

                                                                                                                                                                                                                                                                                      每个 token 有 k+1 个(biased)此前 k 个 / 1 个替换。选择 q = 1 - top_k / n。分位数恰好把每个 token 到"恰好到 k 个专家、实际 n-k 个落选"对齐。由于 b 是 buffer(detach),不干扰打分梯度。

                                                                                                                                                                                                                                                                                      4.5.2 Quantile Balancing 的核心

                                                                                                                                                                                                                                                                                      对于 Quantile Balancing,确定 bias 是手段,负载均衡才是目的;而"快速"只是表象,本质是"让 bias 成为负载均衡问题的一个精确解"。拆开看:

                                                                                                                                                                                                                                                                                      1. 为什么说"确定 bias 是手段":QB 真正要解决的是:896 个专家热度不均 → 冷门专家欠训练。bias 只是实现均衡的工具——通过 s + b 改变"谁被选中"(router_qb.py:168)。

                                                                                                                                                                                                                                                                                      2. 为什么说"快速"只是表象 :传统方法(辅助 loss / signSGD 固定步长)也调 bias,只是慢、有超参。QB 的核心突破不是"快",而是:

                                                                                                                                                                                                                                                                                      QB 的本质

                                                                                                                                                                                                                                                                                      含义

                                                                                                                                                                                                                                                                                      一步即最优解b*_j = quantile_{1-k/n}(r_{:,j})

                                                                                                                                                                                                                                                                                       是均衡匹配 LP 对偶的精确坐标极小化→ 无需学习率,不是"梯度步进",而是"直接读分位数"

                                                                                                                                                                                                                                                                                      目标是精确负载

                                                                                                                                                                                                                                                                                      分位数选取保证 load_j(b_j) = q = mk/n,不是"朝均衡挪一点"

                                                                                                                                                                                                                                                                                      可扩展

                                                                                                                                                                                                                                                                                      直方图计数可加 → 一次整数 all-reduce 得全局分布,通信 O(n·B) 与 token 数无关

                                                                                                                                                                                                                                                                                      3. 一句话总结 QB 的核心 = 把"负载均衡"从"调参/加损失"转写成"逐专家分位数估计"这一统计问题——于是得到一个无梯度、无超参、一步到位的精确 bias 解。"快速"是这个数学性质的副产品,不是目标本身。

                                                                                                                                                                                                                                                                                      所以更准确的说法:"QB 的核心是用分位数一步解出使负载精确均衡的 bias,而不是去学一个 bias。"

                                                                                                                                                                                                                                                                                      4.6 子知识点 5:其他稳定性 / 工程细节

                                                                                                                                                                                                                                                                                      • kimi-k3-pytorch 版提供 ExactQuantileBalancer/HistogramQuantileBalancer,与本项目 update_bias_exact/update_bias 一一对应。

                                                                                                                                                                                                                                                                                      • 训练形态:_accumulate 每 step 归集,optimizer 后调用 update_bias 一次;

                                                                                                                                                                                                                                                                                      • 推理形态:bias 冻结为 buffer,不打分。本任务不做推理运行态验证(GPU/性能校验不在本分析范围,标注「不在此任务内」)。

                                                                                                                                                                                                                                                                                      4.7 计算复杂度

                                                                                                                                                                                                                                                                                      • 每 token 路由 FLOPs ≈ d·l(下潜)+ k·l·hidden(路由专家)+ l·d(上潜)+ shared d·hidden;

                                                                                                                                                                                                                                                                                      • 对比纯 dense MLP 2·d·(4d),当 l≈3584、hidden≈3072、k=16 时节省约一个量级(省略具体两处数字空间);

                                                                                                                                                                                                                                                                                      • 内存额外仅 bias (E,) 与直方图 (E×B)。

                                                                                                                                                                                                                                                                                      0x05 验证实验

                                                                                                                                                                                                                                                                                      脚本 experiments/moe/demo_stable_latent_moe.py 四联图对应:

                                                                                                                                                                                                                                                                                      • (a) QB 前后各专家 token 负载柱状(负载均衡效果);

                                                                                                                                                                                                                                                                                      • (b) 精确分位数 vs 直方图分位数(标注 max diff);

                                                                                                                                                                                                                                                                                      • (c) SwiGLU vs SiTU-GLU 输出幅度随 scale 变化(有界性);

                                                                                                                                                                                                                                                                                      • (d) RMSNorm 尺度稳定性(放大 50x 前后对比)。

                                                                                                                                                                                                                                                                                      demo_stable_latent_moe
                                                                                                                                                                                                                                                                                      demo_stable_latent_moe

                                                                                                                                                                                                                                                                                      脚本 experiments/moe/demo_stable_latent_moe.py 四联图对应:

                                                                                                                                                                                                                                                                                      • 左上:LatentMoE 数据流架构图。

                                                                                                                                                                                                                                                                                      • 右上:width 分离的参数量 / FLOPs 节省(K3 真实配置)。

                                                                                                                                                                                                                                                                                      • 左下:稀疏度(n_routed/top_k)对计算量的影响。

                                                                                                                                                                                                                                                                                      • 右下:Dense warm-up + MoE body 层调度。

                                                                                                                                                                                                                                                                                      plot_moe_principle
                                                                                                                                                                                                                                                                                      plot_moe_principle

                                                                                                                                                                                                                                                                                      附录

                                                                                                                                                                                                                                                                                      附录A. MoE实现

                                                                                                                                                                                                                                                                                      A.1 GroupedExperts

                                                                                                                                                                                                                                                                                      源码

                                                                                                                                                                                                                                                                                        class GroupedExperts(nn.Module):
                                                                                                                                                                                                                                                                                            """``n`` SiTU-GLU experts stored as batched weights.


                                                                                                                                                                                                                                                                                            Keeping the experts as three stacked tensors rather than ``n`` modules is what
                                                                                                                                                                                                                                                                                            lets dispatch become a grouped GEMM -- the shape MoonEP schedules in phase 5.
                                                                                                                                                                                                                                                                                            """


                                                                                                                                                                                                                                                                                            # 【中文释义】GroupedExperts 把 n_routed 个专家"打包"成三块叠加权重张量:
                                                                                                                                                                                                                                                                                            #   - gate:(E, l, H)  —— 每个专家对潜向量做线性变换,作为 SiTU 门控的输入
                                                                                                                                                                                                                                                                                            #   - up:  (E, l, H)  —— 同源上分支,同样在潜空间 l 中
                                                                                                                                                                                                                                                                                            #   - down:(E, H, l)  —— 把专家内部宽度 H 投影回潜宽度 l
                                                                                                                                                                                                                                                                                            # 不把每个专家实现为独立 nn.Module 的目的:dispatch 可以变成「一次 grouped GEMM」
                                                                                                                                                                                                                                                                                            # 的形状(一次 matmul 覆盖所有被选中的专家),这正是 MoonEP(§5)在 EP 分布式
                                                                                                                                                                                                                                                                                            # 下调度 S×K token 到专家时使用的组织方式。CPU 教学实现里 forward_indexed 用
                                                                                                                                                                                                                                                                                            # 逐专家稠密 matmul + 排列替代,语义一致。
                                                                                                                                                                                                                                                                                            def __init__(
                                                                                                                                                                                                                                                                                                self,
                                                                                                                                                                                                                                                                                                n_experts: int,
                                                                                                                                                                                                                                                                                                dim_in: int,
                                                                                                                                                                                                                                                                                                hidden: int,
                                                                                                                                                                                                                                                                                                dim_out: int,
                                                                                                                                                                                                                                                                                                *,
                                                                                                                                                                                                                                                                                                beta_gate: float,
                                                                                                                                                                                                                                                                                                beta_up: float,
                                                                                                                                                                                                                                                                                            ):
                                                                                                                                                                                                                                                                                                super().__init__()
                                                                                                                                                                                                                                                                                                self.n_experts = n_experts
                                                                                                                                                                                                                                                                                                self.dim_in, self.hidden, self.dim_out = dim_in, hidden, dim_out
                                                                                                                                                                                                                                                                                                self.beta_gate, self.beta_up = beta_gate, beta_up
                                                                                                                                                                                                                                                                                                self.gate = nn.Parameter(torch.empty(n_experts, dim_in, hidden))
                                                                                                                                                                                                                                                                                                self.up = nn.Parameter(torch.empty(n_experts, dim_in, hidden))
                                                                                                                                                                                                                                                                                                self.down = nn.Parameter(torch.empty(n_experts, hidden, dim_out))
                                                                                                                                                                                                                                                                                                #: Quantisation-aware training (paper section 4.1.4).  When enabled the
                                                                                                                                                                                                                                                                                                #: forward pass sees MXFP4 expert weights and MXFP8 activations while the
                                                                                                                                                                                                                                                                                                #: master weights stay in higher precision, so the model adapts to the
                                                                                                                                                                                                                                                                                                #: deployment numerics instead of meeting them for the first time at
                                                                                                                                                                                                                                                                                                #: export.  Off by default; ``kimi3.quant.mxfp.apply_qat`` turns it on.
                                                                                                                                                                                                                                                                                                self.qat_enabled = False
                                                                                                                                                                                                                                                                                                self.reset_parameters()


                                                                                                                                                                                                                                                                                            # 【中文释义】量化感知训练(QAT,论文 §4.1.4)的占位钩子:正式启用后前向会
                                                                                                                                                                                                                                                                                            # 以 MXFP4 专家权重 / MXFP8 激活参与计算,而 master 权重保持高精度,让模型在
                                                                                                                                                                                                                                                                                            # 训练阶段就适应部署数值环境,而不是导出时才第一次撞上。默认关闭
                                                                                                                                                                                                                                                                                            # (qat_enabled=False),故 _q_weight/_q_act 目前原样返回;由
                                                                                                                                                                                                                                                                                            # kimi3.quant.mxfp.apply_qat 打开。保留这两个接口是为了不与参考实现的结构偏离。
                                                                                                                                                                                                                                                                                            def _q_weight(self, w: Tensor) -> Tensor:
                                                                                                                                                                                                                                                                                                if not self.qat_enabled:
                                                                                                                                                                                                                                                                                                    return w
                                                                                                                                                                                                                                                                                                return w


                                                                                                                                                                                                                                                                                            def _q_act(self, x: Tensor) -> Tensor:
                                                                                                                                                                                                                                                                                                if not self.qat_enabled:
                                                                                                                                                                                                                                                                                                    return x
                                                                                                                                                                                                                                                                                                return x


                                                                                                                                                                                                                                                                                            def reset_parameters(self) -> None:
                                                                                                                                                                                                                                                                                                # 【中文释义】Xavier 风格的 Normal 初始化:std = fan_in^-0.5。
                                                                                                                                                                                                                                                                                                # gate/up 的 fan_in 是潜宽度 dim_in,down 的 fan_in 是专家内部宽度 hidden。
                                                                                                                                                                                                                                                                                                for w, fan_in in ((self.gate, self.dim_in), (self.up, self.dim_in), (self.down, self.hidden)):
                                                                                                                                                                                                                                                                                                    nn.init.normal_(w, std=fan_in**-0.5)


                                                                                                                                                                                                                                                                                            def forward_indexed(self, x: Tensor, expert_ids: Tensor) -> Tensor:
                                                                                                                                                                                                                                                                                                """Apply expert ``expert_ids[t]`` to row ``t`` of ``x``.


                                                                                                                                                                                                                                                                                                Rows are permuted into expert-contiguous order so each expert's work is a
                                                                                                                                                                                                                                                                                                single dense matmul, then permuted back once.  This is the shape MoonEP
                                                                                                                                                                                                                                                                                                turns into a grouped GEMM with a fused permute/unpermute in phase 5; here
                                                                                                                                                                                                                                                                                                the permutation is a plain gather and the inverse a single scatter.
                                                                                                                                                                                                                                                                                                """
                                                                                                                                                                                                                                                                                                # 【中文释义】按 expert_ids 把 (tokens, l) 的 token 行"按专家分组连续化":
                                                                                                                                                                                                                                                                                                #   - order     = 按专家 id 排序的索引(stable sort 保证同专家 token 保持输入相对顺序)
                                                                                                                                                                                                                                                                                                #   - counts    = 每个专家获得的 token 数
                                                                                                                                                                                                                                                                                                #   - offsets   = 每段专家的起始位置(前缀和),[0, c0, c0+c1, ...]
                                                                                                                                                                                                                                                                                                # 之后每个专家直接取 x_sorted[lo:hi] 一整段做一次稠密 matmul + SiTU-GLU,
                                                                                                                                                                                                                                                                                                # 相当于把它变成一个 grouped GEMM 的一次性切分;最后用 index_copy 把各段
                                                                                                                                                                                                                                                                                                # 输出按 order 回填到原始 token 顺序。这一步对应论文 §5 / MoonEP 中
                                                                                                                                                                                                                                                                                                # "fused permute/unpermute" 的形状——此处是朴素 gather + scatter 的 CPU 实现。
                                                                                                                                                                                                                                                                                                from .situ_glu import situ_glu


                                                                                                                                                                                                                                                                                                order = torch.argsort(expert_ids)
                                                                                                                                                                                                                                                                                                counts = torch.bincount(expert_ids, minlength=self.n_experts)
                                                                                                                                                                                                                                                                                                offsets = torch.cat([counts.new_zeros(1), counts.cumsum(0)])
                                                                                                                                                                                                                                                                                                x_sorted = x.index_select(0, order)


                                                                                                                                                                                                                                                                                                pieces = []
                                                                                                                                                                                                                                                                                                for e in range(self.n_experts):
                                                                                                                                                                                                                                                                                                    lo, hi = int(offsets[e]), int(offsets[e + 1])
                                                                                                                                                                                                                                                                                                    if lo == hi:
                                                                                                                                                                                                                                                                                                        continue
                                                                                                                                                                                                                                                                                                    xe = self._q_act(x_sorted[lo:hi])
                                                                                                                                                                                                                                                                                                    # 【中文释义】专家 e 的完整 SiTU-GLU 前馈:
                                                                                                                                                                                                                                                                                                    #   h = softcap(xe·gate_e, βg) * sigmoid(xe·gate_e) * softcap(xe·up_e, βu)
                                                                                                                                                                                                                                                                                                    # 然后 h @ down_e 把隐藏层宽度降回潜宽度 l。gate/up 共享同一预激活
                                                                                                                                                                                                                                                                                                    # (xe@gate_e),SiTU 有界激活保证乘积不爆炸(|·| ≤ βg·βu = 4×25)。
                                                                                                                                                                                                                                                                                                    h = situ_glu(
                                                                                                                                                                                                                                                                                                        xe @ self._q_weight(self.gate[e]),
                                                                                                                                                                                                                                                                                                        xe @ self._q_weight(self.up[e]),
                                                                                                                                                                                                                                                                                                        self.beta_gate,
                                                                                                                                                                                                                                                                                                        self.beta_up,
                                                                                                                                                                                                                                                                                                    )
                                                                                                                                                                                                                                                                                                    pieces.append(self._q_act(h) @ self._q_weight(self.down[e]))


                                                                                                                                                                                                                                                                                                if not pieces:
                                                                                                                                                                                                                                                                                                    return x.new_zeros(x.shape[0], self.dim_out)
                                                                                                                                                                                                                                                                                                sorted_out = torch.cat(pieces, dim=0)
                                                                                                                                                                                                                                                                                                out = torch.empty(
                                                                                                                                                                                                                                                                                                    x.shape[0], self.dim_out, dtype=sorted_out.dtype, device=x.device
                                                                                                                                                                                                                                                                                                )
                                                                                                                                                                                                                                                                                                return out.index_copy_(0, order, sorted_out)


                                                                                                                                                                                                                                                                                            def forward_all(self, x: Tensor) -> Tensor:
                                                                                                                                                                                                                                                                                                """Apply every expert to every row: ``(n, tokens, dim_out)``.


                                                                                                                                                                                                                                                                                                Only used by tiny configs and by tests; the dispatch path is the norm.
                                                                                                                                                                                                                                                                                                """
                                                                                                                                                                                                                                                                                                # 【中文释义】把所有专家对每个 token 的投影一次性算出,返回 (n, tokens, l)。
                                                                                                                                                                                                                                                                                                # 仅用于小配置与测试(test_grouped_dispatch_matches_dense_evaluation 用它当
                                                                                                                                                                                                                                                                                                # 稠密 oracle),正式 dispatch 永远走 forward_indexed。
                                                                                                                                                                                                                                                                                                from .situ_glu import situ_glu


                                                                                                                                                                                                                                                                                                xq = self._q_act(x)
                                                                                                                                                                                                                                                                                                h = situ_glu(
                                                                                                                                                                                                                                                                                                    torch.einsum("td,ndh->nth", xq, self._q_weight(self.gate)),
                                                                                                                                                                                                                                                                                                    torch.einsum("td,ndh->nth", xq, self._q_weight(self.up)),
                                                                                                                                                                                                                                                                                                    self.beta_gate,
                                                                                                                                                                                                                                                                                                    self.beta_up,
                                                                                                                                                                                                                                                                                                )
                                                                                                                                                                                                                                                                                                return torch.einsum("nth,nho->nto", self._q_act(h), self._q_weight(self.down))

                                                                                                                                                                                                                                                                                        常见问题

                                                                                                                                                                                                                                                                                        Q1:cutoff 是啥意思

                                                                                                                                                                                                                                                                                        cutoff = 第 (k+1) 个 biased score(router_qb.py:170-182):

                                                                                                                                                                                                                                                                                          top_val, top_idx = torch.topk(biased, k+1)      # 一次取 k+1 个
                                                                                                                                                                                                                                                                                          indices = top_idx[:, :top_k]                    # 前 k 个 = 实际路由
                                                                                                                                                                                                                                                                                          cutoff  = top_val[:, top_k]                     # 第 k+1 个 = α_i
                                                                                                                                                                                                                                                                                          • 语义:token i 要进入自己的 Top-k,专家分数必须超过 α_i——它是第 k 名与第 k+1 名之间的"边界分"。

                                                                                                                                                                                                                                                                                          • 为什么需要:QB 要回答"专家 j 加多少偏置 b 才会被 token i 选中",直接取路由自身产生的 α_i 即可,无需单独算 token 侧分位数:

                                                                                                                                                                                                                                                                                            margin r_ij = α_i − s_ij      # 专家 j 所需补的偏置量(router_qb.py:218)
                                                                                                                                                                                                                                                                                            选中条件: s_ij + b_j ≥ α_i   ⇔  r_ij ≤ b_j
                                                                                                                                                                                                                                                                                            • 边界情形:k+1 > n_experts 时没有第 k+1 个,cutoff 填 -inf(无门槛)。

                                                                                                                                                                                                                                                                                            Q2:GroupedExperts 是 MoonEP 的 CPU 实现吗

                                                                                                                                                                                                                                                                                            不是完整 MoonEP,只是其"组织形状层"。 注释 "这正是 MoonEP …使用的组织方式" 指权重打包与 grouped 调度形态,不指并行运行时:

                                                                                                                                                                                                                                                                                            层面

                                                                                                                                                                                                                                                                                            MoonEP(论文 §5)

                                                                                                                                                                                                                                                                                            本项目 GroupedExperts

                                                                                                                                                                                                                                                                                            权重组织

                                                                                                                                                                                                                                                                                            batched 权重,dispatch=一次 grouped GEMM

                                                                                                                                                                                                                                                                                            同款:gate/up/down 三张叠加

                                                                                                                                                                                                                                                                                            token→专家

                                                                                                                                                                                                                                                                                            S×K token 经 all-to-all 分发到各 rank

                                                                                                                                                                                                                                                                                            forward_indexed 排序成段+逐段 matmul

                                                                                                                                                                                                                                                                                            动态冗余专家/online plan/梯度归约

                                                                                                                                                                                                                                                                                            有(运行时再均衡)

                                                                                                                                                                                                                                                                                            无(教学 CPU 只覆盖形状)

                                                                                                                                                                                                                                                                                            "语义一致" = "每 token 只被选中的专家算、结果与逐专家独立求一致"这一层等价;并行运行时(MoonEP-master)需 GPU/多机,不在本项目实现范围。

                                                                                                                                                                                                                                                                                            forward_indexed 的"分组"体现在哪

                                                                                                                                                                                                                                                                                            "分组"不靠显式结构,而是排序把同一专家的行凑成连续段,再逐段做一次稠密 matmul:

                                                                                                                                                                                                                                                                                              输入 x: (bt, l)        expert_ids: (bt,)
                                                                                                                                                                                                                                                                                                │                      │
                                                                                                                                                                                                                                                                                                ▼                      ▼
                                                                                                                                                                                                                                                                                               order   = argsort(expert_ids)        # 升序索引 → 同专家行相邻
                                                                                                                                                                                                                                                                                               counts  = bincount(expert_ids)       # 每专家分到 token 数
                                                                                                                                                                                                                                                                                               offsets = [0, c0, c0+c1, ...]        # 各段起止(前缀和)
                                                                                                                                                                                                                                                                                                │
                                                                                                                                                                                                                                                                                                ▼
                                                                                                                                                                                                                                                                                               x_sorted = x[order]                  # 专家 0 的 token、专家 1 的 token、…
                                                                                                                                                                                                                                                                                                │
                                                                                                                                                                                                                                                                                                ▼  逐专家 e=0..E-1:
                                                                                                                                                                                                                                                                                                │    lo, hi = offsets[e], offsets[e+1]
                                                                                                                                                                                                                                                                                                │    if lo == hi: continue                   # 空段跳过
                                                                                                                                                                                                                                                                                                │    xe    = x_sorted[lo:hi]                 # ★ 这段 = 分给专家 e 的一组
                                                                                                                                                                                                                                                                                                │    h     = SiTU-GLU(xe@gate[e], xe@up[e], βg, βu)
                                                                                                                                                                                                                                                                                                │    out_e = h @ down[e]                     # 每段一次稠密 matmul
                                                                                                                                                                                                                                                                                                │    pieces.append(out_e)
                                                                                                                                                                                                                                                                                                └───────────────────────────────
                                                                                                                                                                                                                                                                                                │
                                                                                                                                                                                                                                                                                                ▼
                                                                                                                                                                                                                                                                                               sorted_out = cat(pieces)             # 按段拼接回 (bt, l)
                                                                                                                                                                                                                                                                                               out = empty(bt, l)
                                                                                                                                                                                                                                                                                               out.index_copy_(0, order, sorted_out) # ★ 逆序回填 → 恢复原 token 顺序
                                                                                                                                                                                                                                                                                                │
                                                                                                                                                                                                                                                                                                ▼
                                                                                                                                                                                                                                                                                               返回 out: (bt, l)

                                                                                                                                                                                                                                                                                              数据流(张量形态):

                                                                                                                                                                                                                                                                                              数据流
                                                                                                                                                                                                                                                                                              数据流

                                                                                                                                                                                                                                                                                              GPU(MoonEP)上这 E 段是一次 grouped_gemm;CPU 教学版退化为循环,段内多 token 一起算 = 批处理。

                                                                                                                                                                                                                                                                                              forward_all 的作用

                                                                                                                                                                                                                                                                                              字面:把每个专家应用到每一行,返回 (E, bt, l) 全量输出(moe.py:211-228):

                                                                                                                                                                                                                                                                                                h = situ_glu(
                                                                                                                                                                                                                                                                                                    einsum("td,ndh->nth", x, gate),   # (E,bt,H) 专家 n × token t 预激活
                                                                                                                                                                                                                                                                                                    einsum("td,ndh->nth", x, up),
                                                                                                                                                                                                                                                                                                    βg, βu)
                                                                                                                                                                                                                                                                                                return einsum("nth,nho->nto", h, down)   # (E, bt, l)

                                                                                                                                                                                                                                                                                                用途:稠密 oracle,仅供小配置与测试。test_grouped_dispatch_matches_dense_evaluation 用它当 ground truth,验证 forward_indexed 的排序/分组/回填正确。

                                                                                                                                                                                                                                                                                                对比:

                                                                                                                                                                                                                                                                                                forward_indexed

                                                                                                                                                                                                                                                                                                forward_all

                                                                                                                                                                                                                                                                                                每 token 用几个专家

                                                                                                                                                                                                                                                                                                仅选中的 top-k(稀疏)

                                                                                                                                                                                                                                                                                                全部 E(稠密)

                                                                                                                                                                                                                                                                                                复杂度

                                                                                                                                                                                                                                                                                                O(bt·k·l·H)

                                                                                                                                                                                                                                                                                                O(E·bt·l·H)

                                                                                                                                                                                                                                                                                                返回形状

                                                                                                                                                                                                                                                                                                (bt, l) 聚合结果

                                                                                                                                                                                                                                                                                                (E, bt, l) 全谱

                                                                                                                                                                                                                                                                                                用途

                                                                                                                                                                                                                                                                                                生产 dispatch

                                                                                                                                                                                                                                                                                                测试 oracle / 极小配置

                                                                                                                                                                                                                                                                                                数据流图:

                                                                                                                                                                                                                                                                                                   x(bt,l)
                                                                                                                                                                                                                                                                                                    │
                                                                                                                                                                                                                                                                                                    ├─ einsum("td,ndh->nth")   ──►  gate_act(E,bt,H)
                                                                                                                                                                                                                                                                                                    ├─ einsum("td,ndh->nth")   ──►  up_act(E,bt,H)
                                                                                                                                                                                                                                                                                                    │        gate_act ┐
                                                                                                                                                                                                                                                                                                    │        up_act   ┴─ SiTU-GLU(βg,βu) ──►  h(E,bt,H)
                                                                                                                                                                                                                                                                                                    │
                                                                                                                                                                                                                                                                                                    └─ einsum("nth,nho->nto") ──►  out(E,bt,l)
                                                                                                                                                                                                                                                                                                                                          │ [专家 n][token t] 全量输出
                                                                                                                                                                                                                                                                                                                                          ▼
                                                                                                                                                                                                                                                                                                                                test 取 out[selected] 与 forward_indexed 对比

                                                                                                                                                                                                                                                                                                  流程图(测试用法):

                                                                                                                                                                                                                                                                                                                forward_all(x) ────► 全量 (E,bt,l)         ← oracle
                                                                                                                                                                                                                                                                                                                      │                    │
                                                                                                                                                                                                                                                                                                                      │              route.indices
                                                                                                                                                                                                                                                                                                                      ▼                    ▼
                                                                                                                                                                                                                                                                                                              forward_indexed(x, ids) → 稀疏 (bt,l) ≈ 稠密中选中行
                                                                                                                                                                                                                                                                                                                                            │
                                                                                                                                                                                                                                                                                                                                            ▼
                                                                                                                                                                                                                                                                                                                            assert 逐元素一致(测试保护)

                                                                                                                                                                                                                                                                                                    A.2 Output

                                                                                                                                                                                                                                                                                                      class MoEOutput:
                                                                                                                                                                                                                                                                                                          __slots__ = ("hidden", "router")


                                                                                                                                                                                                                                                                                                          # 【中文释义】MoE 前向的标准返回结构:
                                                                                                                                                                                                                                                                                                          #   - hidden:(b, t, d) 的最终输出 = 共享路径 + 路由路径;
                                                                                                                                                                                                                                                                                                          #   - router:QuantileBalancingRouter 的 RouterOutput,携带 indices/weights/cutoff
                                                                                                                                                                                                                                                                                                          #     (scores)等路由决策信息,供量化负载均衡(QB)下一步更新使用。
                                                                                                                                                                                                                                                                                                          # DenseFFN 层由于没有路由,router 恒为 None(见 DenseFFN.forward)。
                                                                                                                                                                                                                                                                                                          def __init__(self, hidden: Tensor, router: RouterOutput | None):
                                                                                                                                                                                                                                                                                                              self.hidden = hidden
                                                                                                                                                                                                                                                                                                              self.router = router


                                                                                                                                                                                                                                                                                                      class DenseFFN(nn.Module):
                                                                                                                                                                                                                                                                                                          """Full-width SiTU-GLU feed-forward, used by the leading dense layer."""


                                                                                                                                                                                                                                                                                                          # 【中文释义】DenseFFN = 全宽(d 维)的 SiTU-GLU 前馈。K3 的「层调度」里,
                                                                                                                                                                                                                                                                                                          # 前 n_dense_layers 层不使用 MoE(避免模型过于稀疏而学不动),直接用共享式
                                                                                                                                                                                                                                                                                                          # 的全宽 FFN 起步;这些层由 model.py 根据 n_dense_layers 塞进 DenseFFN,
                                                                                                                                                                                                                                                                                                          # 其余层才走 StableLatentMoE。本质上是"dense warm-up + sparse body"。
                                                                                                                                                                                                                                                                                                          def __init__(self, dim: int, hidden: int, cfg: MoEConfig):
                                                                                                                                                                                                                                                                                                              super().__init__()
                                                                                                                                                                                                                                                                                                              self.ffn = SiTUGLU(
                                                                                                                                                                                                                                                                                                                  dim, hidden, beta_gate=cfg.situ_beta_gate, beta_up=cfg.situ_beta_up
                                                                                                                                                                                                                                                                                                              )


                                                                                                                                                                                                                                                                                                          def forward(self, x: Tensor) -> MoEOutput:
                                                                                                                                                                                                                                                                                                              # 【中文释义】Dense 层没有路由决策,router 字段固定为 None。
                                                                                                                                                                                                                                                                                                              return MoEOutput(self.ffn(x), None)

                                                                                                                                                                                                                                                                                                      A.3 StableLatentMoE

                                                                                                                                                                                                                                                                                                        class StableLatentMoE(nn.Module):
                                                                                                                                                                                                                                                                                                            # 【中文释义】Stable LatentMoE 的完整组件:把一个 dim 维输入 token 通过潜空间
                                                                                                                                                                                                                                                                                                            # (latent width l)路由到 top_k 个专家 + 全宽 shared 专家,汇聚后回投影到 d 维。
                                                                                                                                                                                                                                                                                                            # 全部宽:dim d → 潜 l → 专家内部 hidden H → 潜 l → dim d。
                                                                                                                                                                                                                                                                                                            # 与 kimi3-master/kimi3/modules/moe.py 逐行镜像;K3 真实配置:
                                                                                                                                                                                                                                                                                                            #   n_routed=896, n_shared=2, top_k=16(稀疏度=56), latent=3584,
                                                                                                                                                                                                                                                                                                            #   expert_hidden=shared_hidden=3072, SiTU beta_gate=4.0, beta_up=25.0,
                                                                                                                                                                                                                                                                                                            #   QB enabled/bins=1000/ema=0.0(见 config.py MoEConfig 默认值)。
                                                                                                                                                                                                                                                                                                            def __init__(self, dim: int, cfg: MoEConfig, *, eps: float = 1e-6):
                                                                                                                                                                                                                                                                                                                super().__init__()
                                                                                                                                                                                                                                                                                                                self.dim = dim
                                                                                                                                                                                                                                                                                                                self.cfg = cfg
                                                                                                                                                                                                                                                                                                                ell = cfg.latent_dim


                                                                                                                                                                                                                                                                                                                self.down_proj = nn.Linear(dim, ell, bias=False)     # W_down: d -> l
                                                                                                                                                                                                                                                                                                                self.up_proj = nn.Linear(ell, dim, bias=False)       # W_up:   l -> d
                                                                                                                                                                                                                                                                                                                # The stabiliser of section 2.3.1, between aggregation and up-projection.
                                                                                                                                                                                                                                                                                                                self.latent_norm = RMSNorm(ell, eps) if cfg.rmsnorm_before_up else nn.Identity()


                                                                                                                                                                                                                                                                                                                # 【中文释义】路由(QuantileBalancingRouter):sigmoid(W_r x) + 专家偏置 bias,
                                                                                                                                                                                                                                                                                                                # Top-(k+1) 取前 k 个作为实际路由、第 (k+1) 个作为 cutoff(α),偏置 b 通过与
                                                                                                                                                                                                                                                                                                                # cutoff 联合的分位数一阶更新(见 router_qb.py)。训练时可自动重均衡,推理冻结。
                                                                                                                                                                                                                                                                                                                self.router = QuantileBalancingRouter(
                                                                                                                                                                                                                                                                                                                    dim,
                                                                                                                                                                                                                                                                                                                    cfg.n_routed,
                                                                                                                                                                                                                                                                                                                    cfg.top_k,
                                                                                                                                                                                                                                                                                                                    enabled=cfg.qb_enabled,
                                                                                                                                                                                                                                                                                                                    bins=cfg.qb_bins,
                                                                                                                                                                                                                                                                                                                    ema=cfg.qb_ema,
                                                                                                                                                                                                                                                                                                                )
                                                                                                                                                                                                                                                                                                                self.experts = GroupedExperts(
                                                                                                                                                                                                                                                                                                                    cfg.n_routed,
                                                                                                                                                                                                                                                                                                                    ell,
                                                                                                                                                                                                                                                                                                                    cfg.expert_hidden,
                                                                                                                                                                                                                                                                                                                    ell,
                                                                                                                                                                                                                                                                                                                    beta_gate=cfg.situ_beta_gate,
                                                                                                                                                                                                                                                                                                                    beta_up=cfg.situ_beta_up,
                                                                                                                                                                                                                                                                                                                )
                                                                                                                                                                                                                                                                                                                self.shared = nn.ModuleList(
                                                                                                                                                                                                                                                                                                                    SiTUGLU(
                                                                                                                                                                                                                                                                                                                        dim,
                                                                                                                                                                                                                                                                                                                        cfg.shared_hidden,
                                                                                                                                                                                                                                                                                                                        beta_gate=cfg.situ_beta_gate,
                                                                                                                                                                                                                                                                                                                        beta_up=cfg.situ_beta_up,
                                                                                                                                                                                                                                                                                                                    )
                                                                                                                                                                                                                                                                                                                    for _ in range(cfg.n_shared)
                                                                                                                                                                                                                                                                                                                )


                                                                                                                                                                                                                                                                                                            def forward(self, x: Tensor) -> MoEOutput:
                                                                                                                                                                                                                                                                                                                # 【中文释义】数据流:
                                                                                                                                                                                                                                                                                                                #   1) flatten:(b, t, d) → (b·t, d),供路由与专家执行一次性批量处理;
                                                                                                                                                                                                                                                                                                                #   2) 路由:router 产出 per-token top_k 专家 indices 与归一化权重 weights,
                                                                                                                                                                                                                                                                                                                #     以及 cutoff/scores 元数据(带回路由器供 QB 更新);
                                                                                                                                                                                                                                                                                                                #   3) 降维投影:latent = W_down(x),进入潜空间;
                                                                                                                                                                                                                                                                                                                #   4) 稀疏 dispatch:把每个 token 扩展成 top_k 份(rows),每份交给对应
                                                                                                                                                                                                                                                                                                                #      专家 forward_indexed 计算(专家内 SiTU-GLU),再按权重加权并
                                                                                                                                                                                                                                                                                                                #      index_add 累加回 u —— 只有选中的专家参与,梯度自然只有这些专家得流量
                                                                                                                                                                                                                                                                                                                #      (test_only_selected_experts_receive_gradient 验证);
                                                                                                                                                                                                                                                                                                                #   5) RMSNorm 稳定化 → W_up 升回 d 维;
                                                                                                                                                                                                                                                                                                                #   6) 加上所有全宽共享专家的输出。
                                                                                                                                                                                                                                                                                                                b, t, d = x.shape
                                                                                                                                                                                                                                                                                                                flat = x.reshape(-1, d)


                                                                                                                                                                                                                                                                                                                route = self.router(flat)
                                                                                                                                                                                                                                                                                                                latent = self.down_proj(flat)                              # (tokens, l)


                                                                                                                                                                                                                                                                                                                k = self.cfg.top_k
                                                                                                                                                                                                                                                                                                                rows = torch.arange(flat.shape[0], device=x.device).repeat_interleave(k)
                                                                                                                                                                                                                                                                                                                expert_ids = route.indices.reshape(-1)
                                                                                                                                                                                                                                                                                                                weights = route.weights.reshape(-1, 1)


                                                                                                                                                                                                                                                                                                                expert_out = self.experts.forward_indexed(latent[rows], expert_ids)
                                                                                                                                                                                                                                                                                                                u = torch.zeros_like(latent)
                                                                                                                                                                                                                                                                                                                u.index_add_(0, rows, (expert_out * weights).to(u.dtype))


                                                                                                                                                                                                                                                                                                                y = self.up_proj(self.latent_norm(u))
                                                                                                                                                                                                                                                                                                                for expert in self.shared:
                                                                                                                                                                                                                                                                                                                    y = y + expert(flat)
                                                                                                                                                                                                                                                                                                                return MoEOutput(y.view(b, t, d), route)

                                                                                                                                                                                                                                                                                                        附录B. Quantile Balancing

                                                                                                                                                                                                                                                                                                        B.1 三视角解读

                                                                                                                                                                                                                                                                                                        视角一:十二岁孩子(游乐园糖摊比喻)

                                                                                                                                                                                                                                                                                                        想象游乐园里有 8 个卖糖小屋。每个小朋友选自己最喜欢的 2 个摊子买糖。

                                                                                                                                                                                                                                                                                                        问题:2 号摊的糖太受欢迎,450 个小朋友里 400 个都想去;7 号摊几乎没人去,摊主一整天打瞌睡。

                                                                                                                                                                                                                                                                                                        • 对摊子:没人去 = 赚不到钱、也不知道大家喜欢什么口味(对模型 = 专家饿死、欠训练)。

                                                                                                                                                                                                                                                                                                        • 对游乐园:热门摊排队太长、冷门摊白开。

                                                                                                                                                                                                                                                                                                        怎么让每个摊子都来差不多的小朋友?

                                                                                                                                                                                                                                                                                                        笨办法:管理员天天对 2 号摊喊"别挤这么多人啦",2 号摊把招牌"推荐指数"往下拉一点点。可能要拉几百天,拉多少全靠猜。

                                                                                                                                                                                                                                                                                                        聪明的办法:管理员先观察一次——心里记下"每个小朋友认为 2 号摊刚好排第二、再差一点就不选它的分数线"(这叫门票线 / cutoff)。然后一步把 2 号摊的推荐指数直接降到"恰好只剩那么多小朋友会选它"的位置。热摊不再挤爆,冷摊的门槛也一步降下来。

                                                                                                                                                                                                                                                                                                        一句话:不用慢慢试,看一眼"最后一道线"在哪,直接跳过去,每个摊子就刚好分到同样多的小朋友。

                                                                                                                                                                                                                                                                                                        视角二:半专业(工程直觉)

                                                                                                                                                                                                                                                                                                        MoE 路由器给每个 token 打分(sigmoid),Top-k 选出信任的专家。问题:专家热度天然不均——热门专家被反复选中、梯度吃饱,冷门专家长期欠训练。

                                                                                                                                                                                                                                                                                                        传统两条路都不够好:

                                                                                                                                                                                                                                                                                                        1. 辅助损失(auxiliary loss):往总 loss 加"负载均衡"惩罚项。缺点:多一个超参 λ、与主任务抢梯度。

                                                                                                                                                                                                                                                                                                        2. 固定步长 signSGD:b ← b + γ·sign(target − load) 慢慢挪。缺点:有超参 γ、收敛慢,896 专家规模等不起。

                                                                                                                                                                                                                                                                                                        QB 做法:分出偏置 buffer b,加进选择分数(s+b)但不进最终权重。偏置只改变"谁被选中",不改变"选中后有多重"——所以可以放心承担负载均衡、不干扰任务训练。

                                                                                                                                                                                                                                                                                                        关键一步——cutoff:路由用 Top-(k+1) 多取一个数 = α_i(token i 进入 Top-k 的边界分)。r_ij = α_i − s_ij 的含义:"专家 j 差多少才被 token i 选中"。

                                                                                                                                                                                                                                                                                                        把 b_j 当专家 j 的门槛:b_j 越大被选中的 token 越多,单调增。要让专家 j 的负载 = q = m·k/n。解方程:b*_j = 所有 r_i,j 分布的第 q 分位(恰好让 q 个 token 选中它的阈值)。大规模用 1000-bin 直方图估计 + 跨卡一次整数 all-reduce 聚合——通信量固定、与 token 数无关。

                                                                                                                                                                                                                                                                                                        一句话:把"负载均衡"从"梯度/损失"里剥出来,变成统计分位数问题,一步算出最优偏置。

                                                                                                                                                                                                                                                                                                        视角三:专业(数学与实现全量)

                                                                                                                                                                                                                                                                                                        记法:s_ij = σ((W_r x_i)_j);路由用 Top-(k+1):前 k 个为实际路由,第 k+1 个为 α_i。

                                                                                                                                                                                                                                                                                                        偏置角色(router_qb.py):

                                                                                                                                                                                                                                                                                                          biased  = s_ij + b_j           # 仅用于选择
                                                                                                                                                                                                                                                                                                          T_i     = argtopk_k(biased)
                                                                                                                                                                                                                                                                                                          p_ij    = s_ij / Σ_{r∈T_i} s_ir   # 权重不含 b

                                                                                                                                                                                                                                                                                                          b 为 register_buffer(router_qb.py),不进优化器、推理冻结。

                                                                                                                                                                                                                                                                                                          目标与推演:专家 j 的负载对齐 q = mk/n。固定截断 α 后:

                                                                                                                                                                                                                                                                                                            load_j(b_j) = #{ i : s_ij + b_j ≥ α_i } = #{ i : r_ij ≤ b_j },   r_ij ≜ α_i − s_ij

                                                                                                                                                                                                                                                                                                            load_j 是 b_j 的单调不减阶梯函数。令其等于 q → b*_j 为 r_{:,j} 的第 q 分位,mean-centring 得 b ← b* − mean(b*)(router_qb.py,保证 Σb=0)。即:

                                                                                                                                                                                                                                                                                                              b̂_j ← −quantile_{1-k/n}(s_{:,j} − α) ;  b ← b̂ − mean(b̂)     (Eq.14)

                                                                                                                                                                                                                                                                                                              一个 forward 直接给出精确解。

                                                                                                                                                                                                                                                                                                              为何无需学习率(论文附录 C):这是"最大总分均衡匹配"LP 的对偶问题,坐标方向最小化恰好是逐列分位数——一步即全局精确解。这是"loss-free"(无惩罚项)+ "无需调参"两大卖点。

                                                                                                                                                                                                                                                                                                              直方图估计(论文附录 D):真实 r_ij 为 M×E 量级、跨 DP rank 与 grad-accum 步,无法直接收集。改为每 rank 把 r_ij 分进每专家 bins(默认 1000,苏剑林:10000 无增益),计入 histogram(E, B) int 缓冲;计数值可加,一次整数 all-reduce 即得全局直方图,估计误差 ≤ 一个 bin 宽(而非各节点平均)。成本恒定 n·B 整数/层/步、与 token 数无关。精确版 update_bias_exact(router_qb.py:287)用 torch.quantile 显式算,作为直方图 oracle。

                                                                                                                                                                                                                                                                                                              边界与工程细节:

                                                                                                                                                                                                                                                                                                              • 更新应用于下一步(绝不用本批自得的 bias 路由自己);

                                                                                                                                                                                                                                                                                                              • bins 默认 1000,config 校验 ≥16(config.py:141);

                                                                                                                                                                                                                                                                                                              • EMA(qb_ema)可选平滑,K3 默认 0.0;

                                                                                                                                                                                                                                                                                                              • 与 SGLang(inkling)差异:生产同为 sigmoid 选 + 自内 renorm,但 latent-down 不存在,属部署形态差异。

                                                                                                                                                                                                                                                                                                              三视角差别小结

                                                                                                                                                                                                                                                                                                              视角

                                                                                                                                                                                                                                                                                                              类比核心

                                                                                                                                                                                                                                                                                                              使用的工具

                                                                                                                                                                                                                                                                                                              12 岁

                                                                                                                                                                                                                                                                                                              糖摊"推荐指数"一步调平

                                                                                                                                                                                                                                                                                                              无公式;"门槛""边界线"

                                                                                                                                                                                                                                                                                                              半专业

                                                                                                                                                                                                                                                                                                              偏置=buffer、cutoff、分位数=一步到 target

                                                                                                                                                                                                                                                                                                              一句话公式 + 单调性直觉

                                                                                                                                                                                                                                                                                                              专业

                                                                                                                                                                                                                                                                                                              LP 对偶、坐标极小化、直方图+all-reduce 通信分析

                                                                                                                                                                                                                                                                                                              完整 Eq.14 / 附录 C-D / 实现细节


                                                                                                                                                                                                                                                                                                              B.2 架构

                                                                                                                                                                                                                                                                                                              B.2.1 类与 buffer 结构

                                                                                                                                                                                                                                                                                                                QuantileBalancingRouter (router_qb.py:123)
                                                                                                                                                                                                                                                                                                                  ├── 参数: weight (E, d)          # W_r,σ门控,训练更新
                                                                                                                                                                                                                                                                                                                  ├── 训练时更新 buffer(偏置不进梯度):
                                                                                                                                                                                                                                                                                                                  │     bias       (E,)           # ← select 用,update 时改
                                                                                                                                                                                                                                                                                                                  │     histogram  (E, bins=1000) # int64,附加可加
                                                                                                                                                                                                                                                                                                                  │     hist_lo    () preserve Range [b_min−1, b_max+1 ]
                                                                                                                                                                                                                                                                                                                  │     hist_width ()             # bin 宽度
                                                                                                                                                                                                                                                                                                                  │     token_count()             # 已统计 token 数
                                                                                                                                                                                                                                                                                                                  │     load       (E,)           # 每个专家被选中次数(窗口)
                                                                                                                                                                                                                                                                                                                  │   ├── 无 __init__ 外再参数 —— 权重 = 路由矩阵 + 均衡状态一体
                                                                                                                                                                                                                                                                                                                  └── 注意:bias 是 buffer,非 Parameter → 不进梯度、推理冻结

                                                                                                                                                                                                                                                                                                                B.2.2 模块间依赖

                                                                                                                                                                                                                                                                                                                          StableLatentMoE
                                                                                                                                                                                                                                                                                                                               │ 实例化
                                                                                                                                                                                                                                                                                                                               ▼
                                                                                                                                                                                                                                                                                                                     QuantileBalancingRouter
                                                                                                                                                                                                                                                                                                                          │ self.weight  W_r (E,d)
                                                                                                                                                                                                                                                                                                                          │
                                                                                                                                                                                                                                                                                                                          ├── forward(x) → RouterOutput
                                                                                                                                                                                                                                                                                                                          │      ├─ scores=σ(W_r x)            (167)
                                                                                                                                                                                                                                                                                                                          │      ├─ biased = s + bias        (168)
                                                                                                                                                                                                                                                                                                                          │      ├─ topk(k+1) → indices/cutoff (175-182)   [k real routes + α]
                                                                                                                                                                                                                                                                                                                          │      ├─ weights = s/Σ(选中集内)   (184-188)
                                                                                                                                                                                                                                                                                                                          │      └─ train? → _accumulate      (190-191, §9.4)
                                                                                                                                                                                                                                                                                                                          │
                                                                                                                                                                                                                                                                                                                          ├── _accumulate(score,cutoff,idx)      (198-227)  histogram 需要
                                                                                                                                                                                                                                                                                                                          ├── update_bias(group)                 (230-284)  Eq.14 通过 histogram
                                                                                                                                                                                                                                                                                                                          │        ┌ all_reduce histogram          (252-254, 可选)
                                                                                                                                                                                                                                                                                                                          │        ├ 目标 q = m*k/n (256-257)
                                                                                                                                                                                                                                                                                                                          │        ├ cumsum → argmax首次≥target    (262-269)
                                                                                                                                                                                                                                                                                                                          │        ├ 插值 frac (270-274)
                                                                                                                                                                                                                                                                                                                          │        ├ b* − mean(b*)                  (275-276)
                                                                                                                                                                                                                                                                                                                          │        └ (ema) copy 回 bias             (278-281)
                                                                                                                                                                                                                                                                                                                          ├── update_bias_exact(s,c)               (287-298)  精确 oracle:torch.quantile
                                                                                                                                                                                                                                                                                                                          └── load_balance_stats()                 (301-315)  指标 max_min/cv/peak

                                                                                                                                                                                                                                                                                                                  B.2.3 数据流(forward + accumulate 一次)

                                                                                                                                                                                                                                                                                                                    (x: flat 输入张量, bt·d)
                                                                                                                                                                                                                                                                                                                       │
                                                                                                                                                                                                                                                                                                                       ▼
                                                                                                                                                                                                                                                                                                                    scores = σ(W_r·x)  (bt, E)
                                                                                                                                                                                                                                                                                                                       │
                                                                                                                                                                                                                                                                                                                       │ biased = scores + bias            ← b 只加在“选”
                                                                                                                                                                                                                                                                                                                       ▼
                                                                                                                                                                                                                                                                                                                    topk(biased, (k+1))  --→  indices(bt,k)              weights(bt,k)
                                                                                                                                                                                                                                                                                                                                        └─α cutoff(bt,)                 (σ选集内归一,无b)
                                                                                                                                                                                                                                                                                                                       │
                                                                                                                                                                                                                                                                                                                       │ (train 且 enabled)
                                                                                                                                                                                                                                                                                                                       ▼
                                                                                                                                                                                                                                                                                                                    _accumulate:
                                                                                                                                                                                                                                                                                                                       required = α − scores            (bt, E)   “所需偏置”
                                                                                                                                                                                                                                                                                                                       bin idx = floor((required−lo)/width)·clamp            (bt,E)
                                                                                                                                                                                                                                                                                                                       to flat idx=E×B                  scatter_add→histogram (E, B)  [整数]
                                                                                                                                                                                                                                                                                                                       token_count += bt ; load += bincount(idx)
                                                                                                                                                                                                                                                                                                                       │ (每 optimizer step)
                                                                                                                                                                                                                                                                                                                       ▼
                                                                                                                                                                                                                                                                                                                    update_bias → 新的 bias 写回 (下次 forward 才生效)

                                                                                                                                                                                                                                                                                                                    B.2.4 执行流

                                                                                                                                                                                                                                                                                                                      每个 forward:
                                                                                                                                                                                                                                                                                                                        1. sigmoid 打分 (167)
                                                                                                                                                                                                                                                                                                                        2. per-expert bias 叠加 (168)
                                                                                                                                                                                                                                                                                                                        3. topk(k+1) → indices + cutoff (170-182)
                                                                                                                                                                                                                                                                                                                        4. 选中集 renorm weights (187-188)
                                                                                                                                                                                                                                                                                                                        5. if train&enabled: _accumulate(detach 后)   ← 更新可观测直方图 (190)


                                                                                                                                                                                                                                                                                                                      每个 optimizer step:
                                                                                                                                                                                                                                                                                                                        6. update_bias (230):
                                                                                                                                                                                                                                                                                                                             - 收集全局直方图(all-reduce, 可选)
                                                                                                                                                                                                                                                                                                                             - 计算 q, 找首批 reach 的 bin, frac 插值, mean-centre, EMA
                                                                                                                                                                                                                                                                                                                             - 写回 bias buffer,清空 histogram/load
                                                                                                                                                                                                                                                                                                                      测试路径:
                                                                                                                                                                                                                                                                                                                        7. update_bias_exact: torch.quantile(Eq14) 直接算出 → 作直方图 oracle
                                                                                                                                                                                                                                                                                                                        8. load_balance_stats 监控负载健康度

                                                                                                                                                                                                                                                                                                                      B.3 实现

                                                                                                                                                                                                                                                                                                                      B.3.1 实现两处:

                                                                                                                                                                                                                                                                                                                      1. 精确版 update_bias_exact(router_qb.py:287):对真分数矩阵直接 torch.quantile(..., topk/n_route)。

                                                                                                                                                                                                                                                                                                                      2. 直方图版 _accumulate + update_bias(router_qb.py:198,230):

                                                                                                                                                                                                                                                                                                                        • 每个 step 把 margin 装入直方图(qb_bins=1000,苏剑林确认 1000 够用、10000 无增益);

                                                                                                                                                                                                                                                                                                                        • update_bias:对累计 count 首次 ≥ target 的 bin 做插值 → b_hat,再均值校正;

                                                                                                                                                                                                                                                                                                                        • 多个 step 间直接相加:bin 直方图可在多 rank/多 step 累计,通信量极小(整数向量)。

                                                                                                                                                                                                                                                                                                                      与 baseline 对比:

                                                                                                                                                                                                                                                                                                                      辅助 loss

                                                                                                                                                                                                                                                                                                                      固定步长 signSGD

                                                                                                                                                                                                                                                                                                                      QB

                                                                                                                                                                                                                                                                                                                      超级参数

                                                                                                                                                                                                                                                                                                                      loss 权重 λ

                                                                                                                                                                                                                                                                                                                      学习率 γ

                                                                                                                                                                                                                                                                                                                      无

                                                                                                                                                                                                                                                                                                                      收敛

                                                                                                                                                                                                                                                                                                                      慢/抖动

                                                                                                                                                                                                                                                                                                                      慢

                                                                                                                                                                                                                                                                                                                      一步 batch

                                                                                                                                                                                                                                                                                                                      通信

                                                                                                                                                                                                                                                                                                                      统计量

                                                                                                                                                                                                                                                                                                                      统计量

                                                                                                                                                                                                                                                                                                                      直方图

                                                                                                                                                                                                                                                                                                                      demo 实测(experiments/moe/demo_stable_latent_moe):

                                                                                                                                                                                                                                                                                                                      • load 前 max/min ≈ 3.69、cv ≈ 0.51;QB 后 max/min ≈ 1.49、cv ≈ 0.14;

                                                                                                                                                                                                                                                                                                                      • histogram vs exact bias 最大差值 0.0027(bin 宽量级)。

                                                                                                                                                                                                                                                                                                                      B.3.2 具体代码

                                                                                                                                                                                                                                                                                                                        r"""Quantile Balancing: auxiliary-loss-free MoE routing (section 2.3.3, appendices C-D).


                                                                                                                                                                                                                                                                                                                        K3 routes with a per-expert bias added to the score used for Top-k selection but
                                                                                                                                                                                                                                                                                                                        *excluded* from the mixture weights::


                                                                                                                                                                                                                                                                                                                            s_i = sigmoid(W_r x_i)
                                                                                                                                                                                                                                                                                                                            T_i = argtopk_k(s_i + b)            selection sees the bias
                                                                                                                                                                                                                                                                                                                            p_ij = s_ij / sum_{r in T_i} s_ir   gradients do not


                                                                                                                                                                                                                                                                                                                        so ``b`` steers dispatch without distorting the optimisation of the router.


                                                                                                                                                                                                                                                                                                                        The question is how to set ``b``.  The usual loss-free rule nudges it by a fixed
                                                                                                                                                                                                                                                                                                                        step in the direction of the load error, ``b <- b + gamma * sign(target - load)``,
                                                                                                                                                                                                                                                                                                                        whose step size is a hyperparameter and whose equilibration is slow -- and at 896
                                                                                                                                                                                                                                                                                                                        experts per layer, slow equilibration means persistently imbalanced expert-parallel
                                                                                                                                                                                                                                                                                                                        training and undertrained experts.


                                                                                                                                                                                                                                                                                                                        Quantile Balancing instead jumps straight to the bias that *makes* each expert's
                                                                                                                                                                                                                                                                                                                        load equal to its target, in one forward pass.  Routing uses Top-(k+1) rather than
                                                                                                                                                                                                                                                                                                                        Top-k on the biased score: the first ``k`` entries are the routes actually taken,
                                                                                                                                                                                                                                                                                                                        and the ``(k+1)``-th is the cutoff ``alpha_i`` an expert must exceed to enter token
                                                                                                                                                                                                                                                                                                                        ``i``'s Top-k.  Taking the cutoff from the routing itself avoids a separate
                                                                                                                                                                                                                                                                                                                        token-side quantile.  With the cutoffs fixed, the count of tokens routed to expert
                                                                                                                                                                                                                                                                                                                        ``j`` under a candidate bias is monotone in the threshold, so setting that count to
                                                                                                                                                                                                                                                                                                                        the target ``q = mk/n`` makes the bias the ``(q+1)``-th largest margin
                                                                                                                                                                                                                                                                                                                        ``s_ij - alpha_i``.  That is Eq. 14::


                                                                                                                                                                                                                                                                                                                            bhat_j <- -quantile_{1-k/n}(s_{:,j} - alpha)
                                                                                                                                                                                                                                                                                                                            b      <- bhat - mean(bhat)


                                                                                                                                                                                                                                                                                                                        Appendix C derives this as the exact coordinate minimiser of the dual of the
                                                                                                                                                                                                                                                                                                                        maximum-score balanced-assignment LP, which is why it needs no learning rate.


                                                                                                                                                                                                                                                                                                                        The update is applied on the *next* step -- a batch is never routed with a bias
                                                                                                                                                                                                                                                                                                                        derived from itself -- and the bias is frozen at inference.


                                                                                                                                                                                                                                                                                                                        Histogram estimation (appendix D)
                                                                                                                                                                                                                                                                                                                        ---------------------------------
                                                                                                                                                                                                                                                                                                                        At scale the quantile spans millions of margins sharded across data-parallel ranks
                                                                                                                                                                                                                                                                                                                        and gradient-accumulation steps, so gathering them exactly is not viable.  Instead
                                                                                                                                                                                                                                                                                                                        each rank histograms the *required bias* ``r_ij = alpha_i - s_ij`` -- the bias that
                                                                                                                                                                                                                                                                                                                        would place expert ``j`` exactly at token ``i``'s cutoff -- into per-expert bins.
                                                                                                                                                                                                                                                                                                                        Counts are additive, so a single integer all-reduce yields the histogram of the
                                                                                                                                                                                                                                                                                                                        pooled global batch, and the estimate is the true global quantile up to the bin
                                                                                                                                                                                                                                                                                                                        width, not an average of per-rank quantiles.  Cost is ``n * B`` integers per layer
                                                                                                                                                                                                                                                                                                                        per step, independent of the token count.
                                                                                                                                                                                                                                                                                                                        """


                                                                                                                                                                                                                                                                                                                        # 【中文释义】本模块实现「Quantile Balancing(QB,分位数均衡)」:一种无辅助损失
                                                                                                                                                                                                                                                                                                                        # (auxiliary-loss-free)的 MoE 路由负载均衡方法(论文 §2.3.3,附录 C、D)。
                                                                                                                                                                                                                                                                                                                        #
                                                                                                                                                                                                                                                                                                                        # 问题:MoE 中不同专家天然热度不均,有的被过度选中、有的饿死(未训练充分)。
                                                                                                                                                                                                                                                                                                                        # 传统做法分两类:
                                                                                                                                                                                                                                                                                                                        #   - 辅助损失(auxiliary loss):在总 loss 上加一项负载均衡惩罚,缺点是与主 loss
                                                                                                                                                                                                                                                                                                                        #     竞争、引入额外超参权重;
                                                                                                                                                                                                                                                                                                                        #   - 固定步长无损失规则:b ← b + γ·sign(target - load)(每步沿负载误差方向挪一小步),
                                                                                                                                                                                                                                                                                                                        #     缺点是有超参步长 γ、收敛慢——在 K3 每层 896 个专家的规模下,慢收敛意味着
                                                                                                                                                                                                                                                                                                                        #     EP 训练长期负载失衡 + 部分专家长期欠训练。
                                                                                                                                                                                                                                                                                                                        #
                                                                                                                                                                                                                                                                                                                        # QB 的思路:不再"挪小步",而是**一步直接跳到让每个专家负载恰好等于目标值的偏置**。
                                                                                                                                                                                                                                                                                                                        # 关键机制:
                                                                                                                                                                                                                                                                                                                        #   1. 路由打分 sigmoid(W_r x),Top-k 选择时用 s + b(带偏置),但混合权重只用
                                                                                                                                                                                                                                                                                                                        #      s 归一化(p_ij = s_ij / Σ s_ir),即偏置只影响"谁被选中",不影响"选中后
                                                                                                                                                                                                                                                                                                                        #      权重有多大"→ 不扭曲路由器的优化目标。
                                                                                                                                                                                                                                                                                                                        #   2. 用 Top-(k+1) 而不是 Top-k:前 k 个是实际路由,第 (k+1) 个 biased score 是
                                                                                                                                                                                                                                                                                                                        #      cutoff α_i(token i 要进入 Top-k 所需超过的阈值)。cutoff 取自路由本身,
                                                                                                                                                                                                                                                                                                                        #      省去单独的 token 侧分位数。
                                                                                                                                                                                                                                                                                                                        #   3. 固定 cutoff 后,"候选偏置下路由到专家 j 的 token 数"关于阈值单调,把它设为
                                                                                                                                                                                                                                                                                                                        #      目标 q = mk/n,就得到偏置 = 第 (q+1) 大的 margin (s_ij - α_i)。即 Eq. 14:
                                                                                                                                                                                                                                                                                                                        #          bhat_j ← -quantile_{1-k/n}(s_{:,j} - α)
                                                                                                                                                                                                                                                                                                                        #          b      ← bhat - mean(bhat)
                                                                                                                                                                                                                                                                                                                        #   4. 附录 C 证明这是"最大打分均衡指派 LP 对偶问题"的精确坐标最小化,因此
                                                                                                                                                                                                                                                                                                                        #      不需要学习率。
                                                                                                                                                                                                                                                                                                                        #
                                                                                                                                                                                                                                                                                                                        # 工程注意点:
                                                                                                                                                                                                                                                                                                                        #   - 更新在**下一步**生效(本批从不用本批算出的偏置路由自己);
                                                                                                                                                                                                                                                                                                                        #   - 推理时偏置冻结(forward 只路由,不 accumulate);
                                                                                                                                                                                                                                                                                                                        #   - 大规模下收集全量 margin 不现实(跨数据并行 rank + 梯度累积步骤),改走
                                                                                                                                                                                                                                                                                                                        #     附录 D 的直方图:每个 rank 把"所需偏置" r_ij = α_i - s_ij 装进逐专家分箱,
                                                                                                                                                                                                                                                                                                                        #     计数可加,一次整数 all-reduce 就得到全局直方图 → 估出的分位数误差至多是
                                                                                                                                                                                                                                                                                                                        #     一个 bin 宽(不是各 rank 分位数的平均)。通信成本固定为 n·B 个整数/层/步,
                                                                                                                                                                                                                                                                                                                        #     与 token 数无关。


                                                                                                                                                                                                                                                                                                                        class RouterOutput:
                                                                                                                                                                                                                                                                                                                            """Routing decision plus everything the balancer needs for its next update."""


                                                                                                                                                                                                                                                                                                                            __slots__ = ("indices", "weights", "scores", "cutoff", "n_tokens")


                                                                                                                                                                                                                                                                                                                            def __init__(
                                                                                                                                                                                                                                                                                                                                self,
                                                                                                                                                                                                                                                                                                                                indices: Tensor,
                                                                                                                                                                                                                                                                                                                                weights: Tensor,
                                                                                                                                                                                                                                                                                                                                scores: Tensor,
                                                                                                                                                                                                                                                                                                                                cutoff: Tensor,
                                                                                                                                                                                                                                                                                                                                n_tokens: int,
                                                                                                                                                                                                                                                                                                                            ):
                                                                                                                                                                                                                                                                                                                                # 【中文释义】一次路由的全部产物:
                                                                                                                                                                                                                                                                                                                                #   - indices:(tokens, k) —— 每个 token 实际选中的 top_k 个专家 id(int64)
                                                                                                                                                                                                                                                                                                                                #   - weights:(tokens, k) —— 归一化混合权重(sigmoid score 在选中集内
                                                                                                                                                                                                                                                                                                                                #     renormalize,与偏置无关)
                                                                                                                                                                                                                                                                                                                                #   - scores: (tokens, n_experts) —— 原始 sigmoid 分数(未加偏置),
                                                                                                                                                                                                                                                                                                                                #     QB 计算 margin 时需要它
                                                                                                                                                                                                                                                                                                                                #   - cutoff: (tokens,),第 (k+1) 个 biased score,即每个 token 的阈值 α
                                                                                                                                                                                                                                                                                                                                #   - n_tokens:tokens 数(供直方图统计规模)
                                                                                                                                                                                                                                                                                                                                # 注意区分:偏置 b 只进 Top-k 选择,不进 weights 的归一化,这是
                                                                                                                                                                                                                                                                                                                                # "无损失"的关键(见模块 docstring)。
                                                                                                                                                                                                                                                                                                                                self.indices = indices        # (tokens, k) long
                                                                                                                                                                                                                                                                                                                                self.weights = weights        # (tokens, k) float
                                                                                                                                                                                                                                                                                                                                self.scores = scores          # (tokens, n_experts) raw sigmoid scores
                                                                                                                                                                                                                                                                                                                                self.cutoff = cutoff          # (tokens,) the (k+1)-th biased score
                                                                                                                                                                                                                                                                                                                                self.n_tokens = n_tokens



                                                                                                                                                                                                                                                                                                                        class QuantileBalancingRouter(nn.Module):
                                                                                                                                                                                                                                                                                                                            bias: Tensor
                                                                                                                                                                                                                                                                                                                            histogram: Tensor
                                                                                                                                                                                                                                                                                                                            hist_lo: Tensor
                                                                                                                                                                                                                                                                                                                            hist_width: Tensor
                                                                                                                                                                                                                                                                                                                            token_count: Tensor
                                                                                                                                                                                                                                                                                                                            load: Tensor


                                                                                                                                                                                                                                                                                                                            def __init__(
                                                                                                                                                                                                                                                                                                                                self,
                                                                                                                                                                                                                                                                                                                                dim: int,
                                                                                                                                                                                                                                                                                                                                n_experts: int,
                                                                                                                                                                                                                                                                                                                                top_k: int,
                                                                                                                                                                                                                                                                                                                                *,
                                                                                                                                                                                                                                                                                                                                enabled: bool = True,
                                                                                                                                                                                                                                                                                                                                bins: int = 1000,
                                                                                                                                                                                                                                                                                                                                ema: float = 0.0,
                                                                                                                                                                                                                                                                                                                            ):
                                                                                                                                                                                                                                                                                                                                super().__init__()
                                                                                                                                                                                                                                                                                                                                self.dim = dim
                                                                                                                                                                                                                                                                                                                                self.n_experts = n_experts
                                                                                                                                                                                                                                                                                                                                self.top_k = top_k
                                                                                                                                                                                                                                                                                                                                self.enabled = enabled
                                                                                                                                                                                                                                                                                                                                self.bins = bins
                                                                                                                                                                                                                                                                                                                                self.ema = ema
                                                                                                                                                                                                                                                                                                                                self.weight = nn.Parameter(torch.empty(n_experts, dim))
                                                                                                                                                                                                                                                                                                                                nn.init.normal_(self.weight, std=dim**-0.5)


                                                                                                                                                                                                                                                                                                                                # Buffers, not parameters: the bias is set by the balancing rule, never by
                                                                                                                                                                                                                                                                                                                                # a gradient, and it is frozen at inference.
                                                                                                                                                                                                                                                                                                                                self.register_buffer("bias", torch.zeros(n_experts))
                                                                                                                                                                                                                                                                                                                                self.register_buffer("histogram", torch.zeros(n_experts, bins, dtype=torch.long))
                                                                                                                                                                                                                                                                                                                                self.register_buffer("hist_lo", torch.zeros(()))
                                                                                                                                                                                                                                                                                                                                self.register_buffer("hist_width", torch.zeros(()))
                                                                                                                                                                                                                                                                                                                                self.register_buffer("token_count", torch.zeros((), dtype=torch.long))
                                                                                                                                                                                                                                                                                                                                self.register_buffer("load", torch.zeros(n_experts, dtype=torch.long))


                                                                                                                                                                                                                                                                                                                            # -- routing -------------------------------------------------------------


                                                                                                                                                                                                                                                                                                                            def forward(self, x: Tensor) -> RouterOutput:
                                                                                                                                                                                                                                                                                                                                """``x`` is ``(tokens, dim)``; the caller flattens batch and sequence."""
                                                                                                                                                                                                                                                                                                                                # 【中文释义】路由打分 = sigmoid(W_r x)。注意与论文一致——训练与推理都是
                                                                                                                                                                                                                                                                                                                                # sigmoid,而不是 softmax(softmax 会把所有专家的分数耦合在一起;sigmoid
                                                                                                                                                                                                                                                                                                                                # 让每个专家独立响应,便于做逐专家分位数均衡)。
                                                                                                                                                                                                                                                                                                                                scores = torch.sigmoid(torch.nn.functional.linear(x.float(), self.weight.float()))
                                                                                                                                                                                                                                                                                                                                biased = scores + self.bias


                                                                                                                                                                                                                                                                                                                                # Top-(k+1): k routes plus the cutoff, in one selection.
                                                                                                                                                                                                                                                                                                                                # 【中文释义】一次 topk 同时拿到"实际路由(前 k 个)"与"阈值 cutoff(第 k+1
                                                                                                                                                                                                                                                                                                                                # 个,biased score)"。它对应论文 Eq. 14 中的 α_i:专家分数 s_ij 必须超过
                                                                                                                                                                                                                                                                                                                                # cutoff 才会进入 token i 的 Top-k。boundary case:当 k+1 > n_experts 时
                                                                                                                                                                                                                                                                                                                                # (top_k 几乎等于全部专家),没有第 k+1 个,取 -inf 占位(即没有门槛)。
                                                                                                                                                                                                                                                                                                                                k1 = min(self.top_k + 1, self.n_experts)
                                                                                                                                                                                                                                                                                                                                top_val, top_idx = torch.topk(biased, k1, dim=-1)
                                                                                                                                                                                                                                                                                                                                indices = top_idx[:, : self.top_k]
                                                                                                                                                                                                                                                                                                                                cutoff = (
                                                                                                                                                                                                                                                                                                                                    top_val[:, self.top_k]
                                                                                                                                                                                                                                                                                                                                    if k1 > self.top_k
                                                                                                                                                                                                                                                                                                                                    else top_val[:, -1].new_full((x.shape[0],), float("-inf"))
                                                                                                                                                                                                                                                                                                                                )


                                                                                                                                                                                                                                                                                                                                # 【中文释义】混合权重只看原始 scores(不带偏置)= 被选中专家的 sigmoid
                                                                                                                                                                                                                                                                                                                                # 分数,在选中的 k 个之间重新归一化(Eq. 11 的 p_ij)。clamp_min 防止
                                                                                                                                                                                                                                                                                                                                # 全部为 0 时除零。
                                                                                                                                                                                                                                                                                                                                chosen = torch.gather(scores, 1, indices)
                                                                                                                                                                                                                                                                                                                                weights = chosen / chosen.sum(dim=-1, keepdim=True).clamp_min(1e-9)


                                                                                                                                                                                                                                                                                                                                if self.training and self.enabled:
                                                                                                                                                                                                                                                                                                                                    self._accumulate(scores.detach(), cutoff.detach(), indices.detach())


                                                                                                                                                                                                                                                                                                                                return RouterOutput(indices, weights.to(x.dtype), scores, cutoff, x.shape[0])


                                                                                                                                                                                                                                                                                                                            # -- balancing -----------------------------------------------------------


                                                                                                                                                                                                                                                                                                                            @torch.no_grad()
                                                                                                                                                                                                                                                                                                                            def _accumulate(self, scores: Tensor, cutoff: Tensor, indices: Tensor) -> None:
                                                                                                                                                                                                                                                                                                                                """Histogram the required bias ``r_ij = alpha_i - s_ij`` (appendix D)."""
                                                                                                                                                                                                                                                                                                                                # 【中文释义】训练时每个前向把一路历史数据压进直方图(附录 D)。
                                                                                                                                                                                                                                                                                                                                # 直接收集"每个 token-专家对的 margin"不可行:M×E 个浮点要跨 rank 聚合。
                                                                                                                                                                                                                                                                                                                                # 改为统计"所需偏置" r_ij = α_i - s_ij(把专家 j 恰好推到 token i 的 cutoff
                                                                                                                                                                                                                                                                                                                                # 所需的偏置值),按专家分成 bins 个桶存计数——计数可加,一次整数 all-reduce
                                                                                                                                                                                                                                                                                                                                # 即得全局直方图。代价恒为 n·B 个整数/层/步,与 token 数无关。
                                                                                                                                                                                                                                                                                                                                b_min = float(self.bias.min())
                                                                                                                                                                                                                                                                                                                                b_max = float(self.bias.max())
                                                                                                                                                                                                                                                                                                                                lo = b_min - 1.0
                                                                                                                                                                                                                                                                                                                                width = (b_max - b_min + 2.0) / self.bins


                                                                                                                                                                                                                                                                                                                                if int(self.token_count) == 0:
                                                                                                                                                                                                                                                                                                                                    self.hist_lo.fill_(lo)
                                                                                                                                                                                                                                                                                                                                    self.hist_width.fill_(width)
                                                                                                                                                                                                                                                                                                                                    self.histogram.zero_()
                                                                                                                                                                                                                                                                                                                                    self.load.zero_()
                                                                                                                                                                                                                                                                                                                                lo = float(self.hist_lo)
                                                                                                                                                                                                                                                                                                                                width = float(self.hist_width)


                                                                                                                                                                                                                                                                                                                                required = cutoff.unsqueeze(1) - scores                  # (tokens, experts)
                                                                                                                                                                                                                                                                                                                                idx = ((required - lo) / width).floor().long().clamp_(0, self.bins - 1)
                                                                                                                                                                                                                                                                                                                                flat = idx + torch.arange(
                                                                                                                                                                                                                                                                                                                                    self.n_experts, device=idx.device
                                                                                                                                                                                                                                                                                                                                ).unsqueeze(0) * self.bins
                                                                                                                                                                                                                                                                                                                                self.histogram.view(-1).scatter_add_(
                                                                                                                                                                                                                                                                                                                                    0, flat.reshape(-1), torch.ones_like(flat.reshape(-1))
                                                                                                                                                                                                                                                                                                                                )
                                                                                                                                                                                                                                                                                                                                self.token_count += scores.shape[0]
                                                                                                                                                                                                                                                                                                                                self.load += torch.bincount(indices.reshape(-1), minlength=self.n_experts)


                                                                                                                                                                                                                                                                                                                            @torch.no_grad()
                                                                                                                                                                                                                                                                                                                            def update_bias(self, group=None) -> Tensor:
                                                                                                                                                                                                                                                                                                                                """Apply Eq. 14 from the pooled histogram.  Call once per optimizer step.


                                                                                                                                                                                                                                                                                                                                Returns the new bias.  The single ``n * bins`` integer all-reduce here is
                                                                                                                                                                                                                                                                                                                                the entire communication cost of load balancing.
                                                                                                                                                                                                                                                                                                                                """
                                                                                                                                                                                                                                                                                                                                # 【中文释义】按直方图估算出的分位数更新偏置(Eq. 14),通常每 optimize step
                                                                                                                                                                                                                                                                                                                                # 调用一次。流程:
                                                                                                                                                                                                                                                                                                                                #   1) all-reduce 直方图与 token 计数(如果多卡):偏置只做负载均衡用,通信量
                                                                                                                                                                                                                                                                                                                                #     就是 n*bins 个整数 / (层, 步);
                                                                                                                                                                                                                                                                                                                                #   2) 目标负载 q = m·k/n(m 个 token,每个选 k 个专家,平均到 n 个专家);
                                                                                                                                                                                                                                                                                                                                #   3) 沿直方图求第 q 大的分箱:对每个专家找"累计计数首次 ≥ q"的 bin,
                                                                                                                                                                                                                                                                                                                                #      再在 bin 内按比例插值得到分位数估计:
                                                                                                                                                                                                                                                                                                                                #         b_hat_j = hist_lo + (bin_idx + frac) * hist_width
                                                                                                                                                                                                                                                                                                                                #      这里 frac 是 (q - before)/counts(bin 已排到那一格后的位置);
                                                                                                                                                                                                                                                                                                                                #   4) 减去均值再 EMA 平滑,写回 bias(Eq. 14 的 mean-centre 处理保证
                                                                                                                                                                                                                                                                                                                                #      sum(b)=0,尺度可控)。
                                                                                                                                                                                                                                                                                                                                if not self.enabled or int(self.token_count) == 0:
                                                                                                                                                                                                                                                                                                                                    return self.bias


                                                                                                                                                                                                                                                                                                                                hist = self.histogram
                                                                                                                                                                                                                                                                                                                                total = self.token_count.clone()
                                                                                                                                                                                                                                                                                                                                if dist.is_available() and dist.is_initialized():
                                                                                                                                                                                                                                                                                                                                    dist.all_reduce(hist, group=group)
                                                                                                                                                                                                                                                                                                                                    dist.all_reduce(total, group=group)


                                                                                                                                                                                                                                                                                                                                m = int(total)
                                                                                                                                                                                                                                                                                                                                q = m * self.top_k / self.n_experts        # target load per expert
                                                                                                                                                                                                                                                                                                                                cum = hist.cumsum(dim=1)
                                                                                                                                                                                                                                                                                                                                target = torch.tensor(q, device=hist.device).ceil()


                                                                                                                                                                                                                                                                                                                                # First bin whose cumulative count reaches the target load.
                                                                                                                                                                                                                                                                                                                                reached = cum >= target
                                                                                                                                                                                                                                                                                                                                bin_idx = torch.where(
                                                                                                                                                                                                                                                                                                                                    reached.any(dim=1),
                                                                                                                                                                                                                                                                                                                                    reached.float().argmax(dim=1),
                                                                                                                                                                                                                                                                                                                                    torch.full((self.n_experts,), self.bins - 1, device=hist.device, dtype=torch.long),
                                                                                                                                                                                                                                                                                                                                )
                                                                                                                                                                                                                                                                                                                                counts = hist.gather(1, bin_idx.unsqueeze(1)).squeeze(1).float()
                                                                                                                                                                                                                                                                                                                                before = cum.gather(1, bin_idx.unsqueeze(1)).squeeze(1).float() - counts
                                                                                                                                                                                                                                                                                                                                frac = torch.where(
                                                                                                                                                                                                                                                                                                                                    counts > 0,
                                                                                                                                                                                                                                                                                                                                    ((q - before) / counts.clamp_min(1.0)).clamp(0.0, 1.0),
                                                                                                                                                                                                                                                                                                                                    torch.zeros_like(counts),
                                                                                                                                                                                                                                                                                                                                )
                                                                                                                                                                                                                                                                                                                                b_hat = self.hist_lo + (bin_idx.float() + frac) * self.hist_width
                                                                                                                                                                                                                                                                                                                                b_hat = b_hat - b_hat.mean()               # mean-centre, Eq. 14


                                                                                                                                                                                                                                                                                                                                if self.ema > 0.0:
                                                                                                                                                                                                                                                                                                                                    b_hat = self.ema * self.bias + (1.0 - self.ema) * b_hat


                                                                                                                                                                                                                                                                                                                                self.bias.copy_(b_hat)
                                                                                                                                                                                                                                                                                                                                self.histogram.zero_()
                                                                                                                                                                                                                                                                                                                                self.token_count.zero_()
                                                                                                                                                                                                                                                                                                                                return self.bias


                                                                                                                                                                                                                                                                                                                            @torch.no_grad()
                                                                                                                                                                                                                                                                                                                            def update_bias_exact(self, scores: Tensor, cutoff: Tensor) -> Tensor:
                                                                                                                                                                                                                                                                                                                                """Exact Eq. 14 on a materialised batch.  Test oracle for the histogram."""
                                                                                                                                                                                                                                                                                                                                # 【中文释义】直接用真分位数 torch.quantile 在一整批显式张量上算 Eq. 14:
                                                                                                                                                                                                                                                                                                                                #   b_hat_j = -quantile_{1-k/n}(... ) = quantile 在 margin 上取 top_k/n 分位,
                                                                                                                                                                                                                                                                                                                                #   再 mean-centre。由于直方图法只是它的降精度近似(误差 ≤ 一个 bin 宽),
                                                                                                                                                                                                                                                                                                                                #   update_bias_exact 专门作为直方图的测试 oracle(test 对照)。
                                                                                                                                                                                                                                                                                                                                required = cutoff.unsqueeze(1) - scores
                                                                                                                                                                                                                                                                                                                                qq = self.top_k / self.n_experts
                                                                                                                                                                                                                                                                                                                                b_hat = torch.quantile(required.float(), qq, dim=0)
                                                                                                                                                                                                                                                                                                                                b_hat = b_hat - b_hat.mean()
                                                                                                                                                                                                                                                                                                                                self.bias.copy_(b_hat)
                                                                                                                                                                                                                                                                                                                                return self.bias


                                                                                                                                                                                                                                                                                                                            @torch.no_grad()
                                                                                                                                                                                                                                                                                                                            def load_balance_stats(self) -> dict[str, float]:
                                                                                                                                                                                                                                                                                                                                """Max/min load ratio and coefficient of variation over the last window."""
                                                                                                                                                                                                                                                                                                                                # 【中文释义】负载均衡的量化健康指标,供 demo / 监控观察偏置更新前后的变化:
                                                                                                                                                                                                                                                                                                                                #   - max_min_ratio:最忙专家 / 最闲专家 的负载比(理想 ≈1)
                                                                                                                                                                                                                                                                                                                                #   - cv:负载的变异系数(std / mean,理想 → 0)
                                                                                                                                                                                                                                                                                                                                #   - max_over_mean:峰值负载与均值的比值(理想 ≈1)
                                                                                                                                                                                                                                                                                                                                load = self.load.float()
                                                                                                                                                                                                                                                                                                                                if float(load.sum()) == 0:
                                                                                                                                                                                                                                                                                                                                    return {"max_min_ratio": 1.0, "cv": 0.0, "max_over_mean": 1.0}
                                                                                                                                                                                                                                                                                                                                mean = load.mean()
                                                                                                                                                                                                                                                                                                                                return {
                                                                                                                                                                                                                                                                                                                                    "max_min_ratio": float(load.max() / load.min().clamp_min(1.0)),
                                                                                                                                                                                                                                                                                                                                    "cv": float(load.std() / mean.clamp_min(1e-9)),
                                                                                                                                                                                                                                                                                                                                    "max_over_mean": float(load.max() / mean.clamp_min(1e-9)),
                                                                                                                                                                                                                                                                                                                                }


                                                                                                                                                                                                                                                                                                                            def extra_repr(self) -> str:
                                                                                                                                                                                                                                                                                                                                return (
                                                                                                                                                                                                                                                                                                                                    f"dim={self.dim}, experts={self.n_experts}, top_k={self.top_k}, "
                                                                                                                                                                                                                                                                                                                                    f"qb={self.enabled}, bins={self.bins}"
                                                                                                                                                                                                                                                                                                                                )

                                                                                                                                                                                                                                                                                                                        B.4 深入分析

                                                                                                                                                                                                                                                                                                                        B.4.1 与把 bias 写进权重,到底有何区别

                                                                                                                                                                                                                                                                                                                        先看现有实现(K3 实际形态):

                                                                                                                                                                                                                                                                                                                          biased  = scores + self.bias            # router_qb.py:168 —— 选择用
                                                                                                                                                                                                                                                                                                                          indices = topk(biased, k)[idx]           # router_qb.py:176 —— b 决定"选中谁"
                                                                                                                                                                                                                                                                                                                          cutoff  = top_val[:, top_k]              # router_qb.py:178-182 —— 第(k+1)个 biased score
                                                                                                                                                                                                                                                                                                                          chosen  = gather(scores, indices)        # router_qb.py:187 —— 权重用【原始】scores
                                                                                                                                                                                                                                                                                                                          weights = chosen / chosen.sum(-1)        # router_qb.py:188 —— 不含 bias

                                                                                                                                                                                                                                                                                                                          对比两种写法的实际差异:

                                                                                                                                                                                                                                                                                                                          维度

                                                                                                                                                                                                                                                                                                                          bias 不进权重(K3)

                                                                                                                                                                                                                                                                                                                          bias 写进权重

                                                                                                                                                                                                                                                                                                                          输出公式

                                                                                                                                                                                                                                                                                                                          y = Σ_{e∈T} (s_e/Σs)·E_e(x)

                                                                                                                                                                                                                                                                                                                          ,与 b 无关

                                                                                                                                                                                                                                                                                                                          y = Σ_{e∈T} ((s_e+b_e)/Σ(s+b))·E_e(x)

                                                                                                                                                                                                                                                                                                                          ,b 直接参与输出组合

                                                                                                                                                                                                                                                                                                                          负载均衡器是否改变模型输出

                                                                                                                                                                                                                                                                                                                          否

                                                                                                                                                                                                                                                                                                                          ——均衡只改"谁被选中",选完的组合系数是内容驱动

                                                                                                                                                                                                                                                                                                                          是

                                                                                                                                                                                                                                                                                                                          ——一旦 update_bias 每步更新 b,输出分布随之跳变。即,偏置一更新,整个输出分布摇动 → 权重语义被"负载均衡器"污染而非真概率

                                                                                                                                                                                                                                                                                                                          梯度

                                                                                                                                                                                                                                                                                                                          b 是 register_buffer(router_qb.py:153),不进计算图,forward 中 weights 不依赖 b → b 无 grad,训练目标不被污染

                                                                                                                                                                                                                                                                                                                          若 b 做成 nn.Parameter:b 获得梯度,优化器会拿负载均衡与任务 loss 两个目标同时推 b,相互打架;若 b 仍是 buffer 但权重用 s+b:b 成为计算图常量,输出被 b 扭曲却没有任何机制去修正它——一个"只加不改"的死偏置

                                                                                                                                                                                                                                                                                                                          语义

                                                                                                                                                                                                                                                                                                                          选择=排序+阈值(b 参与),权重=相对置信(纯内容),两相正交

                                                                                                                                                                                                                                                                                                                          负载均衡被"写"成模型对专家的隐藏偏好,token 无关

                                                                                                                                                                                                                                                                                                                          正解:

                                                                                                                                                                                                                                                                                                                          • b 负责"把哪个专家拉进/踢出 top-k"(不影响各单给多少)。这是"无损失负载均衡"的关键设计——QB 更新的是 buffer(register_buffer,router_qb.py:153),不走 autograd,因此均衡器不干预训练目标。

                                                                                                                                                                                                                                                                                                                          • 选择的天然形式是"排序 + 阈值"(b 参与),权重的天然形式是"相对置信"(b 不参与)。 两者分离才能让"负载均衡"与"任务学习"正交。

                                                                                                                                                                                                                                                                                                                          一处容易误解的点:

                                                                                                                                                                                                                                                                                                                          • softmax 全专家归一时,给所有专家加同一个常数会被分母抵消——但 bias 是逐专家不同的(b_j≠b_k),写在权重里会被真实地放大/削弱各自专家的输出强度。这正是"污染"所在:b 是为"凑齐负载"算出来的,不是为"这个 token 该听谁"算出来的,把它掺进权重等于把调度副作用写进模型语义。

                                                                                                                                                                                                                                                                                                                          B.4.2 bias 怎么"训练"的

                                                                                                                                                                                                                                                                                                                          关键认知:bias 训练不靠梯度下降,靠平衡规则的重算。它是 register_buffer(非 Parameter),但在训练中每个 optimizer step 被确定性规则覆盖:

                                                                                                                                                                                                                                                                                                                            每个 forward(train & enabled):              每个 optimizer step:
                                                                                                                                                                                                                                                                                                                            _accumulate(scores, cutoff, indices)  ──────►  update_bias(group)
                                                                                                                                                                                                                                                                                                                              · 把 r_ij = α_i − s_ij 分箱填直方图          · all_reduce 直方图(多卡)
                                                                                                                                                                                                                                                                                                                              · token_count += bt                        · q = m·k/n  ← 目标负载
                                                                                                                                                                                                                                                                                                                              · load += bincount(indices)                · cumsum → argmax 首个≥target 的 bin
                                                                                                                                                                                                                                                                                                                                                                         · 箱内插值 frac → b_hat
                                                                                                                                                                                                                                                                                                                                                                         · b_hat − mean(b_hat)   (route_qb.py)
                                                                                                                                                                                                                                                                                                                                                                         · 写回 bias buffer,清空直方图

                                                                                                                                                                                                                                                                                                                            所以:

                                                                                                                                                                                                                                                                                                                            • 它也在训练:每步都在变(reflected by _accumulate + update_bias),但它变了;准确性靠的是「分位数一阶直达」,不是梯度数值下降。

                                                                                                                                                                                                                                                                                                                            • 它不需要梯度也能被训练:传统"训练=梯度下降"对参数而言;对 buffer 而言,更新者不是 optimizer,而是你自己写的规则 update_bias(router_qb.py:230)。它读取离线收集的数据(直方图),每个 optimizer step 调用一次。

                                                                                                                                                                                                                                                                                                                            • 为什么此处 buffer 而非 Parameter:

                                                                                                                                                                                                                                                                                                                              1. 不让优化器碰它(否则两个优化目标打架,§问题一);

                                                                                                                                                                                                                                                                                                                              2. 训练时更新、推理冻结:forward 只在 self.training and self.enabled 时调用 _accumulate(router_qb.py:190),推理时 b 恒等于最后一次 update 的值。

                                                                                                                                                                                                                                                                                                                            一句总结:bias 的"训练" = 基于负载统计的确定性重算(每步直方图 → 分位数 → 覆盖),而非基于损失梯度的学习。所以它是"被算法更新",不是"被 optimizer 训练"。

                                                                                                                                                                                                                                                                                                                            B.4.3 QB 分位数为何能把"每 token 选 k 个、n−k 个落选"对齐

                                                                                                                                                                                                                                                                                                                            • 路由用 Top-k 天然满足"每个 token 恰好选 k 个、n−k 落选"(由 topk 本身保证)。

                                                                                                                                                                                                                                                                                                                            • 真正难的是全局公平:让 每个专家 的"被选中次数"趋近 target q = m·k/n(m=tokens)。

                                                                                                                                                                                                                                                                                                                            核心推导(router_qb 注释 + 论文 Eq.14)

                                                                                                                                                                                                                                                                                                                            记"所需偏置":

                                                                                                                                                                                                                                                                                                                              r_ij = α_i − s_ij        # 把专家 j 恰好推到 token i 的 cutoff 所需的偏置量

                                                                                                                                                                                                                                                                                                                              固定 α_i(路由自身的 (k+1)-th biased score,不重新算),在偏置 b 下:

                                                                                                                                                                                                                                                                                                                                token i 的专家 j 进入 top-k   ⟺   s_ij + b_j ≥ α_i
                                                                                                                                                                                                                                                                                                                                                            ⟺   r_ij ≤ b_j                    (i.e. b_j 为该列要的偏置阈值)

                                                                                                                                                                                                                                                                                                                                所以 专家 j 的负载(被选中次数)= #{i : r_ij ≤ b_j},它是 b_j 的单调不减函数(对排序单调)。

                                                                                                                                                                                                                                                                                                                                目标负载:q = m·k/n(每 token 贡献 k 个选中名额,分摊给 n 个专家)。

                                                                                                                                                                                                                                                                                                                                → 求"使负载 = q 时的 b_j" ⟺ 取 b_j 为 r_{:,j} 的第 q 个分位数(每个专家一列,分数可排):

                                                                                                                                                                                                                                                                                                                                  b*_j = quantile_{1-k/n}(r_{:,j})       # ↑ 推导:恰好把负载推到 q 的阈值

                                                                                                                                                                                                                                                                                                                                  再加均值中心化(sum(b)=0,尺度可控):b ← b* − mean(b*)。这就是 Eq.14,也是 update_bias_exact(router_qb.py:287-298)做的。

                                                                                                                                                                                                                                                                                                                                  为什么" 一步到 target"

                                                                                                                                                                                                                                                                                                                                  因为 q 是直接目标,不是"挪一步"。固定的单调性 + 分位数的通用性让每个专家分位数恰好命中目标负载,无需梯度、无需学习率(第一步就等于最优解)。

                                                                                                                                                                                                                                                                                                                                  "每 token 一定 k 个" 的保障
                                                                                                                                                                                                                                                                                                                                  • token 粒度:由 Top-(k+1) 的 indices = topk(biased, k) 硬保证(router_qb.py:176)——每行恰好 k 个 index,排除了所有其他专家。

                                                                                                                                                                                                                                                                                                                                  • 专家粒度:由 QB 的 b 保证"整体公平"(每个专家大约被选中 q 次)。两层独立并行 → 合成"结构性稀疏 + 负载均衡"两全。

                                                                                                                                                                                                                                                                                                                                  直觉对照(论文 §4.4):如果不做 b 更新,热门专家(其 r 分布偏小)会被反复选中。QB 把热门专家的 b_j 调低——由 s_ij + b_j ≥ α_i 可知 b_j 越低,需要 s_ij 越高才进得了 top-k,等效"提高门槛";冷专家反之,b_j 抬高、更容易被选中。于是每个专家的被选中次数逐渐向 q 平齐。

                                                                                                                                                                                                                                                                                                                                  B.5 逐专家 sigmoid vs softmax:为何 sigmoid 更好

                                                                                                                                                                                                                                                                                                                                  为什么路由用 sigmoid 而非 softmax?这是因为:softmax 全局耦合,bias 差语义;sigmoid 逐专家独立,QB 对每列做分位秩更方便。

                                                                                                                                                                                                                                                                                                                                  B.5.1 两套打分的数学形态

                                                                                                                                                                                                                                                                                                                                  softmax(标准 MoE,DeepSeek 参照):

                                                                                                                                                                                                                                                                                                                                    s = W_r x                    # (tokens, E) 任意实数
                                                                                                                                                                                                                                                                                                                                    p_j = exp(s_j) / Σ_{e=1}^E exp(s_e)     # 全局归一,所有专家竞争同一个概率质量

                                                                                                                                                                                                                                                                                                                                    sigmoid(本实现,router_qb.py:167):

                                                                                                                                                                                                                                                                                                                                      s_j = σ(W_r x)_j = 1/(1+e^{-z_j})      # 逐专家独立,(tokens, E),每列 ∈ (0,1)
                                                                                                                                                                                                                                                                                                                                      p_j = s_j / Σ_{e∈T} s_e               # 只在选中的 top-k 内部归一(router_qb.py:187-188)

                                                                                                                                                                                                                                                                                                                                      B.5.2 sigmoid 更好的四点理由

                                                                                                                                                                                                                                                                                                                                      维度

                                                                                                                                                                                                                                                                                                                                      softmax

                                                                                                                                                                                                                                                                                                                                      sigmoid(K3)

                                                                                                                                                                                                                                                                                                                                      专家的耦合度

                                                                                                                                                                                                                                                                                                                                      全局耦合——改任一专家分数,所有专家权重变化(质量守恒)

                                                                                                                                                                                                                                                                                                                                      逐专家独立激活,互不干扰

                                                                                                                                                                                                                                                                                                                                      偏置语义

                                                                                                                                                                                                                                                                                                                                      bias 进权重会因分母 Σexp 而连锁扭曲

                                                                                                                                                                                                                                                                                                                                      +b 只移动本列阈值,语义干净

                                                                                                                                                                                                                                                                                                                                      负载均衡

                                                                                                                                                                                                                                                                                                                                      分位数统计被"全局竞争"污染

                                                                                                                                                                                                                                                                                                                                      每列独立分布,可直接逐专家取分位数(QB 前置条件)

                                                                                                                                                                                                                                                                                                                                      动态范围

                                                                                                                                                                                                                                                                                                                                      无界 logits → fp8 溢出

                                                                                                                                                                                                                                                                                                                                      σ∈(0,1) 有界、数值友好

                                                                                                                                                                                                                                                                                                                                      核心逻辑:K3 负载均衡(QB)需要对"某专家是否被选中"做逐列分位数操作。若用 softmax,专家的"倾向度"是被全体共享的概率质量——调整 b 会连带重塑分布形状,Eq.14 的逐列分位数统计(router_qb.py:218 required = cutoff − scores)就失去独立性。而 sigmoid 让 s_j 与 s_{j'} 解耦,margin_{ij} = s_ij − α_i 能独立于其他列被排序/分箱。

                                                                                                                                                                                                                                                                                                                                       

                                                                                                                                                                                                                                                                                                                                      补充:Top-k 选择结果在两种打分下等价(σ 单调递增,排序不变)。真正区别只发生在权重归一化:softmax over all vs 选中集内 renorm。K3 采用后者,使得"未选中专家不消耗任何概率质量",这也是偏置能自由进选择域的原因之一。

                                                                                                                                                                                                                                                                                                                                      ”

                                                                                                                                                                                                                                                                                                                                      B.5.3 用代码位置佐证

                                                                                                                                                                                                                                                                                                                                      • router_qb.py:167 scores = sigmoid(W_r x)

                                                                                                                                                                                                                                                                                                                                      • router_qb.py:187-188 weights = chosen / chosen.sum(...)(选中集内归一,不含 bias)

                                                                                                                                                                                                                                                                                                                                      B.6 样例

                                                                                                                                                                                                                                                                                                                                      本样例目标是看清楚一批 token 产生的向量,如何变成新的bias,以及这个 bias 如何参与下一批 token 的 Top-k 分配。

                                                                                                                                                                                                                                                                                                                                      对应实现:

                                                                                                                                                                                                                                                                                                                                      • scores = sigmoid(W_r x):原始路由分数;

                                                                                                                                                                                                                                                                                                                                      • biased = scores + bias:只用于选择专家;

                                                                                                                                                                                                                                                                                                                                      • topk(biased, k + 1):前 k 个是实际专家,第 k+1 个是 cutoff;

                                                                                                                                                                                                                                                                                                                                      • weights = scores_selected / sum(scores_selected):混合权重不使用 bias;

                                                                                                                                                                                                                                                                                                                                      • _accumulate:累计 required = cutoff - scores;

                                                                                                                                                                                                                                                                                                                                      • update_bias_exact:用完整矩阵计算精确分位数;

                                                                                                                                                                                                                                                                                                                                      • update_bias:实际训练中用直方图近似分位数。

                                                                                                                                                                                                                                                                                                                                      B.6.1. 样例设置

                                                                                                                                                                                                                                                                                                                                      为便于手算,取:

                                                                                                                                                                                                                                                                                                                                        专家数 n = 4
                                                                                                                                                                                                                                                                                                                                        top-k  k = 2
                                                                                                                                                                                                                                                                                                                                        token 数 m = 4
                                                                                                                                                                                                                                                                                                                                        初始 bias = [0, 0, 0, 0]

                                                                                                                                                                                                                                                                                                                                        下面直接给出 sigmoid(W_r x) 的结果。每一行是一个 token,每一列是一个专家:

                                                                                                                                                                                                                                                                                                                                                           expert 0  expert 1  expert 2  expert 3
                                                                                                                                                                                                                                                                                                                                          token 0             0.90      0.80      0.20      0.10
                                                                                                                                                                                                                                                                                                                                          token 1             0.85      0.75      0.30      0.20
                                                                                                                                                                                                                                                                                                                                          token 2             0.80      0.70      0.40      0.30
                                                                                                                                                                                                                                                                                                                                          token 3             0.75      0.65      0.50      0.40

                                                                                                                                                                                                                                                                                                                                          这对应代码中的:

                                                                                                                                                                                                                                                                                                                                            scores = torch.sigmoid(
                                                                                                                                                                                                                                                                                                                                                torch.nn.functional.linear(x.float(), self.weight.float())
                                                                                                                                                                                                                                                                                                                                            )
                                                                                                                                                                                                                                                                                                                                            biased = scores + self.bias

                                                                                                                                                                                                                                                                                                                                            初始 bias 全零,所以第一批的 biased 与 scores 相同。

                                                                                                                                                                                                                                                                                                                                            B.6.2. 第一批:Top-(k+1) 同时产生路由和 cutoff

                                                                                                                                                                                                                                                                                                                                            这里 k + 1 = 3,所以每个 token 取 biased score 最大的 3 个值。前 2 个是实际路由,第三个是 cutoff alpha。

                                                                                                                                                                                                                                                                                                                                            token 0

                                                                                                                                                                                                                                                                                                                                              biased score: [0.90, 0.80, 0.20, 0.10]
                                                                                                                                                                                                                                                                                                                                              排序结果:    e0=0.90, e1=0.80, e2=0.20
                                                                                                                                                                                                                                                                                                                                              indices:     [e0, e1]
                                                                                                                                                                                                                                                                                                                                              cutoff α:    0.20

                                                                                                                                                                                                                                                                                                                                              token 1

                                                                                                                                                                                                                                                                                                                                                biased score: [0.85, 0.75, 0.30, 0.20]
                                                                                                                                                                                                                                                                                                                                                排序结果:    e0=0.85, e1=0.75, e2=0.30
                                                                                                                                                                                                                                                                                                                                                indices:     [e0, e1]
                                                                                                                                                                                                                                                                                                                                                cutoff α:    0.30

                                                                                                                                                                                                                                                                                                                                                token 2

                                                                                                                                                                                                                                                                                                                                                  biased score: [0.80, 0.70, 0.40, 0.30]
                                                                                                                                                                                                                                                                                                                                                  排序结果:    e0=0.80, e1=0.70, e2=0.40
                                                                                                                                                                                                                                                                                                                                                  indices:     [e0, e1]
                                                                                                                                                                                                                                                                                                                                                  cutoff α:    0.40

                                                                                                                                                                                                                                                                                                                                                  token 3

                                                                                                                                                                                                                                                                                                                                                    biased score: [0.75, 0.65, 0.50, 0.40]
                                                                                                                                                                                                                                                                                                                                                    排序结果:    e0=0.75, e1=0.65, e2=0.50
                                                                                                                                                                                                                                                                                                                                                    indices:     [e0, e1]
                                                                                                                                                                                                                                                                                                                                                    cutoff α:    0.50

                                                                                                                                                                                                                                                                                                                                                    因此第一批的负载是:

                                                                                                                                                                                                                                                                                                                                                      expert 0: 4
                                                                                                                                                                                                                                                                                                                                                      expert 1: 4
                                                                                                                                                                                                                                                                                                                                                      expert 2: 0
                                                                                                                                                                                                                                                                                                                                                      expert 3: 0

                                                                                                                                                                                                                                                                                                                                                      平均目标负载为:

                                                                                                                                                                                                                                                                                                                                                        q = m * k / n = 4 * 2 / 4 = 2

                                                                                                                                                                                                                                                                                                                                                        也就是说,理想情况下每个专家被选中 2 次,而不是专家 0、1 各 4 次,专家 2、3 一次也没有。

                                                                                                                                                                                                                                                                                                                                                        B.6.3. 第一批的混合权重:只看原始 score

                                                                                                                                                                                                                                                                                                                                                        以 token 0 为例,选中专家是 e0 和 e1:

                                                                                                                                                                                                                                                                                                                                                          raw selected scores = [0.90, 0.80]
                                                                                                                                                                                                                                                                                                                                                          sum                 = 1.70
                                                                                                                                                                                                                                                                                                                                                          weights             = [0.90 / 1.70, 0.80 / 1.70]
                                                                                                                                                                                                                                                                                                                                                                              ≈ [0.5294, 0.4706]

                                                                                                                                                                                                                                                                                                                                                          代码是:

                                                                                                                                                                                                                                                                                                                                                            chosen = torch.gather(scores, 1, indices)
                                                                                                                                                                                                                                                                                                                                                            weights = chosen / chosen.sum(dim=-1, keepdim=True).clamp_min(1e-9)

                                                                                                                                                                                                                                                                                                                                                            注意:如果某个专家因为 bias 被选中,weights 仍然使用它原来的score,不会把 score + bias 放进归一化。因此 bias 负责“选谁”,不负责“选中后占多大权重”。

                                                                                                                                                                                                                                                                                                                                                            B.6.4. 每个 token 为每个专家计算所需 bias

                                                                                                                                                                                                                                                                                                                                                            路由器把 cutoff 与原始 score 相减:

                                                                                                                                                                                                                                                                                                                                                              required = cutoff.unsqueeze(1) - scores

                                                                                                                                                                                                                                                                                                                                                              required[i, j] 的含义是:专家 j 需要加多少 bias,才能刚好达到 token i 的 cutoff。

                                                                                                                                                                                                                                                                                                                                                              token 0:cutoff = 0.20

                                                                                                                                                                                                                                                                                                                                                                required[0] = [0.20-0.90, 0.20-0.80, 0.20-0.20, 0.20-0.10]
                                                                                                                                                                                                                                                                                                                                                                            = [-0.70, -0.60,  0.00,  0.10]


                                                                                                                                                                                                                                                                                                                                                                token 1:cutoff = 0.30

                                                                                                                                                                                                                                                                                                                                                                  required[1] = [0.30-0.85, 0.30-0.75, 0.30-0.30, 0.30-0.20]
                                                                                                                                                                                                                                                                                                                                                                              = [-0.55, -0.45,  0.00,  0.10]


                                                                                                                                                                                                                                                                                                                                                                  token 2:cutoff = 0.40

                                                                                                                                                                                                                                                                                                                                                                    required[2] = [0.40-0.80, 0.40-0.70, 0.40-0.40, 0.40-0.30]
                                                                                                                                                                                                                                                                                                                                                                                = [-0.40, -0.30,  0.00,  0.10]


                                                                                                                                                                                                                                                                                                                                                                    token 3:cutoff = 0.50

                                                                                                                                                                                                                                                                                                                                                                      required[3] = [0.50-0.75, 0.50-0.65, 0.50-0.50, 0.50-0.40]
                                                                                                                                                                                                                                                                                                                                                                                  = [-0.25, -0.15,  0.00,  0.10]


                                                                                                                                                                                                                                                                                                                                                                      把四个 token 叠起来:

                                                                                                                                                                                                                                                                                                                                                                        required =
                                                                                                                                                                                                                                                                                                                                                                        [
                                                                                                                                                                                                                                                                                                                                                                          [-0.70, -0.60, 0.00, 0.10],
                                                                                                                                                                                                                                                                                                                                                                          [-0.55, -0.45, 0.00, 0.10],
                                                                                                                                                                                                                                                                                                                                                                          [-0.40, -0.30, 0.00, 0.10],
                                                                                                                                                                                                                                                                                                                                                                          [-0.25, -0.15, 0.00, 0.10],
                                                                                                                                                                                                                                                                                                                                                                        ]

                                                                                                                                                                                                                                                                                                                                                                        按列看:

                                                                                                                                                                                                                                                                                                                                                                          expert 0: [-0.70, -0.55, -0.40, -0.25]
                                                                                                                                                                                                                                                                                                                                                                          expert 1: [-0.60, -0.45, -0.30, -0.15]
                                                                                                                                                                                                                                                                                                                                                                          expert 2: [ 0.00,  0.00,  0.00,  0.00]
                                                                                                                                                                                                                                                                                                                                                                          expert 3: [ 0.10,  0.10,  0.10,  0.10]

                                                                                                                                                                                                                                                                                                                                                                          这已经直接暴露了负载问题:

                                                                                                                                                                                                                                                                                                                                                                          • expert 0、1 的 required 很小,稍微加一点甚至减一点就能跨过 cutoff,所以它们容易被选中;

                                                                                                                                                                                                                                                                                                                                                                          • expert 2 需要约 0.00 的 bias;

                                                                                                                                                                                                                                                                                                                                                                          • expert 3 需要约 0.10 的 bias,必须明显抬高才有机会进入 Top-k。

                                                                                                                                                                                                                                                                                                                                                                          B.6.5. 用分位数一步得到新的 bias

                                                                                                                                                                                                                                                                                                                                                                          目标分位数位置是:

                                                                                                                                                                                                                                                                                                                                                                            top_k / n_experts = 2 / 4 = 0.5

                                                                                                                                                                                                                                                                                                                                                                            update_bias_exact 等价于:

                                                                                                                                                                                                                                                                                                                                                                              required = cutoff.unsqueeze(1) - scores
                                                                                                                                                                                                                                                                                                                                                                              qq = self.top_k / self.n_experts
                                                                                                                                                                                                                                                                                                                                                                              b_hat = torch.quantile(required.float(), qq, dim=0)
                                                                                                                                                                                                                                                                                                                                                                              b_hat = b_hat - b_hat.mean()

                                                                                                                                                                                                                                                                                                                                                                              对每一列取 0.5 分位数。PyTorch 默认使用线性插值,因此这里的中位数是中间两个值的平均:

                                                                                                                                                                                                                                                                                                                                                                                expert 0: median([-0.70, -0.55, -0.40, -0.25])
                                                                                                                                                                                                                                                                                                                                                                                          = (-0.55 + -0.40) / 2
                                                                                                                                                                                                                                                                                                                                                                                          = -0.475


                                                                                                                                                                                                                                                                                                                                                                                expert 1: median([-0.60, -0.45, -0.30, -0.15])
                                                                                                                                                                                                                                                                                                                                                                                          = (-0.45 + -0.30) / 2
                                                                                                                                                                                                                                                                                                                                                                                          = -0.375


                                                                                                                                                                                                                                                                                                                                                                                expert 2: median([0.00, 0.00, 0.00, 0.00]) = 0.000
                                                                                                                                                                                                                                                                                                                                                                                expert 3: median([0.10, 0.10, 0.10, 0.10]) = 0.100

                                                                                                                                                                                                                                                                                                                                                                                所以未中心化的结果是:

                                                                                                                                                                                                                                                                                                                                                                                  b_hat = [-0.475, -0.375, 0.000, 0.100]

                                                                                                                                                                                                                                                                                                                                                                                  均值为:

                                                                                                                                                                                                                                                                                                                                                                                    mean(b_hat) = (-0.475 - 0.375 + 0.000 + 0.100) / 4
                                                                                                                                                                                                                                                                                                                                                                                                = -0.1875

                                                                                                                                                                                                                                                                                                                                                                                    减去均值后,写回 router 的 bias:

                                                                                                                                                                                                                                                                                                                                                                                      b_new = b_hat - mean(b_hat)
                                                                                                                                                                                                                                                                                                                                                                                            = [-0.2875, -0.1875, 0.1875, 0.2875]

                                                                                                                                                                                                                                                                                                                                                                                      这个方向很直观:

                                                                                                                                                                                                                                                                                                                                                                                      • 热门的 expert 0、1 被减分;

                                                                                                                                                                                                                                                                                                                                                                                      • 冷门的 expert 2、3 被加分;

                                                                                                                                                                                                                                                                                                                                                                                      • bias 均值为 0,只改变专家之间的相对排序,不让所有分数一起漂移。

                                                                                                                                                                                                                                                                                                                                                                                      B.6.6. 下一批:新 bias 如何改变分配

                                                                                                                                                                                                                                                                                                                                                                                      重要时序是:

                                                                                                                                                                                                                                                                                                                                                                                        batch 0: forward,使用旧 bias
                                                                                                                                                                                                                                                                                                                                                                                                 accumulate(required)
                                                                                                                                                                                                                                                                                                                                                                                        optimizer step: update_bias()
                                                                                                                                                                                                                                                                                                                                                                                        batch 1: forward,才使用新 bias

                                                                                                                                                                                                                                                                                                                                                                                        本批统计出来的 bias 不会回头重路由本批。

                                                                                                                                                                                                                                                                                                                                                                                        假设下一批的原始 score 是:

                                                                                                                                                                                                                                                                                                                                                                                                           expert 0  expert 1  expert 2  expert 3
                                                                                                                                                                                                                                                                                                                                                                                          token 0             0.60      0.55      0.58      0.57
                                                                                                                                                                                                                                                                                                                                                                                          token 1             0.65      0.60      0.59      0.56
                                                                                                                                                                                                                                                                                                                                                                                          token 2             0.55      0.52      0.62      0.61
                                                                                                                                                                                                                                                                                                                                                                                          token 3             0.50      0.48      0.58      0.57



                                                                                                                                                                                                                                                                                                                                                                                          token 0

                                                                                                                                                                                                                                                                                                                                                                                            raw scores:   [0.60, 0.55, 0.58, 0.57]
                                                                                                                                                                                                                                                                                                                                                                                            new bias:     [-0.2875, -0.1875, 0.1875, 0.2875]
                                                                                                                                                                                                                                                                                                                                                                                            biased:       [0.3125, 0.3625, 0.7675, 0.8575]
                                                                                                                                                                                                                                                                                                                                                                                            排序:         e3, e2, e1
                                                                                                                                                                                                                                                                                                                                                                                            indices:      [e3, e2]
                                                                                                                                                                                                                                                                                                                                                                                            cutoff α:     0.3625


                                                                                                                                                                                                                                                                                                                                                                                            新的 bias 把路由从热门的 e0/e1 推向冷门的 e2/e3。

                                                                                                                                                                                                                                                                                                                                                                                            但 weights 仍然用原始分数:

                                                                                                                                                                                                                                                                                                                                                                                              weights = [score(e3), score(e2)] / (score(e3) + score(e2))
                                                                                                                                                                                                                                                                                                                                                                                                      = [0.57, 0.58] / 1.15
                                                                                                                                                                                                                                                                                                                                                                                                      ≈ [0.4957, 0.5043]

                                                                                                                                                                                                                                                                                                                                                                                              token 1

                                                                                                                                                                                                                                                                                                                                                                                                raw scores:   [0.65, 0.60, 0.59, 0.56]
                                                                                                                                                                                                                                                                                                                                                                                                biased:       [0.3625, 0.4125, 0.7775, 0.8475]
                                                                                                                                                                                                                                                                                                                                                                                                排序:         e3, e2, e1
                                                                                                                                                                                                                                                                                                                                                                                                indices:      [e3, e2]
                                                                                                                                                                                                                                                                                                                                                                                                cutoff α:     0.4125
                                                                                                                                                                                                                                                                                                                                                                                                weights:      [0.56, 0.59] / 1.15 ≈ [0.4870, 0.5130]

                                                                                                                                                                                                                                                                                                                                                                                                token 2

                                                                                                                                                                                                                                                                                                                                                                                                  raw scores:   [0.55, 0.52, 0.62, 0.61]
                                                                                                                                                                                                                                                                                                                                                                                                  biased:       [0.2625, 0.3325, 0.8075, 0.8975]
                                                                                                                                                                                                                                                                                                                                                                                                  排序:         e3, e2, e1
                                                                                                                                                                                                                                                                                                                                                                                                  indices:      [e3, e2]
                                                                                                                                                                                                                                                                                                                                                                                                  cutoff α:     0.3325
                                                                                                                                                                                                                                                                                                                                                                                                  weights:      [0.61, 0.62] / 1.23 ≈ [0.4959, 0.5041]

                                                                                                                                                                                                                                                                                                                                                                                                  token 3

                                                                                                                                                                                                                                                                                                                                                                                                    raw scores:   [0.50, 0.48, 0.58, 0.57]
                                                                                                                                                                                                                                                                                                                                                                                                    biased:       [0.2125, 0.2925, 0.7675, 0.8575]
                                                                                                                                                                                                                                                                                                                                                                                                    排序:         e3, e2, e1
                                                                                                                                                                                                                                                                                                                                                                                                    indices:      [e3, e2]
                                                                                                                                                                                                                                                                                                                                                                                                    cutoff α:     0.2925
                                                                                                                                                                                                                                                                                                                                                                                                    weights:      [0.57, 0.58] / 1.15 ≈ [0.4957, 0.5043]

                                                                                                                                                                                                                                                                                                                                                                                                    这个特意构造的第二批展示了“方向”而非保证单个 batch 立刻完美均衡:

                                                                                                                                                                                                                                                                                                                                                                                                      第一批 indices: [e0,e1], [e0,e1], [e0,e1], [e0,e1]
                                                                                                                                                                                                                                                                                                                                                                                                      第二批 indices: [e3,e2], [e3,e2], [e3,e2], [e3,e2]

                                                                                                                                                                                                                                                                                                                                                                                                      实际训练中 token 分布更丰富,新的 bias 会改变不同 token 的排序;QB 统计的是大量 token 上每个专家的 required 分布,而不是强行让每一个小 batch 都呈现固定模式。

                                                                                                                                                                                                                                                                                                                                                                                                      B.6.7. 代码中的完整闭环

                                                                                                                                                                                                                                                                                                                                                                                                      把上面的数学过程压缩成代码时,核心链路是:

                                                                                                                                                                                                                                                                                                                                                                                                        # batch t
                                                                                                                                                                                                                                                                                                                                                                                                        out = router(x_t)
                                                                                                                                                                                                                                                                                                                                                                                                        # out.indices: 实际 top-k 专家
                                                                                                                                                                                                                                                                                                                                                                                                        # out.weights: 只由 raw scores 归一化得到
                                                                                                                                                                                                                                                                                                                                                                                                        # out.cutoff: 每个 token 的第 k+1 个 biased score
                                                                                                                                                                                                                                                                                                                                                                                                        # router._accumulate(...) 已在 training forward 中记录 required


                                                                                                                                                                                                                                                                                                                                                                                                        # optimizer step 结束时
                                                                                                                                                                                                                                                                                                                                                                                                        router.update_bias()


                                                                                                                                                                                                                                                                                                                                                                                                        # batch t+1
                                                                                                                                                                                                                                                                                                                                                                                                        out_next = router(x_next)  # 这里才读取新 bias

                                                                                                                                                                                                                                                                                                                                                                                                        forward 内部对应:

                                                                                                                                                                                                                                                                                                                                                                                                          scores = sigmoid(linear(x, weight))
                                                                                                                                                                                                                                                                                                                                                                                                          biased = scores + bias
                                                                                                                                                                                                                                                                                                                                                                                                          top_val, top_idx = torch.topk(biased, top_k + 1, dim=-1)
                                                                                                                                                                                                                                                                                                                                                                                                          indices = top_idx[:, :top_k]
                                                                                                                                                                                                                                                                                                                                                                                                          cutoff = top_val[:, top_k]
                                                                                                                                                                                                                                                                                                                                                                                                          chosen = gather(scores, 1, indices)
                                                                                                                                                                                                                                                                                                                                                                                                          weights = chosen / chosen.sum(dim=-1, keepdim=True)

                                                                                                                                                                                                                                                                                                                                                                                                          训练时 _accumulate 再做:

                                                                                                                                                                                                                                                                                                                                                                                                            required = cutoff[:, None] - scores

                                                                                                                                                                                                                                                                                                                                                                                                            精确测试路径直接对 required 做 torch.quantile;大规模训练路径不保存所有浮点 required,而是将它们按专家分桶,累计 histogram[expert, bin],然后在 update_bias 中:

                                                                                                                                                                                                                                                                                                                                                                                                              cum = histogram.cumsum(dim=1)
                                                                                                                                                                                                                                                                                                                                                                                                              找到首次达到 q 的 bin
                                                                                                                                                                                                                                                                                                                                                                                                              在该 bin 内插值
                                                                                                                                                                                                                                                                                                                                                                                                              b_hat = hist_lo + (bin_idx + frac) * hist_width
                                                                                                                                                                                                                                                                                                                                                                                                              bias = b_hat - b_hat.mean()


                                                                                                                                                                                                                                                                                                                                                                                                              因此,update_bias_exact 是数学上的 oracle,update_bias 是工程上的低通信近似。

                                                                                                                                                                                                                                                                                                                                                                                                              B.6.8. 映射到 K3 的真实规模

                                                                                                                                                                                                                                                                                                                                                                                                              K3 默认配置在 config.py 中是:

                                                                                                                                                                                                                                                                                                                                                                                                                n_routed = 896
                                                                                                                                                                                                                                                                                                                                                                                                                top_k    = 16
                                                                                                                                                                                                                                                                                                                                                                                                                qb_bins  = 1000
                                                                                                                                                                                                                                                                                                                                                                                                                qb_ema   = 0.0


                                                                                                                                                                                                                                                                                                                                                                                                                对一批 m 个 token,平均目标负载是:

                                                                                                                                                                                                                                                                                                                                                                                                                  q = m * 16 / 896 = m / 56


                                                                                                                                                                                                                                                                                                                                                                                                                  每个 token 仍然只产生一个 cutoff,但每个 cutoff 要和 896 个 raw score 相减,于是形成 (m, 896) 的 required 矩阵。生产规模下:

                                                                                                                                                                                                                                                                                                                                                                                                                  1. 每个 data-parallel rank 对每个专家的 required 值做 1000-bin 计数;

                                                                                                                                                                                                                                                                                                                                                                                                                  2. 对形状为 (896, 1000) 的整数 histogram 做一次 all-reduce;

                                                                                                                                                                                                                                                                                                                                                                                                                  3. 每个专家沿 bin 维做累计计数,定位目标分位数;

                                                                                                                                                                                                                                                                                                                                                                                                                  4. 得到新的 896 维 bias;

                                                                                                                                                                                                                                                                                                                                                                                                                  5. 下一次 forward 使用它。

                                                                                                                                                                                                                                                                                                                                                                                                                  通信量与 token 数无关,主要是 896 * 1000 个整数的直方图;代价是用一个 bin 宽度以内的误差换取不收集全部 token-expert 浮点值。

                                                                                                                                                                                                                                                                                                                                                                                                                  B.6.9. 一句话总结

                                                                                                                                                                                                                                                                                                                                                                                                                  QB 不是“看到某个专家过热,就把它的 bias 慢慢减一点”,而是:

                                                                                                                                                                                                                                                                                                                                                                                                                    本批 cutoff - raw score
                                                                                                                                                                                                                                                                                                                                                                                                                            → 每个专家的 required 向量
                                                                                                                                                                                                                                                                                                                                                                                                                            → 目标分位数
                                                                                                                                                                                                                                                                                                                                                                                                                            → mean-centred bias
                                                                                                                                                                                                                                                                                                                                                                                                                            → 下一批改变 Top-k 选择


                                                                                                                                                                                                                                                                                                                                                                                                                    其中 bias 只改变“选谁”,不改变“选中后如何按 raw score 混合”,并且总是在下一批才生效。


                                                                                                                                                                                                                                                                                                                                                                                                                    TransFormer-封面
                                                                                                                                                                                                                                                                                                                                                                                                                    TransFormer-封面

                                                                                                                                                                                                                                                                                                                                                                                                                    0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                    阅读原文

                                                                                                                                                                                                                                                                                                                                                                                                                    跳转微信打开

                                                                                                                                                                                                                                                                                                                                                                                                                    •  

                                                                                                                                                                                                                                                                                                                                                                                                                    【轻量化复刻大模型 / KIMI K3】AttnRes 模块交互式演示

                                                                                                                                                                                                                                                                                                                                                                                                                    原创 罗西的思考 2026-11-12 21:38 北京

                                                                                                                                                                                                                                                                                                                                                                                                                    【轻量化复刻大模型 / KIMI K3】AttnRes 模块交互式演示

                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x00 概述
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x01 核心数学
                                                                                                                                                                                                                                                                                                                                                                                                                      • 1.1 Block vs Full
                                                                                                                                                                                                                                                                                                                                                                                                                      • 1.2 状态机 API
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x02 Tab 1: Demo 四联图
                                                                                                                                                                                                                                                                                                                                                                                                                      • 2.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                      • 2.2 Copy 任务是什么
                                                                                                                                                                                                                                                                                                                                                                                                                      • 2.3 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                      • 2.4 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                      • 2.5 调节建议
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x03 Tab 2: 范式对比
                                                                                                                                                                                                                                                                                                                                                                                                                      • 3.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                      • 3.2 前向范数实验
                                                                                                                                                                                                                                                                                                                                                                                                                      • 3.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                      • 3.4 深度-时间对偶性
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x04 Tab 3: Block vs Full
                                                                                                                                                                                                                                                                                                                                                                                                                      • 4.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                      • 4.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                      • 4.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                      • 4.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x05 Tab 4: Embedding 源
                                                                                                                                                                                                                                                                                                                                                                                                                      • 5.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                      • 5.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                      • 5.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                      • 5.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x06 Tab 5: 内存有界
                                                                                                                                                                                                                                                                                                                                                                                                                      • 6.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                      • 6.2 "source 数 ≤ 块数 + 常数" 三个数的含义
                                                                                                                                                                                                                                                                                                                                                                                                                      • 6.3 "峰值 = 块数 + 2" 的推导
                                                                                                                                                                                                                                                                                                                                                                                                                      • 6.4 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                      • 6.5 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                      • 6.6 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x07 Tab 6: 权重分布
                                                                                                                                                                                                                                                                                                                                                                                                                      • 7.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                      • 7.2 alpha 的概念
                                                                                                                                                                                                                                                                                                                                                                                                                      • 7.3 为什么在这里展示
                                                                                                                                                                                                                                                                                                                                                                                                                      • 7.4 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                      • 7.5 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                      • 7.6 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x08 Tab 7: RMSNorm 防垄断
                                                                                                                                                                                                                                                                                                                                                                                                                      • 8.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                      • 8.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                      • 8.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                      • 8.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x9 Tab 8: 梯度流
                                                                                                                                                                                                                                                                                                                                                                                                                      • 9.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                      • 9.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                      • 9.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                      • 9.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0x10 Tab 9: 2.8T 配置
                                                                                                                                                                                                                                                                                                                                                                                                                      • 10.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                      • 10.2 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                      • 10.3 关键数值
                                                                                                                                                                                                                                                                                                                                                                                                                      • 10.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                      • 10.5 代码复用策略
                                                                                                                                                                                                                                                                                                                                                                                                                      • 10.5 验证策略总览
                                                                                                                                                                                                                                                                                                                                                                                                                    • 0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                    0x00 概述

                                                                                                                                                                                                                                                                                                                                                                                                                    本文是AttnRes (Attention Residuals) 的完整交互式演示,9 个 Tab 覆盖深度注意力混合的核心机制、Block vs Full 形式对比、内存有界性验证、RMSNorm 防垄断、梯度流通等。全部 CPU 实时运行,复用 attn_res.py 和 norm.py 真实源码算子。

                                                                                                                                                                                                                                                                                                                                                                                                                    如何启动:

                                                                                                                                                                                                                                                                                                                                                                                                                      python experiments\models\llm\kimi_k3\modules\attnres\gradio_attnres_demo.py

                                                                                                                                                                                                                                                                                                                                                                                                                      浏览器打开 http://localhost:7860

                                                                                                                                                                                                                                                                                                                                                                                                                      注:

                                                                                                                                                                                                                                                                                                                                                                                                                      • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

                                                                                                                                                                                                                                                                                                                                                                                                                      • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

                                                                                                                                                                                                                                                                                                                                                                                                                      • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

                                                                                                                                                                                                                                                                                                                                                                                                                      • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

                                                                                                                                                                                                                                                                                                                                                                                                                      • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

                                                                                                                                                                                                                                                                                                                                                                                                                      • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

                                                                                                                                                                                                                                                                                                                                                                                                                      • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                                                                                                                                                                                                                                                                                                                      • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。

                                                                                                                                                                                                                                                                                                                                                                                                                      0x01 核心数学

                                                                                                                                                                                                                                                                                                                                                                                                                      AttnRes 把 attention 从时间维迁移到深度维— 标准残差流把所有历史输出等权相加(深度维的无差别瓶颈),AttnRes 让第 l 层用一个可学习伪查询去软注意之前所有层的输出:

                                                                                                                                                                                                                                                                                                                                                                                                                        q_l = w_l                     # 可学习伪查询(每层一个向量)
                                                                                                                                                                                                                                                                                                                                                                                                                        k_i = v_i = f_i(h_i),  k_0 = v_0 = h_1   # embedding 永远是源
                                                                                                                                                                                                                                                                                                                                                                                                                        phi(q, k) = exp(q^T RMSNorm(k))          # 打分核(RMSNorm 防幅值垄断)
                                                                                                                                                                                                                                                                                                                                                                                                                        alpha_{i->l} = phi(q_l, k_i) / sum_j phi  # softmax 归一化
                                                                                                                                                                                                                                                                                                                                                                                                                        h_l = sum_i alpha_{i->l} v_i             # 加权混合(Eq. 9)

                                                                                                                                                                                                                                                                                                                                                                                                                        关键洞察: h_l 是混合本身,不是 "上一状态 + 新增"。均匀累加只是 alpha 的一个退化设置。

                                                                                                                                                                                                                                                                                                                                                                                                                        1.1 Block vs Full

                                                                                                                                                                                                                                                                                                                                                                                                                        • Full 形式 (Eqs. 8‑9):每层输出都保留为独立 source,算术 O (L²d)、内存 O (Ld)

                                                                                                                                                                                                                                                                                                                                                                                                                        • Block 形式 (Eq. 10):把 L 层切成 N 块,每块塌缩成单个求和表示 b_n,内存降到 O (Nd)

                                                                                                                                                                                                                                                                                                                                                                                                                        • 退化关系: block_units=1 时 Block 自动退化为 Full

                                                                                                                                                                                                                                                                                                                                                                                                                        1.2 状态机 API

                                                                                                                                                                                                                                                                                                                                                                                                                          state = attnres.init_state(embedding)  # b_0 = h_1
                                                                                                                                                                                                                                                                                                                                                                                                                          for i, layer in enumerate(layers):
                                                                                                                                                                                                                                                                                                                                                                                                                              h = attnres.mix(state, i)          # 深度注意力混合
                                                                                                                                                                                                                                                                                                                                                                                                                              out = layer(h)                     # 子层变换
                                                                                                                                                                                                                                                                                                                                                                                                                              state = attnres.add_output(state, out)  # 块归档
                                                                                                                                                                                                                                                                                                                                                                                                                          out = attnres.finalize(state)          # 最终聚合

                                                                                                                                                                                                                                                                                                                                                                                                                          0x02 Tab 1: Demo 四联图

                                                                                                                                                                                                                                                                                                                                                                                                                          2.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                          通过一个 copy 任务的训练过程,展示 AttnRes 的核心行为:训练前 alpha 均匀(等价标准残差),训练后 alpha 学会重点读 embedding;Block 形式内存有界 vs Full 形式线性增长;AttnRes vs 标准残差的训练收敛速度对比。

                                                                                                                                                                                                                                                                                                                                                                                                                          2.2 Copy 任务是什么

                                                                                                                                                                                                                                                                                                                                                                                                                          Copy 任务定义:给定随机输入 x, 模型输出必须逼近 x 本身(即 target = input)。损失函数为 MSE。

                                                                                                                                                                                                                                                                                                                                                                                                                          训练代码位于 gradio_attnres_demo.py 第 190‑203 行 (tab_demo_four 函数内),也复用于 demo_attn_res.py 第 131‑145 行:

                                                                                                                                                                                                                                                                                                                                                                                                                            for step in range(steps):
                                                                                                                                                                                                                                                                                                                                                                                                                                x = torch.randn(batch, 1, dim)        # 随机输入
                                                                                                                                                                                                                                                                                                                                                                                                                                opt.zero_grad()
                                                                                                                                                                                                                                                                                                                                                                                                                                out_a, _ = _forward_attnres(layers, attnres, x)
                                                                                                                                                                                                                                                                                                                                                                                                                                la = torch.nn.functional.mse_loss(out_a, x)  # 目标 = 输入 x
                                                                                                                                                                                                                                                                                                                                                                                                                                la.backward()
                                                                                                                                                                                                                                                                                                                                                                                                                                opt.step()

                                                                                                                                                                                                                                                                                                                                                                                                                            为什么用 copy 任务: 标准残差把 6 层输出等权加起来,输入信息被逐层稀释;AttnRes 则学会通过 softmax 注意力把权重集中在 embedding (source 1) 上,从而直接读回 x。这是最简单的验证 AttnRes "选择性读取" 能力的任务。

                                                                                                                                                                                                                                                                                                                                                                                                                            具体演示了 4 件事:

                                                                                                                                                                                                                                                                                                                                                                                                                            1. w=0 初始化 == 均匀 == 标准残差:训练前最后 unit 的 alpha = [0.3333, 0.3333, 0.3333](softmax(0) 均匀),与"等权相加"无差别 —— 这就是"从 baseline 平滑出发"的实锤(论文零初始化要求)。

                                                                                                                                                                                                                                                                                                                                                                                                                            2. 选择性读取:训练后同一 unit 的 alpha = [0.0422, 0.0003, 0.9575]——模型学会把权重集中在 embedding 源上直接读回输入;而纯残差只能把 6 层输出等权相加(输入被稀释)。这也复现了论文的"embedding 作为深度维 attention sink"。

                                                                                                                                                                                                                                                                                                                                                                                                                            3. 收敛优势:相同层权重、唯一区别是路由方式,AttnRes 最终 MSE 7.57e-5 vs 标准残差 0.0572(约 750 倍差距),验证了"input-dependent 深度路由是关键增益"。

                                                                                                                                                                                                                                                                                                                                                                                                                            4. Block 内存有界:源数演进 Block [1,2,2,2,3,3,3](n_units=6、block_units=3 时最多 3 个源)vs Full [1,2,3,4,5,6,7](线性增长)—— 印证 O(Ld)→O(Nd) 的内存降维。

                                                                                                                                                                                                                                                                                                                                                                                                                            2.3 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                            参数

                                                                                                                                                                                                                                                                                                                                                                                                                            范围

                                                                                                                                                                                                                                                                                                                                                                                                                            默认

                                                                                                                                                                                                                                                                                                                                                                                                                            调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                            dim

                                                                                                                                                                                                                                                                                                                                                                                                                            4‑64

                                                                                                                                                                                                                                                                                                                                                                                                                            16

                                                                                                                                                                                                                                                                                                                                                                                                                            隐藏维度。增大 → 模型容量更高,训练更慢但可能更准

                                                                                                                                                                                                                                                                                                                                                                                                                            n_units

                                                                                                                                                                                                                                                                                                                                                                                                                            2‑20

                                                                                                                                                                                                                                                                                                                                                                                                                            6

                                                                                                                                                                                                                                                                                                                                                                                                                            子层数量。增大 → 深度更深,alpha 分布更复杂

                                                                                                                                                                                                                                                                                                                                                                                                                            block_units

                                                                                                                                                                                                                                                                                                                                                                                                                            1‑10

                                                                                                                                                                                                                                                                                                                                                                                                                            3

                                                                                                                                                                                                                                                                                                                                                                                                                            块大小。增大 → Full 形式;增大 → 块数减少,内存更低但精度可能下降

                                                                                                                                                                                                                                                                                                                                                                                                                            steps

                                                                                                                                                                                                                                                                                                                                                                                                                            50‑500

                                                                                                                                                                                                                                                                                                                                                                                                                            260

                                                                                                                                                                                                                                                                                                                                                                                                                            训练步数。增大 → 训练更充分,alpha 分布更分化

                                                                                                                                                                                                                                                                                                                                                                                                                            batch

                                                                                                                                                                                                                                                                                                                                                                                                                            4‑64

                                                                                                                                                                                                                                                                                                                                                                                                                            16

                                                                                                                                                                                                                                                                                                                                                                                                                            批大小。增大 → 梯度更稳定,训练更平滑

                                                                                                                                                                                                                                                                                                                                                                                                                            lr

                                                                                                                                                                                                                                                                                                                                                                                                                            0.005‑0.1

                                                                                                                                                                                                                                                                                                                                                                                                                            0.02

                                                                                                                                                                                                                                                                                                                                                                                                                            学习率。增大 → 收敛更快但可能不稳定

                                                                                                                                                                                                                                                                                                                                                                                                                            2.4 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                            tab-1
                                                                                                                                                                                                                                                                                                                                                                                                                            tab-1

                                                                                                                                                                                                                                                                                                                                                                                                                            2×2 四联图:

                                                                                                                                                                                                                                                                                                                                                                                                                            • 左上 (a): 训练前 alpha

                                                                                                                                                                                                                                                                                                                                                                                                                              • 灰色折线图,X 轴 = source 编号,Y 轴 = alpha 权重

                                                                                                                                                                                                                                                                                                                                                                                                                              • 初始时 queries 权重接近 0 → softmax 输出近似均匀 → 所有 source 权重相等

                                                                                                                                                                                                                                                                                                                                                                                                                              • 这就是标准残差的行为: h_l = h_{l‑1} + F_l(h_{l‑1}) 等价于 alpha 全等

                                                                                                                                                                                                                                                                                                                                                                                                                            • 右上 (b): 训练后 alpha

                                                                                                                                                                                                                                                                                                                                                                                                                              • 柱状图,红色柱 = argmax(学到的最重要源),蓝色柱 = 其他 source

                                                                                                                                                                                                                                                                                                                                                                                                                              • 训练后 argmax 是 source 3(最新块,alpha ≈ 0.49),不是 embedding(alpha ≈ 0.10)

                                                                                                                                                                                                                                                                                                                                                                                                                              • 物理意义:copy 任务的目标 = 输入本身,最后一层输出最接近输入,所以模型学到"读最新层比读 embedding 更直接"

                                                                                                                                                                                                                                                                                                                                                                                                                              • 原描述"embedding 显著增大"是错的——实际上 embedding 的 alpha 反而最小(0.10),因为它是"最远的源"

                                                                                                                                                                                                                                                                                                                                                                                                                              • 这恰好验证了 AttnRes 的核心价值:模型能学到内容相关的深度选择,而不是盲目累加

                                                                                                                                                                                                                                                                                                                                                                                                                            • 左下 (c): 可见源数演进

                                                                                                                                                                                                                                                                                                                                                                                                                              • 两条折线:Block (阶梯形,有上界) vs Full (线性增长)

                                                                                                                                                                                                                                                                                                                                                                                                                              • 红色虚线: Block 上界 (n_units //block_units + 2)

                                                                                                                                                                                                                                                                                                                                                                                                                              • Block 形式:每 block_units 个 unit 归档一次 → source 数阶梯式增长

                                                                                                                                                                                                                                                                                                                                                                                                                              • Full 形式:每个 unit 都保留 → source 数 = unit 编号 + 1,线性增长到 n_units

                                                                                                                                                                                                                                                                                                                                                                                                                            • 右下 (d): 训练曲线

                                                                                                                                                                                                                                                                                                                                                                                                                              • 两条 log‑scale 曲线:AttnRes (蓝) vs 标准残差 (橙)

                                                                                                                                                                                                                                                                                                                                                                                                                              • AttnRes 收敛更快: 深度注意力让每层能选择性读取有用的历史表示

                                                                                                                                                                                                                                                                                                                                                                                                                              • 最终 MSE 更低: copy 任务中 AttnRes 的 input‑dependent 混合优于标准残差的固定等权

                                                                                                                                                                                                                                                                                                                                                                                                                            • 验证了哪些观点:demo 第 2、3 点验证"固定伪查询可学出选择模式"与"softmax 让选择更锐利";第 1 点验证"零初始化 = 从标准残差平滑出发"。

                                                                                                                                                                                                                                                                                                                                                                                                                            2.5 调节建议

                                                                                                                                                                                                                                                                                                                                                                                                                            • 想看 alpha 更分化 → 增大 steps 到 400+

                                                                                                                                                                                                                                                                                                                                                                                                                            • 想看 Block vs Full 内存差异 → 增大 n_units 到 15+

                                                                                                                                                                                                                                                                                                                                                                                                                            • 想看 Full 形式 → 设 block_units=1


                                                                                                                                                                                                                                                                                                                                                                                                                            0x03 Tab 2: 范式对比

                                                                                                                                                                                                                                                                                                                                                                                                                            3.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                            对比深度维连接的三种范式:标准残差、mHC (流形约束超连接)、AttnRes。展示架构图 + 深度‑时间对偶性 + 量化指标。

                                                                                                                                                                                                                                                                                                                                                                                                                            3.2 前向范数实验

                                                                                                                                                                                                                                                                                                                                                                                                                            设置 32/64/128 层,隐藏维 512。比较:

                                                                                                                                                                                                                                                                                                                                                                                                                            1. 标准 PreNorm 残差。

                                                                                                                                                                                                                                                                                                                                                                                                                            2. 残差缩放或 DeepNorm 风格缩放。

                                                                                                                                                                                                                                                                                                                                                                                                                            3. Full AttnRes。

                                                                                                                                                                                                                                                                                                                                                                                                                            4. Block AttnRes, block size 2/4/8/16。

                                                                                                                                                                                                                                                                                                                                                                                                                            记录每层:||h_l||、新增 delta 的相对占比 ||delta|| / ||h_l||、softmax 最大权重、entropy。

                                                                                                                                                                                                                                                                                                                                                                                                                            预期:标准残差范数随深度增长;AttnRes 混合值范数更接近历史源最大范数;Block AttnRes 在块内仍有局部增长,在边界处更平稳。

                                                                                                                                                                                                                                                                                                                                                                                                                            3.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                            tab-2
                                                                                                                                                                                                                                                                                                                                                                                                                            tab-2

                                                                                                                                                                                                                                                                                                                                                                                                                            2×3 布局:

                                                                                                                                                                                                                                                                                                                                                                                                                            上排三个架构图:

                                                                                                                                                                                                                                                                                                                                                                                                                            位置

                                                                                                                                                                                                                                                                                                                                                                                                                            范式

                                                                                                                                                                                                                                                                                                                                                                                                                            核心机制

                                                                                                                                                                                                                                                                                                                                                                                                                            权重来源

                                                                                                                                                                                                                                                                                                                                                                                                                            input‑dependent

                                                                                                                                                                                                                                                                                                                                                                                                                            (1) 左

                                                                                                                                                                                                                                                                                                                                                                                                                            标准残差

                                                                                                                                                                                                                                                                                                                                                                                                                            h_l = h_{l‑1} + F_l(h_{l‑1})

                                                                                                                                                                                                                                                                                                                                                                                                                            固定 1

                                                                                                                                                                                                                                                                                                                                                                                                                            否

                                                                                                                                                                                                                                                                                                                                                                                                                            (2) 中

                                                                                                                                                                                                                                                                                                                                                                                                                            mHC

                                                                                                                                                                                                                                                                                                                                                                                                                            m 条平行流 + 双随机转移矩阵

                                                                                                                                                                                                                                                                                                                                                                                                                            学习 + 双随机投影

                                                                                                                                                                                                                                                                                                                                                                                                                            否

                                                                                                                                                                                                                                                                                                                                                                                                                            (3) 右

                                                                                                                                                                                                                                                                                                                                                                                                                            AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                            深度维 softmax 注意力

                                                                                                                                                                                                                                                                                                                                                                                                                            学习 + 输入相关 softmax

                                                                                                                                                                                                                                                                                                                                                                                                                            是

                                                                                                                                                                                                                                                                                                                                                                                                                            每个架构图底部有量化条,显示:权重来源、input‑dependent、状态大小、每层 I/O、Table 4 困惑度。

                                                                                                                                                                                                                                                                                                                                                                                                                            下排三个分析图:

                                                                                                                                                                                                                                                                                                                                                                                                                            位置

                                                                                                                                                                                                                                                                                                                                                                                                                            内容

                                                                                                                                                                                                                                                                                                                                                                                                                            该看什么

                                                                                                                                                                                                                                                                                                                                                                                                                            左下

                                                                                                                                                                                                                                                                                                                                                                                                                            深度‑时间对偶性

                                                                                                                                                                                                                                                                                                                                                                                                                            三阶段演进:等权加法 → 矩阵流动 → 内容寻址

                                                                                                                                                                                                                                                                                                                                                                                                                            中下

                                                                                                                                                                                                                                                                                                                                                                                                                            每层内存 I/O

                                                                                                                                                                                                                                                                                                                                                                                                                            标准残差 3d, mHC 34d, AttnRes (Block) 5.5d

                                                                                                                                                                                                                                                                                                                                                                                                                            右下

                                                                                                                                                                                                                                                                                                                                                                                                                            16 层困惑度

                                                                                                                                                                                                                                                                                                                                                                                                                            标准残差 1.766, mHC 1.747, AttnRes (Full) 1.737, AttnRes (Block) 1.746

                                                                                                                                                                                                                                                                                                                                                                                                                            3.4 深度-时间对偶性

                                                                                                                                                                                                                                                                                                                                                                                                                            论文 §6.2 的核心洞察:

                                                                                                                                                                                                                                                                                                                                                                                                                              序列建模:linear attention → softmax attention


                                                                                                                                                                                                                                                                                                                                                                                                                              深度建模:标准残差 → mHC → AttnRes


                                                                                                                                                                                                                                                                                                                                                                                                                                   (等权加法) (矩阵流动) (内容寻址)
                                                                                                                                                                                                                                                                                                                                                                                                                              • 标准残差 = 深度维的 linear attention (等权,无选择性)

                                                                                                                                                                                                                                                                                                                                                                                                                              • mHC = 深度维的 linear attention (学习转移矩阵,但权重与输入无关)

                                                                                                                                                                                                                                                                                                                                                                                                                              • AttnRes = 深度维的 softmax attention (input‑dependent 内容寻址)

                                                                                                                                                                                                                                                                                                                                                                                                                              AttnRes 的关键增益: input‑dependent— 每层根据当前输入内容决定读哪些历史深度,而非固定模式。


                                                                                                                                                                                                                                                                                                                                                                                                                              0x04 Tab 3: Block vs Full

                                                                                                                                                                                                                                                                                                                                                                                                                              4.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                              验证 block_units=1 时 Block 形式自动退化为 Full 形式。这是 Block 实现正确性的基础锚点。测试套件因此不需要维护两套深层实现,Block 一处实现覆盖两种语义。

                                                                                                                                                                                                                                                                                                                                                                                                                              4.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                              参数

                                                                                                                                                                                                                                                                                                                                                                                                                              范围

                                                                                                                                                                                                                                                                                                                                                                                                                              默认

                                                                                                                                                                                                                                                                                                                                                                                                                              调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                              dim

                                                                                                                                                                                                                                                                                                                                                                                                                              4‑32

                                                                                                                                                                                                                                                                                                                                                                                                                              8

                                                                                                                                                                                                                                                                                                                                                                                                                              隐藏维度

                                                                                                                                                                                                                                                                                                                                                                                                                              n_units

                                                                                                                                                                                                                                                                                                                                                                                                                              2‑20

                                                                                                                                                                                                                                                                                                                                                                                                                              6

                                                                                                                                                                                                                                                                                                                                                                                                                              子层数量

                                                                                                                                                                                                                                                                                                                                                                                                                              seed

                                                                                                                                                                                                                                                                                                                                                                                                                              0‑10

                                                                                                                                                                                                                                                                                                                                                                                                                              0

                                                                                                                                                                                                                                                                                                                                                                                                                              随机种子

                                                                                                                                                                                                                                                                                                                                                                                                                              4.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                              tab-3
                                                                                                                                                                                                                                                                                                                                                                                                                              tab-3

                                                                                                                                                                                                                                                                                                                                                                                                                              1×2 布局:

                                                                                                                                                                                                                                                                                                                                                                                                                              • 左图:逐块最大绝对误差

                                                                                                                                                                                                                                                                                                                                                                                                                                • 当 block_units=1 时,每个 unit 输出立即归档为一个"块",Block 应退化为 Full

                                                                                                                                                                                                                                                                                                                                                                                                                                • 理想情况:所有块误差 = 0(Block 与 Full 逐位一致)

                                                                                                                                                                                                                                                                                                                                                                                                                                • 实际渲染问题:所有 diff 确实为 0,但 log scale 下 bar(0) 画不出来(log(0) = -inf),导致左图空白

                                                                                                                                                                                                                                                                                                                                                                                                                                • 修复:当所有误差 < 1e-12 时,改用文本标注"所有块误差 = 0(Block 与 Full 逐位一致)"

                                                                                                                                                                                                                                                                                                                                                                                                                                • 结论:Block(block_units=1) 与 Full 数学等价,Block 是 Full 的泛化——差异仅在内存策略,不在表达能力

                                                                                                                                                                                                                                                                                                                                                                                                                              • 右图:逐层 alpha 均值对比

                                                                                                                                                                                                                                                                                                                                                                                                                                • 蓝色圆点线 = 模块状态机算出的 alpha 均值

                                                                                                                                                                                                                                                                                                                                                                                                                                • 橙色方块虚线 = 朴素 Full 实现算出的 alpha 均值

                                                                                                                                                                                                                                                                                                                                                                                                                                • 理想情况: 两条线完全重合

                                                                                                                                                                                                                                                                                                                                                                                                                              4.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                              Block 是 Full 的泛化(block_units=1 是退化)。如果退化失败,说明 Block 的归档逻辑(何时把 partial 并入 blocks、何时清空)有 bug。


                                                                                                                                                                                                                                                                                                                                                                                                                              0x05 Tab 4: Embedding 源

                                                                                                                                                                                                                                                                                                                                                                                                                              5.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                              验证 embedding 永远是 sources()[0] (b_0 = h_1 约定)。任何深度的层都能读到最初的输入表示。

                                                                                                                                                                                                                                                                                                                                                                                                                              5.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                              参数

                                                                                                                                                                                                                                                                                                                                                                                                                              范围

                                                                                                                                                                                                                                                                                                                                                                                                                              默认

                                                                                                                                                                                                                                                                                                                                                                                                                              调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                              dim

                                                                                                                                                                                                                                                                                                                                                                                                                              4‑32

                                                                                                                                                                                                                                                                                                                                                                                                                              8

                                                                                                                                                                                                                                                                                                                                                                                                                              隐藏维度

                                                                                                                                                                                                                                                                                                                                                                                                                              n_units

                                                                                                                                                                                                                                                                                                                                                                                                                              2‑24

                                                                                                                                                                                                                                                                                                                                                                                                                              12

                                                                                                                                                                                                                                                                                                                                                                                                                              子层数量。增大 → 验证更深处的 embedding 保持性

                                                                                                                                                                                                                                                                                                                                                                                                                              block_units

                                                                                                                                                                                                                                                                                                                                                                                                                              1‑12

                                                                                                                                                                                                                                                                                                                                                                                                                              4

                                                                                                                                                                                                                                                                                                                                                                                                                              块大小。增大 → 块归档更少,验证更极端的压缩下 embedding 仍保持

                                                                                                                                                                                                                                                                                                                                                                                                                              seed

                                                                                                                                                                                                                                                                                                                                                                                                                              0‑10

                                                                                                                                                                                                                                                                                                                                                                                                                              0

                                                                                                                                                                                                                                                                                                                                                                                                                              随机种子

                                                                                                                                                                                                                                                                                                                                                                                                                              5.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                              tab-4
                                                                                                                                                                                                                                                                                                                                                                                                                              tab-4

                                                                                                                                                                                                                                                                                                                                                                                                                              1×2 布局:

                                                                                                                                                                                                                                                                                                                                                                                                                              • 左图:embedding 保持检查

                                                                                                                                                                                                                                                                                                                                                                                                                                • 绿色柱状图,每根柱 = 1.0 (embedding == sources ()[0])

                                                                                                                                                                                                                                                                                                                                                                                                                                • 如果出现 0.0 柱 → 严重 bug: embedding 在某步被覆盖或丢失

                                                                                                                                                                                                                                                                                                                                                                                                                              • 右图:可见 source 数演进

                                                                                                                                                                                                                                                                                                                                                                                                                                • 紫色折线,阶梯形增长 (每 block_units 个 unit 归档一次,source 数 +1)

                                                                                                                                                                                                                                                                                                                                                                                                                                • 红色虚线 = 上界 (block_units + 2)

                                                                                                                                                                                                                                                                                                                                                                                                                                • 默认配置 (n_units=12, block_units=4) 下,source 数演进为 [1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4]

                                                                                                                                                                                                                                                                                                                                                                                                                                • 规律:每 block_units 步 source 数 +1,在两次归档之间保持不变

                                                                                                                                                                                                                                                                                                                                                                                                                              5.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                              论文规定 k_0 = v_0 = h_1 (embedding 永远是第一个源)。如果实现把它丢了(例如 block 轮转时误覆盖 blocks [0]),深层网络会失去对输入的直连路径— 所有层只能读到中间层输出,无法直接访问原始输入。这对 copy 任务、信息检索任务等是灾难性的。


                                                                                                                                                                                                                                                                                                                                                                                                                              0x06 Tab 5: 内存有界

                                                                                                                                                                                                                                                                                                                                                                                                                              6.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                              验证 Block 形式的核心优势:source 数 ≤ 块数 + 常数,远小于 Full 形式的 O (L)。

                                                                                                                                                                                                                                                                                                                                                                                                                              6.2 "source 数 ≤ 块数 + 常数" 三个数的含义

                                                                                                                                                                                                                                                                                                                                                                                                                              符号

                                                                                                                                                                                                                                                                                                                                                                                                                              含义

                                                                                                                                                                                                                                                                                                                                                                                                                              Block 形式

                                                                                                                                                                                                                                                                                                                                                                                                                              Full 形式

                                                                                                                                                                                                                                                                                                                                                                                                                              source 数

                                                                                                                                                                                                                                                                                                                                                                                                                              当前深度注意力可见的历史表示数量 (len(state.sources()))

                                                                                                                                                                                                                                                                                                                                                                                                                              阶梯增长,峰值 = 块数 + 2

                                                                                                                                                                                                                                                                                                                                                                                                                              每步 +1,最终 = n_units + 1

                                                                                                                                                                                                                                                                                                                                                                                                                              块数

                                                                                                                                                                                                                                                                                                                                                                                                                              已完成的块归档数 (len(state.blocks) - 1, 减去 embedding)

                                                                                                                                                                                                                                                                                                                                                                                                                              n_units // block_units

                                                                                                                                                                                                                                                                                                                                                                                                                              n_units (每 unit 一个块)

                                                                                                                                                                                                                                                                                                                                                                                                                              常数

                                                                                                                                                                                                                                                                                                                                                                                                                              固定开销:1 个 embedding + 1 个当前 partial

                                                                                                                                                                                                                                                                                                                                                                                                                              2

                                                                                                                                                                                                                                                                                                                                                                                                                              1 (只有 embedding,无 partial)

                                                                                                                                                                                                                                                                                                                                                                                                                              具体数值示例(默认配置 n_units=40, block_units=8):

                                                                                                                                                                                                                                                                                                                                                                                                                              指标

                                                                                                                                                                                                                                                                                                                                                                                                                              Block 形式

                                                                                                                                                                                                                                                                                                                                                                                                                              Full 形式

                                                                                                                                                                                                                                                                                                                                                                                                                              块数

                                                                                                                                                                                                                                                                                                                                                                                                                              40 // 8 = 5

                                                                                                                                                                                                                                                                                                                                                                                                                              40 (每 unit 一个块)

                                                                                                                                                                                                                                                                                                                                                                                                                              常数

                                                                                                                                                                                                                                                                                                                                                                                                                              2 (embedding + partial)

                                                                                                                                                                                                                                                                                                                                                                                                                              1 (只有 embedding)

                                                                                                                                                                                                                                                                                                                                                                                                                              source 数上界

                                                                                                                                                                                                                                                                                                                                                                                                                              5 + 2 = 7

                                                                                                                                                                                                                                                                                                                                                                                                                              40 + 1 = 41

                                                                                                                                                                                                                                                                                                                                                                                                                              实际峰值 source 数

                                                                                                                                                                                                                                                                                                                                                                                                                              7

                                                                                                                                                                                                                                                                                                                                                                                                                              41

                                                                                                                                                                                                                                                                                                                                                                                                                              内存压缩比

                                                                                                                                                                                                                                                                                                                                                                                                                              41/7 ≈ 5.9x

                                                                                                                                                                                                                                                                                                                                                                                                                              1x

                                                                                                                                                                                                                                                                                                                                                                                                                              6.3 "峰值 = 块数 + 2" 的推导

                                                                                                                                                                                                                                                                                                                                                                                                                              "2" 就是 1 个 embedding + 1 个当前 partial。这是 AttnRes Block 形式的算法设计规定的,不是任意常数。

                                                                                                                                                                                                                                                                                                                                                                                                                              具体推导:

                                                                                                                                                                                                                                                                                                                                                                                                                                `state.sources()` 的构成 = blocks 列表 + [partial] (如果 partial 存在)

                                                                                                                                                                                                                                                                                                                                                                                                                                其中 blocks 列表的内容是:

                                                                                                                                                                                                                                                                                                                                                                                                                                  blocks = [embedding, 已归档的块1, 已归档的块2, ..., 已归档的块N]
                                                                                                                                                                                                                                                                                                                                                                                                                                            ↑永远在          ↑每满 block_units 个 unit 归档一次

                                                                                                                                                                                                                                                                                                                                                                                                                                  所以峰值 source 数:

                                                                                                                                                                                                                                                                                                                                                                                                                                    峰值 = len(blocks) + 1(partial)
                                                                                                                                                                                                                                                                                                                                                                                                                                         = (1 + 已归档块数) + 1
                                                                                                                                                                                                                                                                                                                                                                                                                                         = 已归档块数 + 2
                                                                                                                                                                                                                                                                                                                                                                                                                                             ↑      ↑
                                                                                                                                                                                                                                                                                                                                                                                                                                         embedding(1) + partial(1)
                                                                                                                                                                                                                                                                                                                                                                                                                                         最多 = n_units // block_units

                                                                                                                                                                                                                                                                                                                                                                                                                                    为什么这两个必须存在:

                                                                                                                                                                                                                                                                                                                                                                                                                                    +1

                                                                                                                                                                                                                                                                                                                                                                                                                                    为什么必须有

                                                                                                                                                                                                                                                                                                                                                                                                                                    算法依据

                                                                                                                                                                                                                                                                                                                                                                                                                                    embedding

                                                                                                                                                                                                                                                                                                                                                                                                                                    论文规定 k_0 = v_0 = h_1,任何深度的层都必须能读到原始输入

                                                                                                                                                                                                                                                                                                                                                                                                                                    Eq. 9 的 source 列表定义

                                                                                                                                                                                                                                                                                                                                                                                                                                    partial

                                                                                                                                                                                                                                                                                                                                                                                                                                    当前块内正在累计的运行和,当前 unit 做深度注意力时必须能看到它

                                                                                                                                                                                                                                                                                                                                                                                                                                    Eq. 10 的 Block 形式定义

                                                                                                                                                                                                                                                                                                                                                                                                                                    partial 必须可见是因为:当前 unit 的深度注意力需要 attend over 可读源 — 已归档的块表示 + 当前块还没归档的部分。如果 partial 不可见,当前 unit 就看不到同块内前面 unit 的输出,信息就断了。

                                                                                                                                                                                                                                                                                                                                                                                                                                    这就是 Block 形式内存 O (Nd) 的核心:用 N 个块表示 + 1 个 partial + 1 个 embedding = N+2 个 source,替代 Full 形式的 L+1 个 source。

                                                                                                                                                                                                                                                                                                                                                                                                                                    6.4 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                    参数

                                                                                                                                                                                                                                                                                                                                                                                                                                    范围

                                                                                                                                                                                                                                                                                                                                                                                                                                    默认

                                                                                                                                                                                                                                                                                                                                                                                                                                    调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                    n_units

                                                                                                                                                                                                                                                                                                                                                                                                                                    10‑100

                                                                                                                                                                                                                                                                                                                                                                                                                                    40

                                                                                                                                                                                                                                                                                                                                                                                                                                    子层数量。增大 → Full 形式线性增长更明显,Block 优势更大

                                                                                                                                                                                                                                                                                                                                                                                                                                    block_units

                                                                                                                                                                                                                                                                                                                                                                                                                                    2‑20

                                                                                                                                                                                                                                                                                                                                                                                                                                    8

                                                                                                                                                                                                                                                                                                                                                                                                                                    块大小。增大 → 块数更少,内存更低

                                                                                                                                                                                                                                                                                                                                                                                                                                    dim

                                                                                                                                                                                                                                                                                                                                                                                                                                    4‑32

                                                                                                                                                                                                                                                                                                                                                                                                                                    8

                                                                                                                                                                                                                                                                                                                                                                                                                                    隐藏维度

                                                                                                                                                                                                                                                                                                                                                                                                                                    seed

                                                                                                                                                                                                                                                                                                                                                                                                                                    0‑10

                                                                                                                                                                                                                                                                                                                                                                                                                                    1

                                                                                                                                                                                                                                                                                                                                                                                                                                    随机种子

                                                                                                                                                                                                                                                                                                                                                                                                                                    6.5 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                    tab-5
                                                                                                                                                                                                                                                                                                                                                                                                                                    tab-5

                                                                                                                                                                                                                                                                                                                                                                                                                                    单图:

                                                                                                                                                                                                                                                                                                                                                                                                                                    • 粉色折线: 实际 source 数随 unit 演进(阶梯形)

                                                                                                                                                                                                                                                                                                                                                                                                                                    • 红色虚线: 理论上界 = n_units //block_units + 2

                                                                                                                                                                                                                                                                                                                                                                                                                                    • 灰色点线: Full 形式需要的 source 数 = n_units

                                                                                                                                                                                                                                                                                                                                                                                                                                    • 灰色阴影区: Block 节省的内存空间

                                                                                                                                                                                                                                                                                                                                                                                                                                    6.6 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                    Block 形式的全部动机是内存 O (Nd) 而非 O (Ld)。在 2.8T 配置中(L=93, N=8),内存压缩比约 93/9 ≈ 10x。如果实现退化(比如 partial 没有及时归档,或块内每个 unit 都被保留),峰值会悄悄涨到 O (L) 而在此暴露。


                                                                                                                                                                                                                                                                                                                                                                                                                                    0x07 Tab 6: 权重分布

                                                                                                                                                                                                                                                                                                                                                                                                                                    7.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                    验证深度注意力权重 alpha 在每个位置构成概率分布(沿 source 维求和 == 1,且全部 ≥ 0)。

                                                                                                                                                                                                                                                                                                                                                                                                                                    7.2 alpha 的概念

                                                                                                                                                                                                                                                                                                                                                                                                                                    alpha 是 AttnRes 中深度维 softmax 注意力的权重,即第 l 层在混合历史表示时分配给第 i 个 source 的权重:

                                                                                                                                                                                                                                                                                                                                                                                                                                      alpha_{i->l} = exp(q_l^T RMSNorm(k_i)) / Σ_j exp(q_l^T RMSNorm(k_j))
                                                                                                                                                                                                                                                                                                                                                                                                                                      h_l = Σ_i alpha_{i->l} v_i
                                                                                                                                                                                                                                                                                                                                                                                                                                      • alpha 的每个分量表示 "第 l 层有多关注第 i 个深度源"

                                                                                                                                                                                                                                                                                                                                                                                                                                      • softmax 归一化保证 Σ_i alpha_i = 1 且 alpha_i ≥ 0

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 这使得 h_l 是各 source 表示的凸组合 (convex combination),不会引入尺度偏移

                                                                                                                                                                                                                                                                                                                                                                                                                                      7.3 为什么在这里展示

                                                                                                                                                                                                                                                                                                                                                                                                                                      alpha 是理解 AttnRes 行为的核心窗口— 它回答 "每层到底读了哪些深度"。通过可视化 alpha 分布,可以验证:

                                                                                                                                                                                                                                                                                                                                                                                                                                      1. 概率分布性质: alpha 求和 == 1 (数值正确性)

                                                                                                                                                                                                                                                                                                                                                                                                                                      2. 选择性读取: 不同 unit 的 alpha 分布不同(伪查询 w_l 学到了不同策略)

                                                                                                                                                                                                                                                                                                                                                                                                                                      3. 训练前后变化: 训练前 alpha 均匀(等权),训练后 alpha 分化(选择性)

                                                                                                                                                                                                                                                                                                                                                                                                                                      7.4 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                      参数

                                                                                                                                                                                                                                                                                                                                                                                                                                      范围

                                                                                                                                                                                                                                                                                                                                                                                                                                      默认

                                                                                                                                                                                                                                                                                                                                                                                                                                      调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                      dim

                                                                                                                                                                                                                                                                                                                                                                                                                                      4‑32

                                                                                                                                                                                                                                                                                                                                                                                                                                      8

                                                                                                                                                                                                                                                                                                                                                                                                                                      隐藏维度

                                                                                                                                                                                                                                                                                                                                                                                                                                      n_units

                                                                                                                                                                                                                                                                                                                                                                                                                                      2‑20

                                                                                                                                                                                                                                                                                                                                                                                                                                      9

                                                                                                                                                                                                                                                                                                                                                                                                                                      子层数量

                                                                                                                                                                                                                                                                                                                                                                                                                                      block_units

                                                                                                                                                                                                                                                                                                                                                                                                                                      1‑10

                                                                                                                                                                                                                                                                                                                                                                                                                                      3

                                                                                                                                                                                                                                                                                                                                                                                                                                      块大小

                                                                                                                                                                                                                                                                                                                                                                                                                                      seed

                                                                                                                                                                                                                                                                                                                                                                                                                                      0‑10

                                                                                                                                                                                                                                                                                                                                                                                                                                      0

                                                                                                                                                                                                                                                                                                                                                                                                                                      随机种子

                                                                                                                                                                                                                                                                                                                                                                                                                                      7.5 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-6
                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-6

                                                                                                                                                                                                                                                                                                                                                                                                                                      2×1 布局:

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 上图:逐层 alpha 权重分布

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 不同 unit 的 alpha 分布不同 → 伪查询 w_l 学到了不同的 "读取策略"

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 多条折线,每条 = 一个 unit 的 alpha 分布

                                                                                                                                                                                                                                                                                                                                                                                                                                        • X 轴 = source 编号,Y 轴 = alpha 权重

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 你该看什么:

                                                                                                                                                                                                                                                                                                                                                                                                                                      • alpha 全部 ≥ 0 且求和 ≈ 1 → 构成有效概率分布

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 下图:求和检查

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 青色柱状图,每根柱 = 1.0 (求和 == 1 通过)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 如果出现 0.0 柱 → 严重 bug: alpha 不构成概率分布

                                                                                                                                                                                                                                                                                                                                                                                                                                      7.6 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                      深度混合 h_l = Σ alpha_i v_i 的系数必须是概率分布,否则加权和会引入不可控的尺度偏移。softmax 归一化天然保证这一点,但如果实现有数值精度问题(如 fp16 下 softmax 溢出),求和可能偏离 1。


                                                                                                                                                                                                                                                                                                                                                                                                                                      0x08 Tab 7: RMSNorm 防垄断

                                                                                                                                                                                                                                                                                                                                                                                                                                      8.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                      验证打分核里的 RMSNorm 确实防止 "大幅值层垄断注意力权重"。

                                                                                                                                                                                                                                                                                                                                                                                                                                      8.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                      参数

                                                                                                                                                                                                                                                                                                                                                                                                                                      范围

                                                                                                                                                                                                                                                                                                                                                                                                                                      默认

                                                                                                                                                                                                                                                                                                                                                                                                                                      调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                      dim

                                                                                                                                                                                                                                                                                                                                                                                                                                      4‑32

                                                                                                                                                                                                                                                                                                                                                                                                                                      8

                                                                                                                                                                                                                                                                                                                                                                                                                                      隐藏维度

                                                                                                                                                                                                                                                                                                                                                                                                                                      n_units

                                                                                                                                                                                                                                                                                                                                                                                                                                      2‑12

                                                                                                                                                                                                                                                                                                                                                                                                                                      6

                                                                                                                                                                                                                                                                                                                                                                                                                                      子层数量 (v5 默认从 4 改为 6,增加 source 数)

                                                                                                                                                                                                                                                                                                                                                                                                                                      seed

                                                                                                                                                                                                                                                                                                                                                                                                                                      0‑10

                                                                                                                                                                                                                                                                                                                                                                                                                                      0

                                                                                                                                                                                                                                                                                                                                                                                                                                      随机种子

                                                                                                                                                                                                                                                                                                                                                                                                                                      8.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-7
                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-7

                                                                                                                                                                                                                                                                                                                                                                                                                                      1×2 布局:

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 左图:baseline vs ×1000 的 alpha 对比

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 蓝色圆点线 = baseline (正常 alpha)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 橙色方块虚线 = blocks [1] 放大 1000 倍后的 alpha

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 两条线几乎完全重合 → RMSNorm 把幅值归一化后,放大不影响打分

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 右图:逐 source 绝对差异 (log scale)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 棕色柱状图,每根柱 = baseline [i] − scaled [i] 的绝对值

                                                                                                                                                                                                                                                                                                                                                                                                                                        • Y 轴为 log scale, 让 e‑08 级别的差异可见

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 每根柱上方标注科学计数法数值(如 8.9e‑08)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 所有柱在 1e‑09 到 1e‑07 之间,远小于通过标准 1e‑4 → RMSNorm 成功防止幅值垄断

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 0 值的柱在 log scale 下显示为 1e‑12 (占位),标注为 0.0e+00

                                                                                                                                                                                                                                                                                                                                                                                                                                      右图读图方法:

                                                                                                                                                                                                                                                                                                                                                                                                                                      1. 看 Y 轴刻度:如果所有柱在 −8 到 −10 之间(即 1e‑08 到 1e‑10),说明差异极小

                                                                                                                                                                                                                                                                                                                                                                                                                                      2. 看柱上方标注:具体数值如 8.9e‑08 远小于通过标准 1e‑4

                                                                                                                                                                                                                                                                                                                                                                                                                                      3. 如果 RMSNorm 失效,差异会涨到 0.1‑1.0 量级,柱会跳到 Y 轴顶部

                                                                                                                                                                                                                                                                                                                                                                                                                                      8.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                      深度注意的最实际风险是 "某层输出幅值巨大 → 它的点积分垄断 softmax 权重 → 其他深度被忽略"。RMSNorm 在打分前把每个 source 重缩放到单位 RMS,从根源消除幅值效应。

                                                                                                                                                                                                                                                                                                                                                                                                                                      对比: 如果打分核漏了 RMSNorm(直接用 q^T @ k 而非 q^T @ RMSNorm(k)),把 blocks [1] 放大 1000 倍后,它的 alpha 会从~0 暴涨到~1.0,其他 source 的 alpha 趋近 0— 这就是 "垄断"。


                                                                                                                                                                                                                                                                                                                                                                                                                                      0x9 Tab 8: 梯度流

                                                                                                                                                                                                                                                                                                                                                                                                                                      9.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                      验证梯度能流到每一层(每个深度源都被注意 / 读到),不存在被遗忘的深度。

                                                                                                                                                                                                                                                                                                                                                                                                                                      9.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                      参数

                                                                                                                                                                                                                                                                                                                                                                                                                                      范围

                                                                                                                                                                                                                                                                                                                                                                                                                                      默认

                                                                                                                                                                                                                                                                                                                                                                                                                                      调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                      dim

                                                                                                                                                                                                                                                                                                                                                                                                                                      4‑32

                                                                                                                                                                                                                                                                                                                                                                                                                                      8

                                                                                                                                                                                                                                                                                                                                                                                                                                      隐藏维度

                                                                                                                                                                                                                                                                                                                                                                                                                                      n_units

                                                                                                                                                                                                                                                                                                                                                                                                                                      2‑20

                                                                                                                                                                                                                                                                                                                                                                                                                                      9

                                                                                                                                                                                                                                                                                                                                                                                                                                      子层数量

                                                                                                                                                                                                                                                                                                                                                                                                                                      block_units

                                                                                                                                                                                                                                                                                                                                                                                                                                      1‑10

                                                                                                                                                                                                                                                                                                                                                                                                                                      3

                                                                                                                                                                                                                                                                                                                                                                                                                                      块大小

                                                                                                                                                                                                                                                                                                                                                                                                                                      seed

                                                                                                                                                                                                                                                                                                                                                                                                                                      0‑10

                                                                                                                                                                                                                                                                                                                                                                                                                                      0

                                                                                                                                                                                                                                                                                                                                                                                                                                      随机种子

                                                                                                                                                                                                                                                                                                                                                                                                                                      9.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-8
                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-8

                                                                                                                                                                                                                                                                                                                                                                                                                                      1×2 布局:

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 左图:逐层参数梯度 (L1 范数)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 紫色柱状图,每根柱 = 该层 weight.grad 的 L1 范数

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 所有柱 > 0 → 每层都收到了梯度,没有被 "遗忘"

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 右图:embedding 梯度

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 橙色单柱 = embedding.grad 的 L1 范数

                                                                                                                                                                                                                                                                                                                                                                                                                                        • > 0 → embedding 也收到了梯度

                                                                                                                                                                                                                                                                                                                                                                                                                                      9.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                      深度混合如果不均匀(某些源被 softmax 权重压成 0 或实现切断了某条路径),对应层的参数梯度会消失 — 那些深度就 "白学了"。AttnRes 的 softmax 注意力天然保证所有 source 的 alpha > 0 (softmax 不输出精确 0),因此梯度总能流到每一层。

                                                                                                                                                                                                                                                                                                                                                                                                                                      对比标准残差: 标准残差也有梯度流(残差直连),但 AttnRes 的优势在于信息流是选择性的— 每层根据内容决定读哪些深度,而非无差别累加。


                                                                                                                                                                                                                                                                                                                                                                                                                                      0x10 Tab 9: 2.8T 配置

                                                                                                                                                                                                                                                                                                                                                                                                                                      10.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                      验证论文 2.8T 配置(93 层 / 8 块 / 每块 12 层)的划分数字与代码配置自洽。

                                                                                                                                                                                                                                                                                                                                                                                                                                      10.2 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-9
                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-9

                                                                                                                                                                                                                                                                                                                                                                                                                                      1×2 布局:

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 左图:每块层数

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 粉色柱状图,8 根柱

                                                                                                                                                                                                                                                                                                                                                                                                                                        • Block 1‑7 各 12 层,Block 8 只有 9 层 (93 = 7×12 + 9)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 每根柱上方标注层数

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 右图:深度注意力可见 source 数

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 水平柱状图,9 个 source

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 蓝色 = embedding (1 个)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 粉色 = block_1 到 block_7 (7 个完成块)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 橙色 = block_8 (partial) (1 个未满块)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 总计 9 个 source = 论文描述

                                                                                                                                                                                                                                                                                                                                                                                                                                      10.3 关键数值

                                                                                                                                                                                                                                                                                                                                                                                                                                      指标

                                                                                                                                                                                                                                                                                                                                                                                                                                      值

                                                                                                                                                                                                                                                                                                                                                                                                                                      来源

                                                                                                                                                                                                                                                                                                                                                                                                                                      n_layers

                                                                                                                                                                                                                                                                                                                                                                                                                                      93

                                                                                                                                                                                                                                                                                                                                                                                                                                      Kimi3Config

                                                                                                                                                                                                                                                                                                                                                                                                                                      block_size

                                                                                                                                                                                                                                                                                                                                                                                                                                      12

                                                                                                                                                                                                                                                                                                                                                                                                                                      AttnResConfig

                                                                                                                                                                                                                                                                                                                                                                                                                                      n_blocks

                                                                                                                                                                                                                                                                                                                                                                                                                                      ceil(93/12) = 8

                                                                                                                                                                                                                                                                                                                                                                                                                                      代码计算

                                                                                                                                                                                                                                                                                                                                                                                                                                      深度 source 总数

                                                                                                                                                                                                                                                                                                                                                                                                                                      8 + 1 = 9

                                                                                                                                                                                                                                                                                                                                                                                                                                      块数 + embedding

                                                                                                                                                                                                                                                                                                                                                                                                                                      n_units (子层粒度)

                                                                                                                                                                                                                                                                                                                                                                                                                                      93 × 2 = 186

                                                                                                                                                                                                                                                                                                                                                                                                                                      每层含 2 个子层

                                                                                                                                                                                                                                                                                                                                                                                                                                      block_units (子层粒度)

                                                                                                                                                                                                                                                                                                                                                                                                                                      12 × 2 = 24

                                                                                                                                                                                                                                                                                                                                                                                                                                      子层块大小

                                                                                                                                                                                                                                                                                                                                                                                                                                      10.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                      把测试与生产配置挂钩 — 论文里 "8 块、9 源、每块 12 层" 的描述必须能被代码里的划分数字精确复现。若配置字段改名或除法约定变化,该测试会立即报警,防止文档与实现漂移。

                                                                                                                                                                                                                                                                                                                                                                                                                                      10.5 代码复用策略

                                                                                                                                                                                                                                                                                                                                                                                                                                      组件

                                                                                                                                                                                                                                                                                                                                                                                                                                      复用方式

                                                                                                                                                                                                                                                                                                                                                                                                                                      说明

                                                                                                                                                                                                                                                                                                                                                                                                                                      demo_attn_res.py

                                                                                                                                                                                                                                                                                                                                                                                                                                      提取 fig_demo_attn_res() → Gradio 直接调用

                                                                                                                                                                                                                                                                                                                                                                                                                                      训练四联图,避免维护两份代码

                                                                                                                                                                                                                                                                                                                                                                                                                                      plot_attnres_comparison.py

                                                                                                                                                                                                                                                                                                                                                                                                                                      提取 fig_attnres_comparison() → Gradio 直接调用

                                                                                                                                                                                                                                                                                                                                                                                                                                      范式对比架构图

                                                                                                                                                                                                                                                                                                                                                                                                                                      test_attn_res.py

                                                                                                                                                                                                                                                                                                                                                                                                                                      复用 build_test() + run_module() + naive oracle

                                                                                                                                                                                                                                                                                                                                                                                                                                      每个 Tab 是对应测试函数的可视化版本

                                                                                                                                                                                                                                                                                                                                                                                                                                      attn_res.py

                                                                                                                                                                                                                                                                                                                                                                                                                                      直接 import AttentionResiduals

                                                                                                                                                                                                                                                                                                                                                                                                                                      真实源码算子,非重实现

                                                                                                                                                                                                                                                                                                                                                                                                                                      norm.py

                                                                                                                                                                                                                                                                                                                                                                                                                                      直接 import rms_norm

                                                                                                                                                                                                                                                                                                                                                                                                                                      RMSNorm 核心计算

                                                                                                                                                                                                                                                                                                                                                                                                                                       

                                                                                                                                                                                                                                                                                                                                                                                                                                      保持向后兼容: 原有 main() 函数保留,__main__ 仍可独立运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                      ”

                                                                                                                                                                                                                                                                                                                                                                                                                                      10.5 验证策略总览

                                                                                                                                                                                                                                                                                                                                                                                                                                      每个 Tab 都是对应测试函数的可视化版本:

                                                                                                                                                                                                                                                                                                                                                                                                                                      Tab

                                                                                                                                                                                                                                                                                                                                                                                                                                      测试函数

                                                                                                                                                                                                                                                                                                                                                                                                                                      验证点

                                                                                                                                                                                                                                                                                                                                                                                                                                      通过标准

                                                                                                                                                                                                                                                                                                                                                                                                                                      3

                                                                                                                                                                                                                                                                                                                                                                                                                                      Block vs Full

                                                                                                                                                                                                                                                                                                                                                                                                                                      test_block_size_one_recovers_the_full_form

                                                                                                                                                                                                                                                                                                                                                                                                                                      block_units=1 退化

                                                                                                                                                                                                                                                                                                                                                                                                                                      逐块误差 < 1e‑6

                                                                                                                                                                                                                                                                                                                                                                                                                                      4

                                                                                                                                                                                                                                                                                                                                                                                                                                      Embedding 源

                                                                                                                                                                                                                                                                                                                                                                                                                                      test_embedding_is_always_a_source

                                                                                                                                                                                                                                                                                                                                                                                                                                      embedding 永远在 sources ()[0]

                                                                                                                                                                                                                                                                                                                                                                                                                                      torch.equal 每步

                                                                                                                                                                                                                                                                                                                                                                                                                                      5

                                                                                                                                                                                                                                                                                                                                                                                                                                      内存有界

                                                                                                                                                                                                                                                                                                                                                                                                                                      test_memory_is_bounded_by_block_count

                                                                                                                                                                                                                                                                                                                                                                                                                                      source 数 ≤ 块数 + 2

                                                                                                                                                                                                                                                                                                                                                                                                                                      peak ≤ n_units//block_units+2

                                                                                                                                                                                                                                                                                                                                                                                                                                      6

                                                                                                                                                                                                                                                                                                                                                                                                                                      权重分布

                                                                                                                                                                                                                                                                                                                                                                                                                                      test_attention_weights_form_a_distribution

                                                                                                                                                                                                                                                                                                                                                                                                                                      alpha 求和 == 1

                                                                                                                                                                                                                                                                                                                                                                                                                                      allclose(atol=1e‑6)

                                                                                                                                                                                                                                                                                                                                                                                                                                      7

                                                                                                                                                                                                                                                                                                                                                                                                                                      RMSNorm 防垄断

                                                                                                                                                                                                                                                                                                                                                                                                                                      test_key_rmsnorm_prevents_magnitude_domination

                                                                                                                                                                                                                                                                                                                                                                                                                                      ×1000 不影响权重

                                                                                                                                                                                                                                                                                                                                                                                                                                      allclose(atol=1e‑4)

                                                                                                                                                                                                                                                                                                                                                                                                                                      8

                                                                                                                                                                                                                                                                                                                                                                                                                                      梯度流

                                                                                                                                                                                                                                                                                                                                                                                                                                      test_gradients_reach_every_depth

                                                                                                                                                                                                                                                                                                                                                                                                                                      每层梯度非零

                                                                                                                                                                                                                                                                                                                                                                                                                                      grad.abs().sum() > 0

                                                                                                                                                                                                                                                                                                                                                                                                                                      9

                                                                                                                                                                                                                                                                                                                                                                                                                                      2.8T 配置

                                                                                                                                                                                                                                                                                                                                                                                                                                      test_paper_partition_for_the_2p8t_config

                                                                                                                                                                                                                                                                                                                                                                                                                                      8 块 /9 源 /24 单位

                                                                                                                                                                                                                                                                                                                                                                                                                                      assert n_blocks==8, module.block_units==24


                                                                                                                                                                                                                                                                                                                                                                                                                                      TransFormer-封面
                                                                                                                                                                                                                                                                                                                                                                                                                                      TransFormer-封面

                                                                                                                                                                                                                                                                                                                                                                                                                                      0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                      阅读原文

                                                                                                                                                                                                                                                                                                                                                                                                                                      跳转微信打开

                                                                                                                                                                                                                                                                                                                                                                                                                                      •  

                                                                                                                                                                                                                                                                                                                                                                                                                                      【轻量化复刻大模型 / KIMI K3】Attention Residuals 完整梳理(2)

                                                                                                                                                                                                                                                                                                                                                                                                                                      原创 罗西的思考 2026-11-11 20:50 北京

                                                                                                                                                                                                                                                                                                                                                                                                                                      # 【轻量化复刻大模型 / KIMI K3】Attention Residuals 完整梳理(2)

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x00 概要

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x01 子知识点拆解

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x02 子知识点深度分析

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.0 共享抽象与设计动机

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.1 打分核(scoring kernel)与伪查询

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.2 Full AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.3 Block AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.4 状态机(AttnResState —— 深度历史如何在层间流动)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.5 online-softmax 两阶段算法(论文 Algorithm 1)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.6 生产级 fused kernel 原理(SGLang;TMA + online softmax + 通信融合)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.7 对比对象 —— mHC(Manifold-Constrained Hyper-Connections)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.8 基础设施:跨阶段缓存 + 高效 Prefill(论文 §4)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.9 学到的深度注意模式(论文 §5.4.2,Fig. 8)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.10 统一视角:残差连接作为结构化矩阵(论文 §6.2,Table 5)

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.11 最优架构分析(论文 §5.4.1,Fig. 7)

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0xFF 参考


                                                                                                                                                                                                                                                                                                                                                                                                                                      0x00 概要

                                                                                                                                                                                                                                                                                                                                                                                                                                      本文为 AttnRes 的第二部分。

                                                                                                                                                                                                                                                                                                                                                                                                                                      注:

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                                                                                                                                                                                                                                                                                                                                      • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。


                                                                                                                                                                                                                                                                                                                                                                                                                                      0x01 子知识点拆解

                                                                                                                                                                                                                                                                                                                                                                                                                                      AttnRes 拆解为以下子知识点(树状结构,标注依赖与项目代码位置):

                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnRes
                                                                                                                                                                                                                                                                                                                                                                                                                                        ├── S1  打分核(scoring kernel):φ(q,k) = exp(q^T·RMSNorm(k))
                                                                                                                                                                                                                                                                                                                                                                                                                                        │   ├── S1.1 伪查询向量 pseudo-query w_l ∈ R^d(每层一个可学习参数,零初始化)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │   ├── S1.2  key = value = 历史层输出(含 embedding 源 h_1)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │   └── S1.3  RMSNorm 在 key 上(防大范数垄断)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │       代码:attn_res.py 的 mix() 函数
                                                                                                                                                                                                                                                                                                                                                                                                                                        ├── S2  Full AttnRes(O(L^2 d) 算术 + O(Ld) 内存,保留所有历史层)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │       代码:attn_res.py 的 FullAttentionResiduals(block_units=1 等价)
                                                                                                                                                                                                                                                                                                                                                                                                                                        ├── S3  Block AttnRes(O(Nd) 内存;分块 + partial sum 运行态)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │   ├── S3.1 块表示 b_n = Σ_{j∈B_n} f_j(h_j)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │   ├── S3.2 运行 partial sum(当前块内累计)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │   ├── S3.3 attention 范围 = 已完成的块表示 + 当前 partial(Eq. 6)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │   └── S3.4 embedding 永远是源 b_0 = h_1
                                                                                                                                                                                                                                                                                                                                                                                                                                        │       代码:attn_res.py 的 AttentionResiduals 类(init_state/mix/add_output/finalize)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │       集成:model.py 的 Kimi3Model 集成
                                                                                                                                                                                                                                                                                                                                                                                                                                        ├── S4  状态机(服务端/推理维度:sources 的演进)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │       代码:attn_res.py 的 AttnResState 数据类
                                                                                                                                                                                                                                                                                                                                                                                                                                        ├── S5  在线 softmax 两阶段算法(分块间并行 + 块内顺序)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │       参考代码:kimi-k3-pytorch-main 的 online_softmax.py / two_phase.py
                                                                                                                                                                                                                                                                                                                                                                                                                                        ├── S6  生产级 fused kernel(SGLang;TMA + online softmax + 通信融合)
                                                                                                                                                                                                                                                                                                                                                                                                                                        │       参考代码:sglang-main 的 attn_res.py + fused_tma.cuh
                                                                                                                                                                                                                                                                                                                                                                                                                                        └── S7  对比对象:mHC(Manifold-Constrained Hyper-Connections)

                                                                                                                                                                                                                                                                                                                                                                                                                                        依赖关系:S1 → S2 / S3(所有 mix 用打分核);S3 → S4(block 演进状态);S2/S3 → S5(两阶段加速);S5 → S6(fused kernel)。S7 为横向对比,不依赖其它子知识点。

                                                                                                                                                                                                                                                                                                                                                                                                                                        各子知识点的实现/变体切换入口:

                                                                                                                                                                                                                                                                                                                                                                                                                                        变体

                                                                                                                                                                                                                                                                                                                                                                                                                                        切换参数

                                                                                                                                                                                                                                                                                                                                                                                                                                        位置

                                                                                                                                                                                                                                                                                                                                                                                                                                        full vs block

                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnResConfig.full

                                                                                                                                                                                                                                                                                                                                                                                                                                        (默认 False→block)

                                                                                                                                                                                                                                                                                                                                                                                                                                        config.py 的 AttnResConfig

                                                                                                                                                                                                                                                                                                                                                                                                                                        block size

                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnResConfig.block_size

                                                                                                                                                                                                                                                                                                                                                                                                                                        (默认 4)

                                                                                                                                                                                                                                                                                                                                                                                                                                        同上

                                                                                                                                                                                                                                                                                                                                                                                                                                        granularity sublayer vs layer

                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnResConfig.granularity

                                                                                                                                                                                                                                                                                                                                                                                                                                        同上

                                                                                                                                                                                                                                                                                                                                                                                                                                        eager vs two_phase

                                                                                                                                                                                                                                                                                                                                                                                                                                        kimi-k3-pytorch 的 backend 字段

                                                                                                                                                                                                                                                                                                                                                                                                                                        kimi-k3-pytorch-main 的 config.py

                                                                                                                                                                                                                                                                                                                                                                                                                                         

                                                                                                                                                                                                                                                                                                                                                                                                                                        关于论文 48B 配置 vs K3 配置的澄清:

                                                                                                                                                                                                                                                                                                                                                                                                                                        • AttnRes 论文主实验(§5.2):基于 Kimi Linear 48B(27 Transformer blocks = 54 层),Block AttnRes 每块 6 层 → 9 个块 + embedding = 10 个深度源。

                                                                                                                                                                                                                                                                                                                                                                                                                                        • K3):K3 技术报告 §2.2 明确 "we partition its layers into 8 blocks with 12-layer size, giving a partial final block and 9 total blocks when counting the embedding layer"。K3 总层数为 93 层。

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 需注意分清:9 源对应 K3(12 层/块),论文主实验是 10 源(6 层/块)。本项目测试 test_paper_partition_for_the_2p8t_config 验证的正是 K3 的 93 层 → 8 块 → 9 源切分。

                                                                                                                                                                                                                                                                                                                                                                                                                                        ”

                                                                                                                                                                                                                                                                                                                                                                                                                                        0x02 子知识点深度分析

                                                                                                                                                                                                                                                                                                                                                                                                                                        2.0 共享抽象与设计动机

                                                                                                                                                                                                                                                                                                                                                                                                                                        所有变体共享同一抽象:一个"源(source)"集合 + 一次"查询-键打分 + 归一化混合"。

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 源(sources):V = [v_0, v_1, ..., v_{n-1}],是历史层输出的集合(显式保留,不压缩成一个状态)。这是与标准残差的分水岭:标准残差把历史"压成"h_{l-1},AttnRes 把历史"留作"列表。

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 打分:每层一个 w_l,对所有源求 exp(w_l^T·RMSNorm(v_i)) 后 softmax,得到 α_i。

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 混合:h_l = Σ_i α_i v_i。

                                                                                                                                                                                                                                                                                                                                                                                                                                        • 设计动机:为什么把历史"留作列表"而非"压成状态"?因为"选择性读取"必须保得住"每一项"才能选——压成一个状态就丢了选择性。代价是保留全部历史的内存,这正是 Block 形式要解决的问题。

                                                                                                                                                                                                                                                                                                                                                                                                                                        统一公式(Full / Block 都是它的实例):

                                                                                                                                                                                                                                                                                                                                                                                                                                          V   = [v_0, ..., v_{n-1}]        # 源列表
                                                                                                                                                                                                                                                                                                                                                                                                                                          K   = RMSNorm(V)                 # key = value,RMSNorm 保证可比
                                                                                                                                                                                                                                                                                                                                                                                                                                          w_l = learned query of layer l
                                                                                                                                                                                                                                                                                                                                                                                                                                          α   = softmax(V·w_l)             # 每源权重
                                                                                                                                                                                                                                                                                                                                                                                                                                          h_l = Σ_i α_i · v_i              # 混合结果

                                                                                                                                                                                                                                                                                                                                                                                                                                          Block 形式唯一的差异是:V 被压缩为 [b_0, ..., b_{N-1}, partial](块表示 + 运行 partial),即 n = N+1 个源而非 L 个。

                                                                                                                                                                                                                                                                                                                                                                                                                                          2.1 打分核(scoring kernel)与伪查询

                                                                                                                                                                                                                                                                                                                                                                                                                                          2.1.1 原理(三视角)

                                                                                                                                                                                                                                                                                                                                                                                                                                          • 直觉:每个源是一个"词汇",每层是"搜索的 query"。伪查询向量 w_l 表示"这一层现在想要什么样的表示",RMSNorm 把每个 key 缩放到同一长度,保证比的是"方向"而不是"长度"。

                                                                                                                                                                                                                                                                                                                                                                                                                                          • 准专业:α_i = exp(w_l^T·RMSNorm(v_i)) / Σ_j exp(w_l^T·RMSNorm(v_j))。w_l∈R^d 是层级参数,训练时学出「这一层该主要读哪些 early 层的输出」。

                                                                                                                                                                                                                                                                                                                                                                                                                                          • 专家:φ(q,k)=exp(q^T RMSNorm(k)) 是 inner-product 点积核,softmax 保证 α 非负且和=1,即每一层是一个「往历史层上的概率分布」。RMSNorm(k) 的作用论文有消融验证:去掉它性能下降(Full 1.743 vs 1.737,Block 1.750 vs 1.746),因为它防止了「范数大的层输出靠量级垄断权重」——也就是防"权重只看 magnitude 不看 semantic dimension"。对 Block 更关键(块表示跨层累积,量级差异更大,论文 §2.3 明确说明)。

                                                                                                                                                                                                                                                                                                                                                                                                                                          2.1.2 对比基线

                                                                                                                                                                                                                                                                                                                                                                                                                                          维度

                                                                                                                                                                                                                                                                                                                                                                                                                                          标准做法(残差)

                                                                                                                                                                                                                                                                                                                                                                                                                                          打分核(伪查询)

                                                                                                                                                                                                                                                                                                                                                                                                                                          权重来源

                                                                                                                                                                                                                                                                                                                                                                                                                                          固定常数 1

                                                                                                                                                                                                                                                                                                                                                                                                                                          每层的 w_l 可学习向量

                                                                                                                                                                                                                                                                                                                                                                                                                                          是否 input-dependent

                                                                                                                                                                                                                                                                                                                                                                                                                                          否

                                                                                                                                                                                                                                                                                                                                                                                                                                          是(经 v_i 内容影响)

                                                                                                                                                                                                                                                                                                                                                                                                                                          额外参数

                                                                                                                                                                                                                                                                                                                                                                                                                                          0

                                                                                                                                                                                                                                                                                                                                                                                                                                          d

                                                                                                                                                                                                                                                                                                                                                                                                                                           per layer (|w_l|=d)

                                                                                                                                                                                                                                                                                                                                                                                                                                          归一化

                                                                                                                                                                                                                                                                                                                                                                                                                                          无

                                                                                                                                                                                                                                                                                                                                                                                                                                          softmax + RMSNorm(key)

                                                                                                                                                                                                                                                                                                                                                                                                                                          2.1.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                          • a) 最强反对:伪查询是每层一个静态向量,无法根据输入 token 动态切换。论文消融确实提出把 w_l 变成 input-dependent 投影(1.731,更低),但有 d×d 投影/层的参数代价和顺序访存代价。

                                                                                                                                                                                                                                                                                                                                                                                                                                          • b) 失败假设:假设每层最重要的历史是输入无关的(或近似静态)。若每 layer 需要 "task / sequence" 级别的动态读取,固定 w_l 就力不从心。

                                                                                                                                                                                                                                                                                                                                                                                                                                          • c) 胜出条件:当"深度方向的读取模式本身比较稳定"(例如固定关注 embedding / 邻居层)时静态伪查询更省参且稳定;失败条件:需要动态(per-token)改变读取。

                                                                                                                                                                                                                                                                                                                                                                                                                                          • d) 更稳做法:用一个小的 input projection 替换 w_l(hybrid),保留两者优点。

                                                                                                                                                                                                                                                                                                                                                                                                                                          • e) 受损方:无——参数极小(每层 d 个标量),唯独增加 PP/通信(块表示跨 stage)。

                                                                                                                                                                                                                                                                                                                                                                                                                                          2.1.4 计算复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                          • 增加:每层一次 w_l·RMSNorm(v_i) 是 d 点积 × n 源 = O(nd);总 L 层 O(nLd)。

                                                                                                                                                                                                                                                                                                                                                                                                                                          • n 个源:Full n=L(K3 以 sublayer 计 2L);Block n=N+1。

                                                                                                                                                                                                                                                                                                                                                                                                                                          • 内存开销:每层存 w_l∈R^d,各 key&value 来自前存输出,零新增。

                                                                                                                                                                                                                                                                                                                                                                                                                                          2.1.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                          • w_l 的初始值:论文 §5 明确"所有伪查询向量必须初始化为零"——这保证初始 w=0 → α=uniform(softmax(0)=均匀) → 初始状态 = 标准残差(等权平均)!论文原文:"This reduces AttnRes to an equal-weight average at the start of training and prevents training volatility, as we validated empirically." 本项目 queries 用 torch.zeros(...) 初始化正是此设计。

                                                                                                                                                                                                                                                                                                                                                                                                                                          • 若 w_l 初始为随机大值,会跳过均匀漂移直接学两极性,易造成层间读数剧烈变化。因此 zeros 是必要工程要点。

                                                                                                                                                                                                                                                                                                                                                                                                                                          2.1.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                          attn_res.py 中的 mix() 方法逐行对应。rms_norm 来自同目录 norm.py。权重两个可训练参数:self.queries(形状 (n_units+1, d),多一个 final 聚合),self.key_norm_weight(形状 (d,))。

                                                                                                                                                                                                                                                                                                                                                                                                                                                def mix(self, state: AttnResState, unit_idx: int) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                    """Eq. 9 -- the representation handed to unit ``unit_idx``.


                                                                                                                                                                                                                                                                                                                                                                                                                                                    【中文释义】深度维 softmax 注意的核心算子(对应论文 Eq. 9):把当前可读
                                                                                                                                                                                                                                                                                                                                                                                                                                                    源列表(``state.sources()``)叠成一个张量,其 key 统一过 RMSNorm,
                                                                                                                                                                                                                                                                                                                                                                                                                                                    用本 unit 的伪查询 ``self.queries[unit_idx]`` 打分得到 ``alpha``(softmax
                                                                                                                                                                                                                                                                                                                                                                                                                                                    归一化),最后加权求和解组成交给该 unit 的表示 ``h_l``。
                                                                                                                                                                                                                                                                                                                                                                                                                                                    当只有 embedding 一个源时直接返回(避免无谓的 einsum/softmax)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                    shape 说明:source 叠成 ``(n, b, t, d)``,scores 为 ``(n, b, t)``,
                                                                                                                                                                                                                                                                                                                                                                                                                                                    softmax 沿源维 ``n`` 归一化,输出回 ``(b, t, d)``。
                                                                                                                                                                                                                                                                                                                                                                                                                                                    """
                                                                                                                                                                                                                                                                                                                                                                                                                                                    sources = state.sources()
                                                                                                                                                                                                                                                                                                                                                                                                                                                    if len(sources) == 1:
                                                                                                                                                                                                                                                                                                                                                                                                                                                        return sources[0]
                                                                                                                                                                                                                                                                                                                                                                                                                                                    stacked = torch.stack(sources, dim=0)                     # (n, b, t, d)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    keys = rms_norm(stacked, self.key_norm_weight, self.eps)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    query = self.queries[unit_idx]                            # (d,)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    scores = torch.einsum("nbtd,d->nbt", keys, query)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    weights = torch.softmax(scores.float(), dim=0).to(stacked.dtype)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    return torch.einsum("nbt,nbtd->btd", weights, stacked)

                                                                                                                                                                                                                                                                                                                                                                                                                                            2.1.7 探讨代码

                                                                                                                                                                                                                                                                                                                                                                                                                                            测试已覆盖:test_attention_weights_form_a_distribution(验证 α 非负、和为 1)与 test_key_rmsnorm_prevents_magnitude_domination(把某个源放大 1000x 后权重不变)。结论:RMSNorm 确实让权重对源 magnitude 不敏感——验证了论文论点。

                                                                                                                                                                                                                                                                                                                                                                                                                                            2.1.8 验证 demo

                                                                                                                                                                                                                                                                                                                                                                                                                                            tests/math/test_attn_res.py 全部通过(可与 test_key_rmsnorm_prevents_magnitude_domination 配合在 notebook 上可视化)。完成度:已实现并运行通过。


                                                                                                                                                                                                                                                                                                                                                                                                                                            2.2 Full AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                            2.2.1 原理(三视角)

                                                                                                                                                                                                                                                                                                                                                                                                                                            • 直觉:无分块,全历史可读——"之前每一页都是独立卡片,随便读哪一张"。

                                                                                                                                                                                                                                                                                                                                                                                                                                            • 准专业:n_units = L(或 sub-layer),每个源都是单一层输出;h_l = softmax 混合所有早期层 + embedding(Eq. 4)。

                                                                                                                                                                                                                                                                                                                                                                                                                                            • 专家:M 稠密 rank-L;内容相关。O(L²d) 算术在 L<100 时可负担(论文:L<100 是 Full 形式可用的前提);瓶颈是 O(Ld) 内存(每层都要持久保存所有层的输出,PP 下还要跨 stage 传输)。

                                                                                                                                                                                                                                                                                                                                                                                                                                            2.2.2 对比基线

                                                                                                                                                                                                                                                                                                                                                                                                                                            Full vs 标准残差:所有源都可见+可选择性 vs 只可见前一状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                            2.2.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                            • a) 反对最强理由:O(Ld) 内存让 PP 无法承受,L 大时退化。

                                                                                                                                                                                                                                                                                                                                                                                                                                            • b) 失败假设:假设 L 足够小(L<100),所以 O(L²) 可负担。若 L 数百,算术也可爆。

                                                                                                                                                                                                                                                                                                                                                                                                                                            • c) 胜出条件:L ≤ ~40 单卡(教育/小模型);失败:PP/大数据。

                                                                                                                                                                                                                                                                                                                                                                                                                                            • d) 更稳做法:Block 形式(见下)。

                                                                                                                                                                                                                                                                                                                                                                                                                                            • e) 受损方:训练方(内存/通信);演进为 Block。

                                                                                                                                                                                                                                                                                                                                                                                                                                            2.2.4 复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                            • 算术:训练 O(L²d)(层间全对全 attention);推理在"两阶段调度"下可降到 O(L·(S+N)·d)(附录 C)。

                                                                                                                                                                                                                                                                                                                                                                                                                                            • 内存:存储所有源 O(Ld) vs 标准 O(d)。

                                                                                                                                                                                                                                                                                                                                                                                                                                            • 参数:新增 0(只有 w_l 固定,d/L)。

                                                                                                                                                                                                                                                                                                                                                                                                                                            2.2.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                            • n_units 必须 ≤ 层数× granularity。若设大,多出的 queries 永不使用。

                                                                                                                                                                                                                                                                                                                                                                                                                                            • 论文:伪查询必须零初始化。

                                                                                                                                                                                                                                                                                                                                                                                                                                            2.2.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                            FullAttentionResiduals(AttentionResiduals) 仅设 block_units=1、full=True,等价性由测试 test_block_size_one_recovers_the_full_form 断言(逐对 allclose atol=1e-6)。

                                                                                                                                                                                                                                                                                                                                                                                                                                            可以看到,在 Kimi3Model 的前向传播中,会用 self.attn_res.add_output(self._attn_res_state, h) 往self._attn_res_state中增加模型每层生成的中间状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                              class Kimi3Model(nn.Module):
                                                                                                                                                                                                                                                                                                                                                                                                                                                  """K3 剔除 lm_head 的完整主杆:embedding + 全部 block + 最后 norm。


                                                                                                                                                                                                                                                                                                                                                                                                                                                  额外管理一个可选的 AttentionResiduals 模块(跨层的深度方向注意力)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                  AttnRes 启用时,每个 block 被**调用两次**(block 内前半个单元 da 次),
                                                                                                                                                                                                                                                                                                                                                                                                                                                  AttnRes 在其间插入"层间混合"(brand-residual mix)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                  """


                                                                                                                                                                                                                                                                                                                                                                                                                                                  def __init__(self, config: Kimi3Config):
                                                                                                                                                                                                                                                                                                                                                                                                                                                      super().__init__()
                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.config = config
                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.tok_embed = nn.Embedding(config.model.vocab_size, config.model.dim)
                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 每层交替:偶数层 KDA(use_kda=True),奇数层 MLA(use_kda=False)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 这决定了 init_caches 返回的列表 K/ML 交替出现。
                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.blocks = nn.ModuleList([
                                                                                                                                                                                                                                                                                                                                                                                                                                                          Kimi3Block(config, i, use_kda=(i % 2 == 0))
                                                                                                                                                                                                                                                                                                                                                                                                                                                          for i in range(config.model.n_layers)
                                                                                                                                                                                                                                                                                                                                                                                                                                                      ])
                                                                                                                                                                                                                                                                                                                                                                                                                                                      if config.model.attn_res.enabled:
                                                                                                                                                                                                                                                                                                                                                                                                                                                          # 启用 AttentionResiduals:n_units = 2*n_layers(每 block 两个
                                                                                                                                                                                                                                                                                                                                                                                                                                                          # unit:attn+ffn),block_size 决定多少个 unit 共享一个残差状态。
                                                                                                                                                                                                                                                                                                                                                                                                                                                          n_units = config.model.n_layers * 2
                                                                                                                                                                                                                                                                                                                                                                                                                                                          block_units = config.model.attn_res.block_size
                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.attn_res = AttentionResiduals(
                                                                                                                                                                                                                                                                                                                                                                                                                                                              config.model.dim, n_units, block_units,
                                                                                                                                                                                                                                                                                                                                                                                                                                                              full=config.model.attn_res.full,
                                                                                                                                                                                                                                                                                                                                                                                                                                                          )
                                                                                                                                                                                                                                                                                                                                                                                                                                                          self._attn_res_state = None  # 前向过程中暂存的 AttnRes 状态缓存
                                                                                                                                                                                                                                                                                                                                                                                                                                                      else:
                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.attn_res = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.norm = RMSNorm(config.model.dim, config.model.norm_eps)


                                                                                                                                                                                                                                                                                                                                                                                                                                                  def forward(
                                                                                                                                                                                                                                                                                                                                                                                                                                                      self,
                                                                                                                                                                                                                                                                                                                                                                                                                                                      tokens: Tensor,
                                                                                                                                                                                                                                                                                                                                                                                                                                                      doc_ids: Optional[Tensor] = None,
                                                                                                                                                                                                                                                                                                                                                                                                                                                      caches: Optional[list] = None,
                                                                                                                                                                                                                                                                                                                                                                                                                                                  ) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                      """完整模型前向。


                                                                                                                                                                                                                                                                                                                                                                                                                                                      ``caches`` 应与 ``self.blocks`` 等长(每 block 一个 cache)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                      解码时与服务端相同:传一个 token,返回一层 logits,内部自动调用
                                                                                                                                                                                                                                                                                                                                                                                                                                                      cache 完成增量前向。训练时一次性给整段 tokens,cache 每层重新
                                                                                                                                                                                                                                                                                                                                                                                                                                                      复算或者用 cache 减少重复计算。
                                                                                                                                                                                                                                                                                                                                                                                                                                                      """
                                                                                                                                                                                                                                                                                                                                                                                                                                                      h = self.tok_embed(tokens)
                                                                                                                                                                                                                                                                                                                                                                                                                                                      reset_mask, attn_mask = doc_masks(
                                                                                                                                                                                                                                                                                                                                                                                                                                                          doc_ids, tokens.shape[1], tokens.device
                                                                                                                                                                                                                                                                                                                                                                                                                                                      )


                                                                                                                                                                                                                                                                                                                                                                                                                                                      if self.attn_res is not None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                          # ---- 带 AttnRes 的路 =========================================
                                                                                                                                                                                                                                                                                                                                                                                                                                                          self._attn_res_state = self.attn_res.init_state(h)
                                                                                                                                                                                                                                                                                                                                                                                                                                                          unit_idx = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                          for i, block in enumerate(self.blocks):
                                                                                                                                                                                                                                                                                                                                                                                                                                                              cache = caches[i] if caches is not None else None  # 每 block 一个 cache
                                                                                                                                                                                                                                                                                                                                                                                                                                                              # 每个 block 被调度两次,中间混入一次 AttnRes 深度混合:
                                                                                                                                                                                                                                                                                                                                                                                                                                                              #   mix -> attn -> add_output -> mix -> ffn -> add_output
                                                                                                                                                                                                                                                                                                                                                                                                                                                              h = self.attn_res.mix(self._attn_res_state, unit_idx)
                                                                                                                                                                                                                                                                                                                                                                                                                                                              h = block(h, cache=cache, reset_mask=reset_mask, attn_mask=attn_mask)
                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._attn_res_state = self.attn_res.add_output(self._attn_res_state, h)
                                                                                                                                                                                                                                                                                                                                                                                                                                                              unit_idx += 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                              h = self.attn_res.mix(self._attn_res_state, unit_idx)
                                                                                                                                                                                                                                                                                                                                                                                                                                                              h = block(h, cache=cache, reset_mask=reset_mask, attn_mask=attn_mask)
                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._attn_res_state = self.attn_res.add_output(self._attn_res_state, h)
                                                                                                                                                                                                                                                                                                                                                                                                                                                              unit_idx += 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                          h = self.attn_res.finalize(self._attn_res_state)
                                                                                                                                                                                                                                                                                                                                                                                                                                                      else:
                                                                                                                                                                                                                                                                                                                                                                                                                                                          # 不带 AttnRes:每个 block 只调用一次。cache 也是"每 block 一个"。
                                                                                                                                                                                                                                                                                                                                                                                                                                                          for i, block in enumerate(self.blocks):
                                                                                                                                                                                                                                                                                                                                                                                                                                                              cache = caches[i] if caches is not None else None
                                                                                                                                                                                                                                                                                                                                                                                                                                                              h = block(h, cache=cache, reset_mask=reset_mask, attn_mask=attn_mask)
                                                                                                                                                                                                                                                                                                                                                                                                                                                      return self.norm(h)   # 最后一层 RMSNorm,喂给 lm_head

                                                                                                                                                                                                                                                                                                                                                                                                                                              2.2.7-2.2.8 探讨/验证

                                                                                                                                                                                                                                                                                                                                                                                                                                              测试:test_block_form_matches_the_eq10_oracle(naive 独立转写比对);test_block_size_one_recovers_the_full_form;test_gradients_reach_every_depth;test_paper_partition_for_the_2p8t_config(93 层/12 → 8 块/9 源)。


                                                                                                                                                                                                                                                                                                                                                                                                                                              2.3 Block AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                              2.3.1 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                              • 直觉:把 L 层分成 N 个块,每个块"收官"时压缩成一个总表示 b_n。读历史时只读 N 个块 + 当前块的运行 partial。

                                                                                                                                                                                                                                                                                                                                                                                                                                              • 准专业(论文 Eq. 5-6):设块 n,层集合 B_n,块表示 b_n = Σ_{j∈B_n} f_j(h_j),当前块前 i-1 层部分和 b_n^{i-1}。则

                                                                                                                                                                                                                                                                                                                                                                                                                                                • V = [b_0, ..., b_{n-1}](第一层,还没有 partial)

                                                                                                                                                                                                                                                                                                                                                                                                                                                • V = [b_0, ..., b_{n-1}, b_n^{i-1}](i≥2 时再附加 partial)

                                                                                                                                                                                                                                                                                                                                                                                                                                                • embedding b_0 = h_1。

                                                                                                                                                                                                                                                                                                                                                                                                                                              • 专家:内存从 O(Ld) → O(Nd);1<N<L 时介于"等权相加"(N=1)和 Full(N=L)之间;论文的实验:N≈8 复原几乎全部(论文图 4 中 Full 与 Block 差距随规模缩小,最大规模仅 0.001);K3 用 8 blocks × 12 层 → 9 源(加 embedding)。

                                                                                                                                                                                                                                                                                                                                                                                                                                              2.3.2 对比基线(block vs full)

                                                                                                                                                                                                                                                                                                                                                                                                                                              维度

                                                                                                                                                                                                                                                                                                                                                                                                                                              Block

                                                                                                                                                                                                                                                                                                                                                                                                                                              Full

                                                                                                                                                                                                                                                                                                                                                                                                                                              内存

                                                                                                                                                                                                                                                                                                                                                                                                                                              O(Nd)

                                                                                                                                                                                                                                                                                                                                                                                                                                              O(Ld)

                                                                                                                                                                                                                                                                                                                                                                                                                                              算术

                                                                                                                                                                                                                                                                                                                                                                                                                                              O(L·N·d)

                                                                                                                                                                                                                                                                                                                                                                                                                                              O(L²d)

                                                                                                                                                                                                                                                                                                                                                                                                                                              精度

                                                                                                                                                                                                                                                                                                                                                                                                                                              最接近

                                                                                                                                                                                                                                                                                                                                                                                                                                              最优

                                                                                                                                                                                                                                                                                                                                                                                                                                              针对性

                                                                                                                                                                                                                                                                                                                                                                                                                                              面向训练内存/通信

                                                                                                                                                                                                                                                                                                                                                                                                                                              参照(理论最优)

                                                                                                                                                                                                                                                                                                                                                                                                                                              Block size 扫描(论文 Fig. 6,16 层模型):S 从 1(即 Full)粗化到 32,loss 优雅退化:

                                                                                                                                                                                                                                                                                                                                                                                                                                              Block size S

                                                                                                                                                                                                                                                                                                                                                                                                                                              1 (Full)

                                                                                                                                                                                                                                                                                                                                                                                                                                              2

                                                                                                                                                                                                                                                                                                                                                                                                                                              4

                                                                                                                                                                                                                                                                                                                                                                                                                                              8

                                                                                                                                                                                                                                                                                                                                                                                                                                              16

                                                                                                                                                                                                                                                                                                                                                                                                                                              32

                                                                                                                                                                                                                                                                                                                                                                                                                                              Loss

                                                                                                                                                                                                                                                                                                                                                                                                                                              1.737

                                                                                                                                                                                                                                                                                                                                                                                                                                              1.746

                                                                                                                                                                                                                                                                                                                                                                                                                                              1.746

                                                                                                                                                                                                                                                                                                                                                                                                                                              1.746

                                                                                                                                                                                                                                                                                                                                                                                                                                              1.757

                                                                                                                                                                                                                                                                                                                                                                                                                                              1.753

                                                                                                                                                                                                                                                                                                                                                                                                                                              S=2/4/8 都落在 1.746 附近,S=16/32 靠近 baseline(1.766)。论文因此固定 ≈ 8 个块。

                                                                                                                                                                                                                                                                                                                                                                                                                                              2.3.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                              • a) 反对:块内压缩丢失层间差异(块内所有层共享同一个 key/value),block 是"近似 full"的折扣——本质上是 N 的选择。

                                                                                                                                                                                                                                                                                                                                                                                                                                              • b) 失败假设:假设块内所有层输出可以被同等压缩(相加);极端情况可能丢信息。

                                                                                                                                                                                                                                                                                                                                                                                                                                              • c) 胜出条件:随着模型变大 L 越来越大、块数 N 固定(≈8)→ 每个块更"稠密",信息损失越来越小;失败:块过小(内存仍大)或块太大(早期块太稠密,读到的已是压缩)。

                                                                                                                                                                                                                                                                                                                                                                                                                                              • d) 更稳做法:soft-block 或轻量跨块(论文未做)。

                                                                                                                                                                                                                                                                                                                                                                                                                                              • e) 受损方:训练(PP 通信必须在块边界)。

                                                                                                                                                                                                                                                                                                                                                                                                                                              2.3.4 复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                              • 内存:O(Nd)(K3: 8 块)。

                                                                                                                                                                                                                                                                                                                                                                                                                                              • 算术:每层 O(N d)(attention over blocks),总 O(L N d)。

                                                                                                                                                                                                                                                                                                                                                                                                                                              • 对比 Full:算术 O(L²) → O(LN),N=8 时 ~L/8 倍省(L=93 时 ~11.6×)。

                                                                                                                                                                                                                                                                                                                                                                                                                                              2.3.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                              • block_size(每块层数):本项目 block_size 直接当 block_units(默认 4),kimi3-master 用 block_units = block_size * per_layer(per_layer=2,默认 24)。论文建议 block_size≈12(层)/ 24(单元)对应 K3。

                                                                                                                                                                                                                                                                                                                                                                                                                                              • 论文经验:N≈8「recover most of the benefit」;增加 block count 一般会提升但受限于通信/内存。

                                                                                                                                                                                                                                                                                                                                                                                                                                              2.3.6 工程实现(论文 Fig. 2 伪代码 vs 本项目)

                                                                                                                                                                                                                                                                                                                                                                                                                                              论文 Fig. 2 的关键伪代码:

                                                                                                                                                                                                                                                                                                                                                                                                                                                def block_attn_res(blocks, partial_block, proj, norm) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                    # blocks: N tensors [B,T,D]; partial_block: [B,T,D] (intra-block partial sum)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    V = torch.stack(blocks + [partial_block])          # [N+1, B, T, D]
                                                                                                                                                                                                                                                                                                                                                                                                                                                    K = norm(V)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    logits = torch.einsum('d, n b t d -> n b t', proj.weight.squeeze(), K)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    h = torch.einsum('n b t, n b t d -> b t d', logits.softmax(0), V)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    return h


                                                                                                                                                                                                                                                                                                                                                                                                                                                def forward(self, blocks, hidden_states):
                                                                                                                                                                                                                                                                                                                                                                                                                                                    partial_block = hidden_states
                                                                                                                                                                                                                                                                                                                                                                                                                                                    # apply block attnres before attn
                                                                                                                                                                                                                                                                                                                                                                                                                                                    h = block_attn_res(blocks, partial_block, self.attn_res_proj, self.attn_res_norm)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    # if reaches block boundary, start new block (block_size counts ATTN+MLP)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    if self.layer_number % (self.block_size // 2) == 0:
                                                                                                                                                                                                                                                                                                                                                                                                                                                        blocks.append(partial_block); partial_block = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                    attn_out = self.attn(self.attn_norm(h))
                                                                                                                                                                                                                                                                                                                                                                                                                                                    partial_block = partial_block + attn_out if partial_block is not None else attn_out
                                                                                                                                                                                                                                                                                                                                                                                                                                                    # apply block attnres before MLP
                                                                                                                                                                                                                                                                                                                                                                                                                                                    h = block_attn_res(blocks, partial_block, self.mlp_res_proj, self.mlp_res_norm)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    mlp_out = self.mlp(self.mlp_norm(h))
                                                                                                                                                                                                                                                                                                                                                                                                                                                    partial_block = partial_block + mlp_out
                                                                                                                                                                                                                                                                                                                                                                                                                                                    return blocks, partial_block

                                                                                                                                                                                                                                                                                                                                                                                                                                                与本项目 attn_res.py 的逐行对应:

                                                                                                                                                                                                                                                                                                                                                                                                                                                • block_attn_res ↔ mix():V=stack(sources)、K=rms_norm、logits=einsum('d,nbtd->nbt')、h=einsum('nbt,nbtd->btd') 完全同构。

                                                                                                                                                                                                                                                                                                                                                                                                                                                • 块边界判断 layer_number % (block_size//2) == 0 ↔ add_output 的 units_in_block >= block_units。

                                                                                                                                                                                                                                                                                                                                                                                                                                                • 双 block_attn_res 调用(attn 前 + MLP 前)↔ model.py 的每 block 两次 mix。

                                                                                                                                                                                                                                                                                                                                                                                                                                                集成:model.py 中的 Kimi3Model —— 先把 h 进 init_state,对每个 block 先 mix(state, unit_idx)(把历史混合作为该层输入),执行 block 后 add_output。granularity="sublayer"(默认)时,每个 transformer 层有 attention 读 + MLP 读两个单位,故 n_units = n_layers*2;

                                                                                                                                                                                                                                                                                                                                                                                                                                                不同库的块单位换算不同:Model-Viz 把 block_size 直接当 block_units(默认 4),而 kimi3-master 用 block_units = block_size * per_layer(per_layer=2 → 默认 24)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                2.3.7 探讨/验证

                                                                                                                                                                                                                                                                                                                                                                                                                                                test_block_form_matches_the_eq10_oracle(naive 独立转写比对);test_memory_is_bounded_by_block_count;test_gradients_reach_every_depth;test_paper_partition_for_the_2p8t_config(93 层/12 → 8 块/9 源)。全部通过。完成度:已实现并运行通过。

                                                                                                                                                                                                                                                                                                                                                                                                                                                Q1:activation recomputation 为什么被影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                标准 activation checkpointing 可以丢掉中间激活,反向时从 checkpoint 重算。但 Full AttnRes 要让后续很多层继续访问旧层输出;如果丢掉它们,后续层无法直接算深度注意力,或者必须频繁重算历史输出。于是它把“可释放的中间态”变成“跨多层被读取的 KV‑like 源”。

                                                                                                                                                                                                                                                                                                                                                                                                                                                Block AttnRes 的妥协是只保存每个块的聚合表示和当前块 partial prefix。这样 activation checkpointing 仍可丢掉 softmax 中间量和大量块内细节,保留少量块级 bank。

                                                                                                                                                                                                                                                                                                                                                                                                                                                Q2:pipeline parallelism 为什么变贵

                                                                                                                                                                                                                                                                                                                                                                                                                                                普通 PP stage 边界只传 hidden_states 和常规 residual。AttnRes 需要下游 stage 也能看到历史块,所以边界还要传 block bank。

                                                                                                                                                                                                                                                                                                                                                                                                                                                若 Full AttnRes 传每层历史,成本随层数涨;Block AttnRes 传块表示,成本随块数涨。

                                                                                                                                                                                                                                                                                                                                                                                                                                                论文提出 cross‑stage caching: 同一物理 stage 在交错流水线的不同 virtual stage 会重复看到部分历史块,因此可缓存已见块,只传新增块,减少冗余通信。


                                                                                                                                                                                                                                                                                                                                                                                                                                                2.4 状态机(AttnResState —— 深度历史如何在层间流动)

                                                                                                                                                                                                                                                                                                                                                                                                                                                AttnResState 是 Block Attention Residuals 的跨层状态机,解决的核心问题是:如何在 O(Nd) 内存约束下(而不是 O(Ld)),让每一层都能"选择性读取"之前所有层的输出。

                                                                                                                                                                                                                                                                                                                                                                                                                                                2.4.1 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                问题:attn 需要在遍历 93 层时"记住"哪些源可用、块进行到哪一步、partial 是什么。

                                                                                                                                                                                                                                                                                                                                                                                                                                                难点:这是一个"顺序推进的、跨层的可变状态",且需要支持 full/block 两模式。

                                                                                                                                                                                                                                                                                                                                                                                                                                                思路:用一个可变 state 对象,每过一层由 add_output 更新。blocks = 已完成的块表示列表;partial = 当前块内运行和;units_in_block = 当前块已累积的单位数。sources() 根据 partial 是否为 None 组装可读列表。

                                                                                                                                                                                                                                                                                                                                                                                                                                                原理:把 block 折叠的时机编码进状态机,而非 per-layer 的全局逻辑。

                                                                                                                                                                                                                                                                                                                                                                                                                                                下图给出 AttnResState 在 AttentionResiduals 中的状态演进(Block 形式):init → 逐子层主循环(mix/block/add_output)→ 满块折叠 → finalize。

                                                                                                                                                                                                                                                                                                                                                                                                                                                AttnResState
                                                                                                                                                                                                                                                                                                                                                                                                                                                AttnResState

                                                                                                                                                                                                                                                                                                                                                                                                                                                循环:每个 unit 走一遍 mix → 输出 → add_output

                                                                                                                                                                                                                                                                                                                                                                                                                                                • partial 累计本块输出,units_in_block 计数

                                                                                                                                                                                                                                                                                                                                                                                                                                                • 满块:partial 归档进 blocks[],partial 置 None、计数清零(O(Ld)→O(Nd))

                                                                                                                                                                                                                                                                                                                                                                                                                                                • finalize 把尾部不全块并入后做最终 mix

                                                                                                                                                                                                                                                                                                                                                                                                                                                2.4.2 对比基线

                                                                                                                                                                                                                                                                                                                                                                                                                                                标准残差没有"状态"——只用局部 h_{l-1}。

                                                                                                                                                                                                                                                                                                                                                                                                                                                AttnRes 需要显式的跨层状态。这是「深度上像 RNN 一样需要 carry 状态」的体现,与序列建模中 RNN 隐状态是同构的。

                                                                                                                                                                                                                                                                                                                                                                                                                                                2.4.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                • a) 反对:状态机的存在让并行(PP/SP)变麻烦——状态必须跨 stage 传递。论文用 cache-based pipeline communication 缓解(见 2.8)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                • b) 失败假设:假设状态很小(N 个块 + 1 partial),可被高效序列化;当 N 变大时仍要承担。

                                                                                                                                                                                                                                                                                                                                                                                                                                                • c) 胜出条件:N 固定小(8);失败:大 N。

                                                                                                                                                                                                                                                                                                                                                                                                                                                • d) 更稳做法:把状态换成"固定长度 buffer"(预分配)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                • e) 受损方:推理/训练基础设施(需同步状态)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                2.4.4 复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                内存:state = O(N·B·T·d)(N 个块表示)。partial 为 1×B×T×d。总 O(N·B·T·d) 与 Full O(L·B·T·d) 相比 N≪L。

                                                                                                                                                                                                                                                                                                                                                                                                                                                2.4.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                                block_units 直接决定 units_in_block 的翻转阈值。若设太小,partial 频繁折叠成 block(→ 退化为 Full 般大 N);设太大,块表示太稠密(选择性降低)。论文经验:K3 取 12 层/块(24 单元)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                2.4.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                AttnResState管理两个数据结构:

                                                                                                                                                                                                                                                                                                                                                                                                                                                字段

                                                                                                                                                                                                                                                                                                                                                                                                                                                含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                内存复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                blocks: list[Tensor]

                                                                                                                                                                                                                                                                                                                                                                                                                                                已完成的块塌缩表示(blocks[0] 恒为 token embedding)

                                                                                                                                                                                                                                                                                                                                                                                                                                                O(Nd),N=块数

                                                                                                                                                                                                                                                                                                                                                                                                                                                partial: Tensor

                                                                                                                                                                                                                                                                                                                                                                                                                                                当前块正在累计的运行和

                                                                                                                                                                                                                                                                                                                                                                                                                                                O(d)

                                                                                                                                                                                                                                                                                                                                                                                                                                                units_in_block: int

                                                                                                                                                                                                                                                                                                                                                                                                                                                当前块已累计的子层数

                                                                                                                                                                                                                                                                                                                                                                                                                                                O(1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                每过一个子层调用一次 add_output():把该子层输出累加进 partial,块写满后把 partial 归档进 blocks 并清空——这就是"块塌缩"发生的时刻,把 L 层输出压缩到 N 个块表示。

                                                                                                                                                                                                                                                                                                                                                                                                                                                init_state(embedding) 设 blocks=[embedding]、partial=None;add_output 折叠逻辑;finalize 把残余 partial 也 append 后 mix。对应 kimi3-master 完全一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                一屏示意图(对应全过程的状态演进):

                                                                                                                                                                                                                                                                                                                                                                                                                                                  ┌─────────────────────────────────────────────────────────────┐
                                                                                                                                                                                                                                                                                                                                                                                                                                                  │  AttentionResiduals 数据流(AttentionState — Block 形式)     │
                                                                                                                                                                                                                                                                                                                                                                                                                                                  └─────────────────────────────────────────────────────────────┘


                                                                                                                                                                                                                                                                                                                                                                                                                                                    ① init_state(h_embed)                        states:blocks = [h_embed]
                                                                                                                                                                                                                                                                                                                                                                                                                                                          inputs: partial = None, units_in_block = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                          (embedding 恒为第 0 个源)
                                                                                                                                                                                                                                                                                                                                                                                                                                                              │
                                                                                                                                                                                                                                                                                                                                                                                                                                                              ▼
                                                                                                                                                                                                                                                                                                                                                                                                                                                    ② for each unit_idx in [attention 子层, FFN 子层, ...]      # n_units
                                                                                                                                                                                                                                                                                                                                                                                                                                                              │
                                                                                                                                                                                                                                                                                                                                                                                                                                                              ▼
                                                                                                                                                                                                                                                                                                                                                                                                                                                    ③ mix(unit) :本 unit 的 深度 softmax 注意力
                                                                                                                                                                                                                                                                                                                                                                                                                                                          sources   = state.sources()          # blocks + [partial](partial None 时仅 blocks)
                                                                                                                                                                                                                                                                                                                                                                                                                                                          keys      = RNorm(sources)           # 防"嗓门大"的源垄断权重
                                                                                                                                                                                                                                                                                                                                                                                                                                                          alpha     = softmax( w_l · keys )    # 对"源"维归一化(Eq.9)
                                                                                                                                                                                                                                                                                                                                                                                                                                                          h_l       = sum_i alpha_i · sources_i
                                                                                                                                                                                                                                                                                                                                                                                                                                                              │
                                                                                                                                                                                                                                                                                                                                                                                                                                                              ▼
                                                                                                                                                                                                                                                                                                                                                                                                                                                    ④ 执行当前 sublayer(按真实模型跑正常 sublayer)
                                                                                                                                                                                                                                                                                                                                                                                                                                                          out = sublayer( h_l )                # attention 层 / FFN 层
                                                                                                                                                                                                                                                                                                                                                                                                                                                              │
                                                                                                                                                                                                                                                                                                                                                                                                                                                              ▼
                                                                                                                                                                                                                                                                                                                                                                                                                                                    ⑤ add_output( out )
                                                                                                                                                                                                                                                                                                                                                                                                                                                          partial        += out
                                                                                                                                                                                                                                                                                                                                                                                                                                                          units_in_block += 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                              │
                                                                                                                                                                                                                                                                                                                                                                                                                                                              ▼
                                                                                                                                                                                                                                                                                                                                                                                                                                                    ⑥ units_in_block == block_units ?   ── 满块?
                                                                                                                                                                                                                                                                                                                                                                                                                                                          ├─ 否 ──────────────────────────────► 回到 ③(本块下一个 unit)
                                                                                                                                                                                                                                                                                                                                                                                                                                                          └─ 是 ──── 折叠归档:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                blocks.append( partial )
                                                                                                                                                                                                                                                                                                                                                                                                                                                                partial = None ; units_in_block = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                ▼
                                                                                                                                                                                                                                                                                                                                                                                                                                                            (下一块第一个 unit 从 ③ 开始)
                                                                                                                                                                                                                                                                                                                                                                                                                                                              │
                                                                                                                                                                                                                                                                                                                                                                                                                                                              ▼ (循环结束后)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    ⑦ finalize()
                                                                                                                                                                                                                                                                                                                                                                                                                                                          if partial is not None: blocks.append( partial)
                                                                                                                                                                                                                                                                                                                                                                                                                                                          out = mix( final 伪查询 )            # 对全部 blocks 再混合一次
                                                                                                                                                                                                                                                                                                                                                                                                                                                              │
                                                                                                                                                                                                                                                                                                                                                                                                                                                              ▼
                                                                                                                                                                                                                                                                                                                                                                                                                                                    ⑧ 返回末层输出 h_out

                                                                                                                                                                                                                                                                                                                                                                                                                                                  直观解读:③ mix 是"读"(深度维度 attention),④ 是"处理"(真实模型),⑤ 是"写"(折入状态);⑥ 决定何时把「块与块之间的运行和 partial」归档成「不可变的块表示」。这就是 AttnResState 这台"深度流水线状态机"的完整轨迹,与 online-softmax 两阶段加速完全对应。

                                                                                                                                                                                                                                                                                                                                                                                                                                                  2.4.7 如果不用 AttnResState,会造成什么困难?

                                                                                                                                                                                                                                                                                                                                                                                                                                                  困难 1:内存爆炸(Full AttnRes 的 O(Ld))

                                                                                                                                                                                                                                                                                                                                                                                                                                                  如果不分块(Block),每层都要保留之前所有层的完整输出:

                                                                                                                                                                                                                                                                                                                                                                                                                                                    # 不用 AttnResState(朴素 Full AttnRes)
                                                                                                                                                                                                                                                                                                                                                                                                                                                    all_outputs = [embedding]  # 每加一层 append 一次
                                                                                                                                                                                                                                                                                                                                                                                                                                                    for layer in layers:
                                                                                                                                                                                                                                                                                                                                                                                                                                                        h = attention_mix(all_outputs)  # 对所有历史做 softmax
                                                                                                                                                                                                                                                                                                                                                                                                                                                        all_outputs.append(layer(h))
                                                                                                                                                                                                                                                                                                                                                                                                                                                    # 内存 = L * d,L=96 层时 96 份完整激活

                                                                                                                                                                                                                                                                                                                                                                                                                                                    K3 用 96 层,96 份 hidden state 常驻内存 → pipeline stage 间通信量爆炸,GPU 内存吃不消。

                                                                                                                                                                                                                                                                                                                                                                                                                                                    困难 2:退化为标准残差(失去选择性)

                                                                                                                                                                                                                                                                                                                                                                                                                                                    如果根本不做"跨层注意",就退化成普通残差连接:

                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 标准残差(无 AttnRes)
                                                                                                                                                                                                                                                                                                                                                                                                                                                      h = embedding
                                                                                                                                                                                                                                                                                                                                                                                                                                                      for layer in layers:
                                                                                                                                                                                                                                                                                                                                                                                                                                                          h = h + layer(h)  # 无差别累加

                                                                                                                                                                                                                                                                                                                                                                                                                                                      这等价于 alpha_i = 1/L(均匀权重)——每一层对历史的影响完全相同,模型无法学习"第 30 层应该多读 embedding、少读第 5 层"这种选择性。

                                                                                                                                                                                                                                                                                                                                                                                                                                                      困难 3:手写状态机容易出错

                                                                                                                                                                                                                                                                                                                                                                                                                                                      Block 塌缩的边界条件很微妙:

                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 何时归档 partial?(满 block_units 时)

                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 最后一个不满的 partial 怎么办?(finalize() 兜底)

                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 如何对 gradient checkpoint 友好?(detach() 深拷贝)

                                                                                                                                                                                                                                                                                                                                                                                                                                                      手写这些逻辑每个模型都要重新实现一遍,容易写出 off-by-one 错误(比如少归档最后一个 partial、或 partial 没清空)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                      困难 4:失去可解释性窗口

                                                                                                                                                                                                                                                                                                                                                                                                                                                      AttnResState.attention_weights() 暴露 alpha 分布用于分析/可视化——能看到"第 L 层到底读了哪些源"。没有这个抽象,调试"为什么模型学不出选择性"就只能盲猜。

                                                                                                                                                                                                                                                                                                                                                                                                                                                      一句话总结

                                                                                                                                                                                                                                                                                                                                                                                                                                                      AttnResState 是用 O(Nd) 内存实现"深度维 softmax 注意力"的状态机,它解决了:

                                                                                                                                                                                                                                                                                                                                                                                                                                                      问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                      不用它

                                                                                                                                                                                                                                                                                                                                                                                                                                                      用它

                                                                                                                                                                                                                                                                                                                                                                                                                                                      内存

                                                                                                                                                                                                                                                                                                                                                                                                                                                      O(Ld) = 96 份激活

                                                                                                                                                                                                                                                                                                                                                                                                                                                      O(Nd) = 8 份激活

                                                                                                                                                                                                                                                                                                                                                                                                                                                      选择性

                                                                                                                                                                                                                                                                                                                                                                                                                                                      退化为均匀残差

                                                                                                                                                                                                                                                                                                                                                                                                                                                      每层学习专属 alpha

                                                                                                                                                                                                                                                                                                                                                                                                                                                      正确性

                                                                                                                                                                                                                                                                                                                                                                                                                                                      手写状态机易错

                                                                                                                                                                                                                                                                                                                                                                                                                                                      统一的 init/mix/add/finalize

                                                                                                                                                                                                                                                                                                                                                                                                                                                      可解释性

                                                                                                                                                                                                                                                                                                                                                                                                                                                      黑盒

                                                                                                                                                                                                                                                                                                                                                                                                                                                      可读 alpha 分布

                                                                                                                                                                                                                                                                                                                                                                                                                                                      2.4.8 AttnResState  如何解决问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                      FullAttentionResiduals 就是 block_units=1 的特例——证明 Block 和 Full 在数学上等价,只是内存策略不同。这是理解整个设计的钥匙。

                                                                                                                                                                                                                                                                                                                                                                                                                                                      问题 1:内存爆炸 → add_output() 的块塌缩

                                                                                                                                                                                                                                                                                                                                                                                                                                                      代码:attn_res.py:178-195

                                                                                                                                                                                                                                                                                                                                                                                                                                                        def add_output(self, state: AttnResState, output: Tensor) -> AttnResState:
                                                                                                                                                                                                                                                                                                                                                                                                                                                            state.partial = output if state.partial is None else state.partial + output
                                                                                                                                                                                                                                                                                                                                                                                                                                                            state.units_in_block += 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                            if state.units_in_block >= self.block_units:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                state.blocks.append(state.partial)   # ★ 块塌缩发生
                                                                                                                                                                                                                                                                                                                                                                                                                                                                state.partial = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                state.units_in_block = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                            return state

                                                                                                                                                                                                                                                                                                                                                                                                                                                        机制:每个子层的输出先累加进 partial(running sum),写满 block_units 个后才"归档"为 blocks 中的一个条目。K3 用 block_units=12,意味着 12 个子层输出被压缩成 1 个块表示。

                                                                                                                                                                                                                                                                                                                                                                                                                                                        数学等价性:blocks[n] = Σ_{i∈block_n} output_i(求和塌缩)。虽然求和有损,但实验表明它保留了足够信息让后续的 softmax 注意仍能区分块。

                                                                                                                                                                                                                                                                                                                                                                                                                                                        内存对比(K3, d=7168):

                                                                                                                                                                                                                                                                                                                                                                                                                                                        形式

                                                                                                                                                                                                                                                                                                                                                                                                                                                        内存

                                                                                                                                                                                                                                                                                                                                                                                                                                                        96 层 × 7168

                                                                                                                                                                                                                                                                                                                                                                                                                                                        Full

                                                                                                                                                                                                                                                                                                                                                                                                                                                        L × d

                                                                                                                                                                                                                                                                                                                                                                                                                                                        688 KB/token(爆炸)

                                                                                                                                                                                                                                                                                                                                                                                                                                                        Block (N=8)

                                                                                                                                                                                                                                                                                                                                                                                                                                                        N × d

                                                                                                                                                                                                                                                                                                                                                                                                                                                        57 KB/token(可接受)


                                                                                                                                                                                                                                                                                                                                                                                                                                                        问题 2:选择性 → mix() 的深度维 softmax

                                                                                                                                                                                                                                                                                                                                                                                                                                                        代码:attn_res.py:157-176

                                                                                                                                                                                                                                                                                                                                                                                                                                                          def mix(self, state: AttnResState, unit_idx: int) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                              sources = state.sources()  # [emb, b_1, ..., b_n, partial?]
                                                                                                                                                                                                                                                                                                                                                                                                                                                              if len(sources) == 1:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                  return sources[0]
                                                                                                                                                                                                                                                                                                                                                                                                                                                              stacked = torch.stack(sources, dim=0)            # (n, b, t, d)
                                                                                                                                                                                                                                                                                                                                                                                                                                                              keys = rms_norm(stacked, self.key_norm_weight)   # 防垄断
                                                                                                                                                                                                                                                                                                                                                                                                                                                              query = self.queries[unit_idx]                   # (d,) 每层专属
                                                                                                                                                                                                                                                                                                                                                                                                                                                              scores = torch.einsum("nbtd,d->nbt", keys, query)
                                                                                                                                                                                                                                                                                                                                                                                                                                                              weights = torch.softmax(scores.float(), dim=0)   # 沿源维归一化
                                                                                                                                                                                                                                                                                                                                                                                                                                                              return torch.einsum("nbt,nbtd->btd", weights, stacked)

                                                                                                                                                                                                                                                                                                                                                                                                                                                          机制:每个 unit(子层)有独立的可学习伪查询self.queries[unit_idx],对所有可见源(已完成块 + 当前 partial)打分,softmax 归一化后加权混合。

                                                                                                                                                                                                                                                                                                                                                                                                                                                          这就是"选择性"的物理实现:

                                                                                                                                                                                                                                                                                                                                                                                                                                                          • queries[unit_idx] 高维向量是可学习的"地址"

                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 训练后模型可能学到:第 30 层应该多读 blocks[0](embedding),少读 blocks[3]

                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 标准残差只是 weights = 1/n 的特例——mix() 把它推广为可学习的分布

                                                                                                                                                                                                                                                                                                                                                                                                                                                          RMSNorm 的作用(attn_res.py:172):防止某层输出幅值过大导致 scores 被它垄断,保证 softmax 不塌缩成 one-hot。


                                                                                                                                                                                                                                                                                                                                                                                                                                                          问题 3:正确性 → finalize() 的兜底逻辑

                                                                                                                                                                                                                                                                                                                                                                                                                                                          代码:attn_res.py:197-208

                                                                                                                                                                                                                                                                                                                                                                                                                                                            def finalize(self, state: AttnResState) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                if state.partial is not None:           # ★ 兜底:尾巴的 partial 也要归档
                                                                                                                                                                                                                                                                                                                                                                                                                                                                    state.blocks.append(state.partial)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                    state.partial = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                    state.units_in_block = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                return self.mix(state, self.n_units)    # 用第 n_units 个 query 做最终聚合

                                                                                                                                                                                                                                                                                                                                                                                                                                                            机制:K3 有 96 层 ÷ 12/块 = 8 个完整块,但如果改成 100 层 ÷ 12/块 = 8 块 + 4 层尾巴,第 9 个块是不满的。finalize() 检查 partial is not None,把这个不满的尾巴也归档进 blocks,确保所有子层输出都被纳入最终聚合,一个不漏。

                                                                                                                                                                                                                                                                                                                                                                                                                                                            这就是手写状态机容易出错的地方:

                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 忘记归档尾巴 → 最后 4 层输出被丢弃

                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 忘记清空 partial → 下次 forward 状态污染

                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 忘记用 n_units 作为 query index → 用了某个中间层的 query 做最终聚合

                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttnResState 把这 3 个坑全部封装在 finalize() 里。


                                                                                                                                                                                                                                                                                                                                                                                                                                                            问题 4:可解释性 → attention_weights() 的暴露

                                                                                                                                                                                                                                                                                                                                                                                                                                                            代码:attn_res.py:210-221

                                                                                                                                                                                                                                                                                                                                                                                                                                                              def attention_weights(self, state: AttnResState, unit_idx: int) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                  sources = state.sources()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                  stacked = torch.stack(sources, dim=0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                  keys = rms_norm(stacked, self.key_norm_weight, self.eps)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                  scores = torch.einsum("nbtd,d->nbt", keys, self.queries[unit_idx])
                                                                                                                                                                                                                                                                                                                                                                                                                                                                  return torch.softmax(scores.float(), dim=0)  # (n, b, t)

                                                                                                                                                                                                                                                                                                                                                                                                                                                              机制:与 mix()共享前 4 行(打分核完全相同),但不做加权求和,直接返回 alpha 分布。形状 (n, b, t) 告诉你"unit_idx 这个子层,对每个源、每个 batch、每个 token 位置分配了多少注意力权重"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                              这就是 debug 的窗口:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                state = attn_res.init_state(embedding)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                for i, layer in enumerate(layers):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                    h = attn_res.mix(state, i)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                    out = layer(h)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                    state = attn_res.add_output(state, out)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                    if i % 12 == 0:  # 每块结束看一次
                                                                                                                                                                                                                                                                                                                                                                                                                                                                        alpha = attn_res.attention_weights(state, i)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                        print(f"layer {i}: alpha over {len(state.sources())} sources = {alpha}")

                                                                                                                                                                                                                                                                                                                                                                                                                                                                没有这个方法,你只能看 mix() 的最终输出,完全不知道模型在深度维上"读"了哪些层。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                总结:状态机的 4 个方法对应 4 个问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                方法

                                                                                                                                                                                                                                                                                                                                                                                                                                                                行号

                                                                                                                                                                                                                                                                                                                                                                                                                                                                解决什么问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                关键操作

                                                                                                                                                                                                                                                                                                                                                                                                                                                                init_state()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                151-155

                                                                                                                                                                                                                                                                                                                                                                                                                                                                初始化(embedding 永远是源)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                blocks=[embedding]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                mix()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                157-176

                                                                                                                                                                                                                                                                                                                                                                                                                                                                选择性(softmax 深度注意)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                queries[unit_idx]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                 × RMSNorm × softmax

                                                                                                                                                                                                                                                                                                                                                                                                                                                                add_output()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                178-195

                                                                                                                                                                                                                                                                                                                                                                                                                                                                内存(块塌缩 O(Ld)→O(Nd))

                                                                                                                                                                                                                                                                                                                                                                                                                                                                满 block_units 时归档 partial

                                                                                                                                                                                                                                                                                                                                                                                                                                                                finalize()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                197-208

                                                                                                                                                                                                                                                                                                                                                                                                                                                                正确性(兜底尾巴)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                不满块也归档 + 最终聚合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                attention_weights()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                210-221

                                                                                                                                                                                                                                                                                                                                                                                                                                                                可解释性(暴露 alpha)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                只打分不混合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                Block 和 Full 的等价性(attn_res.py:230-244):FullAttentionResiduals 就是 block_units=1——每个输出立即归档成"块",数学上和 Block 完全等价,只是内存策略不同。这证明了块塌缩不损失表达能力,只是工程上的内存优化。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.5 online-softmax 两阶段算法(论文 Algorithm 1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.5.1 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                问题:Full/Block AttnRes 在推理时是逐 token 的(decode)。要算 h_l = softmax(w_l·K)·V,理论上需要完整 softmax(读所有源)。但 Block 形式下,「已完成块的表示」是固定不变的(前块已经写完,不会变),只有「当前 partial」是逐 token 在变。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                难点:不想每 token 都对所有块重新做完整 softmax。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                思路(两阶段):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • Phase 1(跨块,可并行):对当前块的所有 S 个 site(该块内的各子层),一次性算出它们对所有已完成块的 logits → 得到每 site 的「块间统计量」(online-softmax 的 (max, sum-exp, weighted-sum))。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • Phase 2(块内,顺序):每个 site 只需要额外把「当前 partial」的 logit 与 Phase1 统计量 merge(在线合并),再 normalize → 得到最终输出。因为 partial 每 token 变,而块间统计量复用,decode 成本大幅降低。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                专家:这是把 softmax 拆成「可复用的块间 part + 变化的块内 part」的 online softmax 技巧,与 flash attention 的同款思想(把 attention 分解成可 merge 的 (m, l, Σ) 三元组)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                三个库对比:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • kimi3-master:朴素 torch(无两阶段)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • kimi-k3-pytorch:实现了完整 online-softmax 两阶段(online_softmax.py + two_phase.py),且 BlockAttentionResidualController 提供 backend="eager"|"two_phase" 开关。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • SGLang:在 CUDA kernel 里把「对 bank 的 online softmax」直接 fused 进单 kernel。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.5.2 对比基线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                eager

                                                                                                                                                                                                                                                                                                                                                                                                                                                                two_phase(online)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                对已完成块的重复计算

                                                                                                                                                                                                                                                                                                                                                                                                                                                                每次 site 都重算

                                                                                                                                                                                                                                                                                                                                                                                                                                                                只算一次(Phase1 向量化)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                需要的数据结构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                sources 列表

                                                                                                                                                                                                                                                                                                                                                                                                                                                                (max, Σexp, weighted_sum) 统计量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                decode 单 token 成本

                                                                                                                                                                                                                                                                                                                                                                                                                                                                O(N·d)(每 token 重扫全块)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                O(d)(只 merge partial)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.5.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • a) 反对:多了一套统计量状态,复杂;且 phase1 需要在块开头预先跑所有 site 的块间 logits(内存 = 块内 site 数 × 块数 × B×T)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • b) 失败假设:假设「已完成块」在 decode 期间不参与 partial 的在线更新;若 partial 与已完成块之间存在耦合(例如分层 RMSNorm),online 合并的数学成立性可能受考验。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • c) 胜出条件:decode 场景、长序列、块数 N 固定。失败:训练/prefill 全量序列(full softmax 直接算即可,省复杂度)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • d) 更稳做法:放弃两阶段,每 token 重算(简单可靠,但 O(N) 每 token)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • e) 受损方:实现者/推理引擎(复杂度);换来性能。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.5.4 复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • eager decode:每 token 每 site 重扫 N 个块 → O(N·B·T·d)(T 为 batch tokens)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • two_phase decode:Phase1 每块一次 O(N·B·T·d),Phase2 每 token 每 site O(d)。节省量随「一个块内的 site 数 S」增大而增加。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 论文报告:inference overhead < 2%(典型 workload,Table 1)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.5.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • backend 开关(eager/two_phase)直接控制此算法。S 越大(块内 site 越多),two_phase 收益越大。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • logits_in_fp32 / weighted_sum_in_fp32(kimi-k3-pytorch config)控制精度策略——默认 fp32 累加,保证两阶段 merge 的数值稳定性。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.5.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                paper-algo-1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                paper-algo-1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                代码(参考库):kimi-k3-pytorch-main 的 online_softmax.py(depth_softmax_stats / single_source_stats / merge_depth_softmax_stats / normalize_depth_softmax_stats / weights_from_stats),以及 two_phase.py(precompute_inter_block_stats / score_single_partial)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                本项目对应:本项目采用 kimi3 风格(朴素 torch 实现),未实现两阶段。若要参考生产做法,可对照上述文件。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                完成度:参考实现已提供(kimi-k3-pytorch),本项目未实现(采用朴素 torch,与 kimi3 一致)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.6 生产级 fused kernel 原理(SGLang;TMA + online softmax + 通信融合)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.6.1 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                问题:K3 真实部署时,AttnRes 每 token 要对 bank(最多 8 个块表示快照 + 1 个 prefix)做 online softmax 聚合 + 输出 RMSNorm。在 GB200/SM100 上这是高频、低算量、高访存操作,纯 PyTorch 逐层调用会卡在 kernel launch / 内存带宽。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                难点:把「读 bank 行 → score → online softmax → weighted combine → 输出 RMSNorm」整条链 fused 成一个 kernel,还要处理 TP(张量并行)下的通信。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                思路(SGLang):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 单 kernel:warp-specialized TMA kernel。一个 persistent CTA/SM:producer warp 用 bulk TMA 一次拉一行 bank 到 smem ring(2 个 chunk slot 双缓冲),8 个 consumer warp 做 score + online softmax fold + 写 TMEM。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 参数:bank[T, NB, H](NB=最多块表示数=8+1,H=7168),cw(score_norm_weight×proj_weight 预乘),ow(输出 RMSNorm weight),eps(两个 norm 共用)。nvb = 有效 bank 行数(1..8)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 通信融合:attn_res_fused_pull_rs(NVLS pull 规约 + local residual + fused)与 attn_res_fused_direct_ag(直接 multicast all-gather 融合)——把 AttnRes 聚合与 TP all-reduce 合二为一,省一次整张往返。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                专家视角:这是「online softmax 状态 (m,l,Σ) 天然可 merge」特性在 kernel 层的极致利用:bank 行是"已完成块",其统计可被并行 fold;write_prefix 把当前 prefix 行也写回 bank,支持后续复用。_TMA_BEST_CONFIG 是每 nvb 的调参表(GB200/GB300 实测),occupancy/consumer_regs 是 CTA 调度权衡。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.6.2 对比基线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                朴素(kimi3 torch)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                SGLang fused TMA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                kernel 数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                多次(norm/score/softmax/mix/norm)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                1 个 fused kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                通信

                                                                                                                                                                                                                                                                                                                                                                                                                                                                独立 all-reduce

                                                                                                                                                                                                                                                                                                                                                                                                                                                                fused 进 kernel(pull_rs/direct_ag)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                内存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                多次 HBM 往返

                                                                                                                                                                                                                                                                                                                                                                                                                                                                TMA 批量 + TMEM staging,最少往返

                                                                                                                                                                                                                                                                                                                                                                                                                                                                平台

                                                                                                                                                                                                                                                                                                                                                                                                                                                                任意

                                                                                                                                                                                                                                                                                                                                                                                                                                                                SM100a+(B100/B300/GB200 等)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                参数限制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                任意 d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                H==7168 模板参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.6.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • a) 反对:这套 kernel 复杂度极高,且 H=7168 硬编码、SM100 专用——不可移植、难维护。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • b) 失败假设:假设"每 token 聚合 bank"值得如此大的 kernel 工程投入;若该算子只占 <1% 时间,就是过度工程。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • c) 胜出条件:大 batch、多 token、SM100 集群(GB200 为主力时);失败:小规模 / 非 SM100。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • d) 更稳做法:用 Triton 通用 kernel 折中(本项目可接受)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • e) 受损方:运维方(版本约束、架构绑定)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.6.4 复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • HBM 流量:bank 读 = nvb×H 每 token;输出 = H。TMA 批量把读合并。通信:pull_rs/direct_ag 把 all-reduce 从独立 O(T·H) 变 fused(省一次 HBM 写读)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 具体数字需跑 benchmark;论文报告 Block AttnRes inference overhead <2%。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.6.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • nvb(有效块数)、chunk_rows(每 chunk 行数)、occupancy(CTA/SM)、consumer_regs。_TMA_BEST_CONFIG 表(sglang attn_res.py)给出每 nvb 的最优 (chunk_rows, occupancy, consumer_regs)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • write_prefix:是否把 prefix 行回写 bank(后续可作 prefix 复用)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.6.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                代码(参考):sglang-main 的 python/sglang/srt/layers/attn_residual.py(Python 层调度,300+ 行)+ python/sglang/srt/kernels/kimi_k3/attn_res.py(TMA kernel wrapper)+ jit/csrc/kimi_k3/attn_res/fused_tma.cuh(CUDA 内核,946 行)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                本项目:本项目采用朴素 torch(与 kimi3 一致),未实现 fused kernel;本文档将其列为「生产级参考」。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                完成度:参考实现已提供(SGLang),本项目未采用。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.7 对比对象 —— mHC(Manifold-Constrained Hyper-Connections)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.7.1 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                问题:HC(Hyper-Connections)把残差变成可学习的多条平行流,但丧失了恒等映射性质(identity mapping 被破坏),训练不稳定、难扩展。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                mHC 的解决:把残差映射矩阵投影到 Birkhoff 多胞体(双随机矩阵)——行列和都等于 1。这样 P x 成为输入特征的凸组合(权重非负、和=1),特征均值守恒、信号范数被严格限制,组合闭包保恒等稳定性。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 直觉:HC 是"多车道",mHC 给每车道加了"所有车道权重加和为 1"的护栏(每列、每行都归一),既保住了多车道的信息流通,又不让信号越飙越大。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 准专业:H_l^{res} x_l 其中 H_l^{res} 是双随机矩阵(非负、行和=1、列和=1)。投影用 Sinkhorn-Knopp 算法(迭代行/列归一化)把任意矩阵投影到 Birkhoff 多胞体。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 专家:m 条平行流 H_l ∈ R^{d×m},更新 H_l = H_{l-1} A_l + f_{l-1}(H_{l-1} α_{l-1}) β_{l-1}^T。展开后有效权重 M_{i→l} = β_i^T A_{i+1→l} α_l,是 m-semiseparable 的深度维 linear attention(state expansion 到 d×m,提高 semiseparable rank)。双随机约束使 A_l 乘积 A_{i→l} 保持性质(范数守恒、composition closure),恢复 identity 稳定性。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                AttnRes 与 mHC 的本质差异(按论文 Table 5 与 §6.2):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 两者都是 input-dependent(动态)。真正的区别是注意力范式:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • mHC:深度维 linear attention(m-semiseparable,低秩)。权重是「学习 + 双随机约束投影」得到的线性变换(M_{i→l}=β^T_i A_{i+1→l} α_l),softmax 的竞争性归一化缺失——各源概率质量不竞争。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • AttnRes:深度维 softmax attention(稠密 rank-L)。权重 α_{i→l} 是 softmax 归一化的 input-dependent(直接对 v_i 内容做 exp 打分),概率质量在源间竞争,形成更锐利的选择。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 论文 Table 4 中 AttnRes(1.737/1.746)优于 mHC(1.747)的原因就是:softmax 的竞争性归一化 + 跨层直接检索。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                mHC 会维护多条并行的 Residual Stream。每一层先动态混合这些信息流,形成这一层的输入,再把这一层的输出分发回不同的信息流。它还会约束混合过程,避免模型变深后信息和梯度被无限放大。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                Attention Residuals 则更像为每一层提供一份历史目录,让它可以直接找到前面某个阶段产生的信息,并选择性地读取。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                只看理论表达能力,Attention Residuals 的上限可能更高。mHC 仍然要把历史信息递归压缩进固定数量的 Residual Stream;Full Attention Residuals 则可以让每个 token 直接关注所有较浅层的输出。打个比方,mHC 更像 RNN(循环神经网络)或线性注意力,信息通过有限状态逐层传递;Full Attention Residuals 更像 Transformer,可以直接跨层读取信息。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                但实际效果仍取决于具体实现。K3 使用的并不是所有层之间直连的 Full Attention Residuals,而是 Block Attention Residuals:先把模型层划分成多个 block,在每个 block 内汇总信息,再在不同 block 之间做 Attention。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.7.2 对比基线表

                                                                                                                                                                                                                                                                                                                                                                                                                                                                维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                Standard Residual

                                                                                                                                                                                                                                                                                                                                                                                                                                                                mHC

                                                                                                                                                                                                                                                                                                                                                                                                                                                                AttnRes (Block)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                更新公式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                h_l = h_{l-1} + f_{l-1}(h_{l-1})

                                                                                                                                                                                                                                                                                                                                                                                                                                                                H_l 多流 + 连接矩阵

                                                                                                                                                                                                                                                                                                                                                                                                                                                                h_l = Σ α_{i→l} v_i

                                                                                                                                                                                                                                                                                                                                                                                                                                                                状态数量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                m(如 4 条流)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                1 伪查询 + N 块表示

                                                                                                                                                                                                                                                                                                                                                                                                                                                                权重来源

                                                                                                                                                                                                                                                                                                                                                                                                                                                                固定单位 1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                学习 + 双随机投影(Sinkhorn)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                学习 + 输入相关 softmax

                                                                                                                                                                                                                                                                                                                                                                                                                                                                是否 input-dependent

                                                                                                                                                                                                                                                                                                                                                                                                                                                                否

                                                                                                                                                                                                                                                                                                                                                                                                                                                                是(Dynamic,Table 5)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                注意力范式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                深度维等权加法

                                                                                                                                                                                                                                                                                                                                                                                                                                                                深度维 linear attention(m-semiseparable)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                深度维 softmax attention(dense softmax)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                恒等稳定性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                好

                                                                                                                                                                                                                                                                                                                                                                                                                                                                双随机保证(identity 保真)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                zeros 初始化平滑出发(等效均匀)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                参数开销

                                                                                                                                                                                                                                                                                                                                                                                                                                                                0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                中等(连接矩阵 A + 转换 α/β)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                低(每层一个 w_l)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                内存 I/O

                                                                                                                                                                                                                                                                                                                                                                                                                                                                ~3d/层

                                                                                                                                                                                                                                                                                                                                                                                                                                                                ~34d/层(m=4)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                ~5.5d/层(Block)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                性能(16 层,论文 Table 4)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                1.766

                                                                                                                                                                                                                                                                                                                                                                                                                                                                1.747

                                                                                                                                                                                                                                                                                                                                                                                                                                                                1.737 / 1.746

                                                                                                                                                                                                                                                                                                                                                                                                                                                                并行 friendly

                                                                                                                                                                                                                                                                                                                                                                                                                                                                是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                一般

                                                                                                                                                                                                                                                                                                                                                                                                                                                                Block 形式友好(块边界通信)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                可解释性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                无

                                                                                                                                                                                                                                                                                                                                                                                                                                                                一般

                                                                                                                                                                                                                                                                                                                                                                                                                                                                好(α 可直接可视化)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                亲密度(本项目)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                基线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                未实现(仅对照)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                已实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                三条路线并排示意图(ASCII,重点:传给"深度历史"的信息流差异):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                三者对比
                                                                                                                                                                                                                                                                                                                                                                                                                                                                三者对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.7.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • a) 反对 AttnRes:固定伪查询无法做 input-dependent query;mHC 至少在结构上是动态的。且 AttnRes 的 softmax 权重在推理时主要由静态向量 w_l 决定(query 不含 token 信息),所谓 input-dependent 主要体现在 key 上。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • b) 失败假设:假设"每层的读取模式静态即可"。论文承认 input-dependent query 能再涨(1.731),说明固定伪查询仍有提升空间。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • c) 胜出条件:深度读模式相对稳定(关注 embedding / 邻居层 / 特定块)的任务;失败:需要 per-token 动态深度读。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • d) 更稳做法:AttnRes + input-dependent query(论文指出可做但需权衡)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • e) 受损方:无显著(两者都小开销)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.7.4 复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • mHC:状态 d×m,每层 I/O ~34d(m=4)远高于 AttnRes ~5.5d(Block,Table 1)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • AttnRes:算术 O(N·d)(Block)/ O(L·d)(Full),内存 O(N·B·T·d)(Block)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 结论:AttnRes 在「表达力相仿或更好」的同时,I/O 低约 6 倍(34d vs 5.5d)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.7.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • mHC:流数 m(2/4/8)、Sinkhorn 迭代数、use_dynamic_mapping。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • AttnRes:块大小 N、伪查询初始 w=0、RMSNorm eps。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 论文:N≈8 最优,mHC 的 m 视任务(通常 4)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.7.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 两者都是「残差可学习化」家族,但一个走约束矩阵(线性注意)、一个走软注意力。本项目选择 AttnRes(K3 采用),因其为 softmax attention(与序列建模同构)、实现简单、I/O 低、可解释性好。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.7.7 对比图(标准残差 vs mHC vs AttnRes)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                AttnRes-vs-mHC-vs-Residual
                                                                                                                                                                                                                                                                                                                                                                                                                                                                AttnRes-vs-mHC-vs-Residual
                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 上排 3 图:架构示意(标准残差蓝 / mHC 琥珀 / AttnRes 红主角)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 下排 3 图:深度-时间对偶性、每层 I/O(Table 1:3d vs 34d vs 5.5d)、Table 4 困惑度(1.766 vs 1.747 vs 1.737/1.746)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 图表关键读数(实测值回填):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • Full 1.737 / Block 1.746 / mHC 1.747 / PreNorm 1.766(Table 4)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 每层 I/O:标准残差 ≈3d、mHC(m=4) ≈34d、AttnRes Block ≈5.5d(Table 1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 关键推论:图上 AttnRes 同时满足"更低 loss + 更低 I/O",直接支撑"softmax attention 兼具表达力与效率"观点。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.8 基础设施:跨阶段缓存 + 高效 Prefill(论文 §4)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                 

                                                                                                                                                                                                                                                                                                                                                                                                                                                                这是 "Block AttnRes 成为标准残差即插即用替代品" 的工程前提。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.8.1 训练:跨阶段缓存(Cross-stage Caching)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                问题:标准残差下 pipeline parallelism 只在相邻 stage 间传一个固定大小的 hidden state(与 pipeline 深度无关)。Block AttnRes 需要每个 stage 的所有已累积块表示来做跨块注意,naïvely 每次 stage 过渡都传完整历史 → 冗余通信。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                推导(论文 Eq. 7-8):设 interleaved pipeline 有 P 个物理 stage、每物理 stage V 个虚拟 stage,C = P·V 个 chunk,第 j 个 chunk 累积 j·N_p 个块(N_p = 每物理 stage 每 token 产生的块数)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                • naïve 通信(每次过渡传全部累积块):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Comm_naive = Σ_{j=1}^{C-1} j·N_p·d = C(C-1)/2 · N_p·d      (Eq. 7)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 缓存后(块在本地位存,跨 stage 只传增量;第一虚拟 stage 无缓存正常累积,v≥2 只传 ~P·N_p 增量块):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Comm_cached = P(P-1)/2 · N_p·d   (第一虚拟 stage)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      + (V-1)·P²·N_p·d     (后续虚拟 stage)           (Eq. 8)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                            效果:每过渡的峰值通信从 O(C) 降到 O(P),是 V× 提升,且能完全与稳态 1F1B 的计算重叠。论文 Fig. 3 用 P=4、V=2 举例:第二虚拟 stage 时缓存消除了 6 次冗余块传输(每 stage 只在块边界才传增量 +[b1,b2] 而非全部 [b0,b1,b2,...])。注:块边界无需对齐物理 stage 边界(Fig. 3 中每块跨越两个物理 stage)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                            训练开销:无 PP 时 Block AttnRes 训练开销可忽略;有 PP 时端到端 overhead < 4%(论文 §4.1)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.8.2 并行状态下的 AttnResState

                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttnResState 不是分布式的,每个 stage 有自己的副本。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                            每个 pipeline stage 都持有自己的 AttnResState 实例,blocks 字段的内容随 stage 递增,即 blocks 列表内容是从上游复制/继承来的。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                            单机视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                            单机上,整个模型只有一个 AttnResState。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                              # 单机视角(你想象的)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                              state = attn_res.init_state(emb)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                              for layer in all_96_layers:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  h = attn_res.mix(state, i)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  out = layer(h)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  state = attn_res.add_output(state, out)  # blocks 累积到 9 个
                                                                                                                                                                                                                                                                                                                                                                                                                                                                              final = attn_res.finalize(state)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                              分布式视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                物理 Rank 0                物理 Rank 1                物理 Rank 2
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                │ AttnResState    │       │ AttnResState    │       │ AttnResState    │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                │  blocks=[b0]    │──→    │  blocks=[b0,b1] │──→    │  blocks=[b0,b1,b2]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                │  partial=None   │  传输 │  partial=b2_acc │  增量 │  partial=None   │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                │  units_in_block=0       │  units_in_block=1       │  units_in_block=0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                └─────────────────┘       └─────────────────┘       └─────────────────┘
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   处理 layer 0-1            处理 layer 2-3            处理 layer 4-5

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                pipeline parallelism 下,每个物理 rank 只跑一部分层,所以每个 rank 需要自己的 state:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # Rank 0(layer 0-23)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  state_r0 = attn_res.init_state(emb)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  for i inrange(24):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      h = attn_res.mix(state_r0, i)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      out = layer_r0[i](h)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      state_r0 = attn_res.add_output(state_r0, out)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # state_r0.blocks = [emb, b1, b2](2 个完整块 + partial)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # Rank 1(layer 24-47)—— 不重建,继承 r0 的 blocks
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  state_r1 = AttnResState(blocks=state_r0.blocks.copy(), partial=state_r0.partial, ...)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  for i inrange(24, 48):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      h = attn_res.mix(state_r1, i)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      out = layer_r1[i-24](h)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      state_r1 = attn_res.add_output(state_r1, out)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # state_r1.blocks = [emb, b1, b2, b3, b4](4 个完整块)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  关键区别

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  概念

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  是不是分布式的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  AttentionResiduals

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  (nn.Module)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  (共享参数)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  所有 stage 共享同一份 queries 和 key_norm_weight 权重(数据并行同步)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  AttnResState

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  (dataclass)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  否

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  (每 stage 独立)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  每个 stage 一个实例,blocks 内容递增

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  blocks

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   列表

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  跨 stage 复制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  每个 stage 的 blocks 包含上游所有块 + 自己新产生的块

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  2.8.3 Cross-stage Caching 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ① Cross-stage Caching 到底缓存什么?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  缓存的是 Block 表示 bn(不是 layer 输出、不是 hidden state、不是梯度)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  回看 attn_res.py:178-195 的 add_output():

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    if state.units_in_block >= self.block_units:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        state.blocks.append(state.partial)   # ★ 这就是要被缓存的东西

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    每个 blocks[i] 是一个已完成块的塌缩表示b_n = Σ_{j∈B_n} f_j(h_j),shape (B, T, d)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    在 pipeline parallelism 下,物理 rank 处理多个虚拟 stage,每个虚拟 stage 会产生若干块表示。Cross-stage caching 就是把这些 b_n 留在本地内存,下次遇到同一 micro-batch 时不再重传。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ② 为什么这些可以缓存?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    关键洞察:块表示 bn 一旦归档,就不再变化。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    看 attn_res.py 的状态机:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      state.partial = output if state.partial is None else state.partial + output
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 满 block_units 后才归档
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      state.blocks.append(state.partial)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      state.partial = None  # 归档后 partial 清空,开始新块

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      b_n 是求和塌缩——一旦块写满(units_in_block >= block_units),这个块的表示就定型了,后续 layer 不会再修改它。这跟 KV cache 的"append-only"性质完全一样:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      特性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Block 表示 bnb**n

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      KV cache 的 K/V

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      何时定型

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      块写满时

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      token 写入时

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      后续是否修改

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      否(只读)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      否(只读)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      内存生命周期

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      整个 forward/backward

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      整个 decode session

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      所以可以缓存:rank 1 在第 1 个虚拟 stage 把 [b_0, b_1] 发给 rank 2,rank 2 处理完存下来;第 2 个虚拟 stage 时 rank 1 又产生新的 [b_2],只需发 +[b_2],rank 2 把它和本地缓存的 [b_0, b_1] 拼起来就是完整历史 [b_0, b_1, b_2]。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ③ 新阶段会产生什么?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      每个新虚拟 stage 会产生 ∼P/N_p 个新块表示(P=物理 stage 数,N_p=平均每 stage 的块数)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      用论文 Figure 3 的例子(P=4, V=2):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Virtual Stage 0(无缓存):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Rank 0 产生 [b_0]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Rank 1 收到 [b_0],产生 [b_1]      → 发给 Rank 2: [b_0, b_1]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Rank 2 收到 [b_0, b_1],产生 [b_2]  → 发给 Rank 3: [b_0, b_1, b_2]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Rank 3 收到 [b_0, b_1, b_2],产生 [b_3]


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Virtual Stage 1(有缓存):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Rank 0 已有 [b_0],产生新的 [b_0']  → 发给 Rank 1: +[b_0']
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Rank 1 已有 [b_0, b_1],收到 +[b_0'],产生 [b_1'] 
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               → 发给 Rank 2: +[b_0', b_1']   (只发增量!)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Rank 2 已有 [b_0, b_1, b_2],收到 +[b_0', b_1'],产生 [b_2']
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               → 发给 Rank 3: +[b_0', b_1', b_2']

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        关键差别:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Naïve(无缓存):每次发完整历史 [b_0, b_1, b_2, ...],通信量随 stage 数平方增长

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Cached:只发增量+[b_new],通信量随 stage 数线性增长

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        论文 Eq. 7→8 给出量化:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Naïve:Commnaı¨ve=C(C−1)2NpdCommnaı¨ve=2C(C−1)Npd

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Cached:Commcached=P(P−1)2Npd+(V−1)P2NpdCommcached=2P(P−1)Npd+(V−1)P2Npd

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        当 V=2、P=4 时,消除 6 次冗余传输(论文原话)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        回到 AttnResState:缓存的工程映射

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnResState.blocks 就是 Cross-stage Caching 的本地缓存:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          @dataclass
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          class AttnResState:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              blocks: list[Tensor]      # ★ 这就是 cache:已归档的块表示
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              partial: Tensor | None    # ★ 正在累计的(还没定型,不能缓存)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              units_in_block: int       # 进度计数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • blocks:跨 stage 缓存的对象(只读、可复用)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • partial:当前 stage 正在产生的增量(未定型,必须传输)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          pipeline 边界的传输就是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # 发送方:把当前 stage 新产生的 blocks 发给下一个 rank
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            new_blocks = state.blocks[len(receiver_cached_blocks):]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            send(new_blocks)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # 接收方:把新块追加到本地缓存
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            state.blocks.extend(new_blocks)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            partial 永远不跨 stage 传输——它必须在当前 stage 内完成塌缩成 blocks 才能进入缓存。这就是"为什么 partial 不能缓存":它还在变,不是只读的。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            一句话总结

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            答案

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            缓存什么

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            已归档的 Block 表示 b_n(AttnResState.blocks)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            为什么能缓存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            块一旦写满就只读不变(求和塌缩的 append-only 性质)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            新阶段产生什么

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ∼P/N_p 个增量块+[b_new],只发增量不重发历史

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Cross-stage Caching 的精确含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            缓存的不是"AttnResState 的一部分",而是"blocks 列表的前缀"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Rank 1 在第 1 个虚拟 stage 结束后,把自己的 blocks=[b0, b1] 发给 Rank 2。Rank 2 存进自己的 state.blocks。第 2 个虚拟 stage 时,Rank 1 又产生新的 b2,只发 +[b2],Rank 2 把它 append 到自己的 state.blocks。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            所以:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • blocks物理上分布在多个 rank 的内存里(每个 rank 一份副本)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 但逻辑上它们是同一个列表的不同前缀

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Cross-stage caching 就是避免重复发送已经共享的前缀

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            一句话总结

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            答案

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            缓存的是 AttnResState 的一部分?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            不准确。缓存的是**blocks 列表的前缀**(跨 rank 共享的已归档块)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttnResState 是分布式的?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            不是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            。每个 rank 有自己的独立实例

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            系统中应该只有一个 AttnResState?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            单机是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ,pipeline 下每个 rank 一个

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            blocks 遍布在每个 stage?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            是的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ,但内容递增——每个 rank 的 blocks 包含上游所有块 + 自己新产生的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.8.4 讨论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            为什么 activation recomputation 被影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标准 activation checkpointing 可以丢掉中间激活,反向时从 checkpoint 重算。但 Full AttnRes 要让后续很多层继续访问旧层输出;如果丢掉它们,后续层无法直接算深度注意力,或者必须频繁重算历史输出。于是它把"可释放的中间态"变成"跨多层被读取的 KV-like 源"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Block AttnRes 的妥协是只保存每个块的聚合表示和当前块 partial prefix。这样 activation checkpointing 仍可丢掉 softmax 中间量和大量块内细节,保留少量块级 bank。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            为什么 pipeline parallelism 变贵

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            普通 PP stage 边界只传 hidden_states 和常规 residual。AttnRes 需要下游 stage 也能看到历史块,所以边界还要传 block bank。若 Full AttnRes 传每层历史,成本随层数涨;Block AttnRes 传块表示,成本随块数涨。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            cross-stage caching: 同一物理 stage 在交错流水线的不同 virtual stage 会重复看到部分历史块,因此可缓存已见块,只传新增块,减少冗余通信。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.8.5 推理:两阶段计算(Algorithm 1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            问题:Block AttnRes 的逐层注意计算类似自回归解码——块表示是被所有层共享复用的"KV cache"。naïve 实现每层都要全扫一遍所有前置块 → O(L·N) 内存访问。关键洞察:伪查询 w_l 与前向计算解耦(是学习参数),所以一个块内的所有 S 个 query 可以批量成一个矩阵乘,把 S 次读摊销成 1 次。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Algorithm 1 两阶段:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Phase 1(跨块,并行):对块 n 的所有 S 层 query [w_l]_{l∈B_n} 一次性对块表示 [b_0..b_{n-1}] 算注意,返回输出 + softmax 统计(max 和 log-sum-exp)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              块 n 的 S 个 query {w_l} 在执行前全部已知,所以前面 (n-1)S 个 key-value 对只需从 HBM 读一次,被 S 个 query 复用:Read_inter(n) = 2(n-1)S·d # 因子 2 = key+value Read_inter = Σ_n 2(n-1)S·d = 2Sd·N(N-1)/2 = dL(N-1) Write_inter = L·d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Phase 2(块内,顺序):逐层用不断演化的 partial sum 算块内注意,然后通过 online softmax 与 Phase 1 输出合并(m_l = max(m^(1), m^(2)),h_l = (e^{m1-m}·o1 + e^{m2-m}·o2) / (e^{m1-m}·l1 + e^{m2-m}·l2))。因为 online-softmax 合并是逐元素操作,Phase 2 可自然与周边算子 kernel 融合,进一步降 I/O。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              块内第 t 层(1≤t≤S)依赖前面 t-1 个块内 key-value:Read_intra(n) = Σ_{t=1}^S 2(t-1)d = S(S-1)d Write_intra = S·d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 总摊销 I/O(除以 L):Read per layer = dL(N-1)/L + N·S(S-1)d/L = (N-1)d + (S-1)d = (S+N-2)d Write per layer = 2d Total I/O = (S+N)d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              结论:批量跨块读把 Full AttnRes 的每层 I/O 从 O(L) 降到 O(S+N)。典型值 L=128, N=8, S=16 → Full = 24d(对比 Block 的 (N/S+5)d=5.5d,Table 1)。Block 形式进一步把存储的表示数从 L 降到 N(每块压成一个向量),故 I/O 更低。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            推理两阶段的直觉读法:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1. 批量计算当前 block 中多层 query 对历史 blocks 的注意力统计。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2. 层内顺序处理当前 partial prefix,并用 online softmax 合并历史块统计。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            核心收益:历史块只读一次或少数几次,避免每层重复扫完整 bank;online softmax 只维护 max、denominator、weighted sum,不必物化大矩阵。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            结果(Table 1):典型参数 L=128, N=8, S=16, m=4:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            方案

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Read

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Write

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Total I/O

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标准残差

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            3d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            mHC(m 流)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            —

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            —

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            34d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttnRes Full(两阶段)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            —

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            —

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            (S+N)d = 24d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttnRes Block(两阶段)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            —

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            —

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            (N/S+5)d = 5.5d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            注:Full 形式用两阶段调度也可从 O(Ld) 摊薄到 (S+N)d(见附录 C),只是块数 N 远大于 Block。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.8.6 推理:内存高效 Prefill(sequence sharding)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            问题:prefill 阶段存块表示需 N·T·d 元素——128K token 序列、8 块时高达 15 GB。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            方案:把块表示沿序列维 shard 到 P 个 tensor-parallel 设备(每设备 N·(T/P)·d)。Phase 1 在本地序列分片上独立执行;Phase 2 的 online-softmax 合并融入标准 TP all-reduce 通信路径(output reduce-scatter → 本地合并 → all-gather 重建),并可自然与 RMSNorm 等 kernel 融合。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            效果:每设备内存从 15 GB 降到 ~1.9 GB(128K/8 块/P=8);配合 chunked prefill(如 16K chunk)进一步降到 <0.3 GB/设备。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.8.7 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • a) 反对:这套基础设施(缓存 + 两阶段 + sharding)本身复杂度高,对小模型/单卡无意义。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • b) 失败假设:假设 PP 是大规模训练标配、块表示必须跨 stage 传。若未来互联带宽暴涨,Full AttnRes 的 O(Ld) 通信也可行(论文明确说这是 Full 形式的潜在未来)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • c) 胜出条件:大规模 PP 训练 + 长上下文推理;失败:单卡教育/小模型。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • d) 更稳做法:不做优化,Block AttnRes 直接朴素实现(本项目采用)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • e) 受损方:基础设施工程师(复杂度)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            完成度:本项目的朴素实现未包含跨 stage 缓存/两阶段/序列分片(与 kimi3-master 一致);本文档记录论文方案作参考。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.9 学到的深度注意模式(论文 §5.4.2,Fig. 8)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            论文可视化 16 层模型(Table 2 436M 行)在 Full 与 Block (N=8) 形式下学到的权重 α_{i→l}(Pre-Attn 与 Pre-MLP 分开展示)。三个关键观察:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1. 保留局部性(Preserved locality):每层主要注意直接前驱(对角占优),但出现选择性的非对角集中——如 layer 4 注意早期源、layers 15-16 在 Block 设置下回溯远处 → 超出标准残差路径的学到的 skip connections。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2. 层级专门化(Layer specialization):embedding h_1 全程保留非平凡权重,尤其 Pre-Attn 层(深度维 attention sink,对应 §6.2 与序列维 attention sink 同源);Pre-MLP 输入的 diag 依赖更锐利(读最近表示),Pre-Attn 输入的感受野更广(attention 跨层路由信息,MLP 局部工作)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            3. Block 保留结构:对角占优、embedding 持续、层级专门化都从 Full 转移到 Block → 块级压缩充当隐式正则,同时保留关键信息通路。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            教学价值:本项目的 attention_weights()(attn_res.py)正是为此设计的分析窗口——可复现论文 Fig. 8 的"哪一层读了哪个源"。实验 demo 已演示学到权重收敛到 embedding 源(见 0x07)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            完成度:论文实验(Fig. 8),本项目可复现(attention_weights() + demo),但未做 16 层模型级可视化。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.10 统一视角:残差连接作为结构化矩阵(论文 §6.2,Table 5)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            深度混合矩阵 M:把残差变体统一表示为 h_l = Σ_{i=0}^{l-1} M_{i→l} v_i(v_0=h_1,v_i=f_i(h_i))。M 是 R^{L×L} 下三角矩阵,M_{i→l} 是层 l 给层 i 输出的权重。各变体的区别在:权重如何产生(fixed / learned / input-dependent)+ M 是否受低秩约束。semiseparable rank 是统一比较的标尺。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            论文 Table 5(更新机制分类):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            paper-tab-5
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            paper-tab-5

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            结构化矩阵视角(Fig. 9,L=4 示例,Block S=2):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            paper-fig-9
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            paper-fig-9
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 标准残差:M = 全 1 下三角矩阵。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Highway:M_{0→l}=γ_{1→l}、M_{i→l}=g_{i+1}·γ_{i+1→l}(γ_{i→l}=Π_{j=i+1}^l (1-g_j) 是 carry product)。因累积积因子化通过标量门,M 是 1-semiseparable(与标准残差同 rank,但 input-dependent)。权重自动和为 1 → Highway 是 softmax-free 的深度维 stick-breaking attention。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • (m)HC:M_{i→l}=β^T_i A_{i+1→l} α_l(A_{i→j}=Π_{k=i+1}^j A_k)。m×m 转移使 M 是 m-semiseparable。mHC 进一步要求每个 A_l 双随机,稳定跨深度累积积。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Full AttnRes:M_{i→l}=α_{i→l} 经 φ(w_l,k_i)=exp(w_l^T RMSNorm(k_i)) 归一化 → 稠密 rank-L。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Block AttnRes:已完成块 B_n 内所有源 i 共享块级 key/value b_n → M_{i→l}=α_{n→l} ∀i∈B_n;当前块内每层额外注意演化 partial sum b_n^{i-1} → 每块内多一个额外源。有效 rank 介于 N 和 N+S 之间,在标准残差(N=1)与 Full(N=L)之间插值。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            两个分析洞察(论文 §6.2):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1. 深度维 attention sink:input-dependent 的 M 揭示某些层无论输入如何都持续吸引高权重(2.10 的 embedding 持续),与序列维 attention sink 同源。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2. φ 可分解性 → 递推塌缩:当 φ(q,k)=φ(q)^T φ(k) 可分解时,深度注意塌缩成递推——正是 MRLA↔GLA、DDL↔DeltaNet 对应的结构根源;不可分解的 softmax 核让 AttnRes 保持稠密可检索。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.10.1 与序列-深度对偶(论文 §6.1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            论文把深度递推与序列递推形式化对齐:TTT 把每个递推步视为对自监督 loss 的梯度下降 W_t = W_{t-1} - η∇ℓ(W_{t-1}; x_t),f 线性时退化为线性注意 S_t = S_{t-1} + k_t v_t^T;标准残差沿深度方向有同样加性形式(h_l 是状态,每层 f_l 是一个"梯度步")。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            跨尺度的对应关系(论文指出):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 序列维 data-dependent gates(RetNet, GLA)↔ 深度维 Highway

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • delta rule ↔ DDL

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • MRLA ↔ GLA(gated linear attention)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 线性注意 S_t = S_{t-1} + k_t v_t^T ↔ 标准残差 h_l = h_{l-1} + f_{l-1}(h_{l-1})

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            这些方法都停留在递推范式内。AttnRes 更进一步:用直接跨层注意替换深度递推——正如 Transformer 用 self-attention 替换时间递推。论文明确:"Since the number of layers in current architectures remains well within the practical regime of softmax attention, we adopt vanilla depth-wise attention",并把"更高效(线性复杂度)替代"列为 future work。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.11 最优架构分析(论文 §5.4.1,Fig. 7)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            问题:AttnRes 是否改变最优的 depth-width-attention 权衡?尤其——既然它在深度维度上有优势,是否偏好更深的模型?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            方法:固定计算预算(FLOPs ≈ 6.5×10^19)和激活参数量(≈ 2.3×10^8),枚举 5×5 网格:d_model/L_b ∈ {15,30,45,60,75} × H/L_b ∈ {0.3,0.4,0.5,0.6,0.7}(L_b=L/2 为 Transformer 块数,H 为注意力头数)。固定每专家 MLP 扩展比 d_ff/d_model ≈ 0.45,隔离纯架构影响。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            paper-fig-7
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            paper-fig-7

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            结果(Fig. 7):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 两方法共享大趋势:loss 随 d_model/L_b 增大、H/L_b 减小而下降,都在 H/L_b≈0.3 达优。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • AttnRes 在全部 25 个配置上低于 baseline,优势 0.019~0.063。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 最优位置移动:baseline 在 d_model/L_b≈60(loss 1.847)达优;AttnRes 移到 d_model/L_b≈45(loss 1.802)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            推论:固定参数预算下,更小的 d_model/L_b = 更深更窄的网络 → AttnRes 能更有效利用额外深度。但论文明确警示:这不是部署推荐(更深模型推理延迟更高),而是揭示"AttnRes 在哪里收益最大"的诊断,可作为选架构时与推理成本一起权衡的因子。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            完成度:论文实验(Fig. 7),本项目未复现(CPU 无法枚举 25 配置)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            TransFormer-封面
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            TransFormer-封面


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • [1] Kimi Team. Attention Residuals(技术报告), arXiv:2602.15031, 2026. 仓库:https://github.com/MoonshotAI/Attention-Residuals

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • [2] Kimi Team. Kimi K3 Technical Report §2.2(Eqs. 8-10 与 8 块×12 层=9 源配置), arXiv:2607.24653.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • [3] Zhenda Xie et al. mHC: Manifold-Constrained Hyper-Connections, arXiv:2512.24880.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • [4] Yongyi Yang & Jianyang Gao. mHC-lite: You Don't Need 20 Sinkhorn-Knopp Iterations, arXiv:2601.05732.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • [5] Yu Zhang et al. Kimi Linear: An Expressive, Efficient Attention Architecture, arXiv:2510.26692.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 参考实现(两阶段):kimi-k3-pytorch-main/src/attention_residuals/

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 参考实现(fused kernel / 生产推理):sglang-main、vllm-main 中的 K3 AttnRes 相关文件

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            阅读原文

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            跳转微信打开

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            •  

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            【轻量化复刻大模型 / KIMI K3】Attention Residuals 完整梳理(1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            原创 罗西的思考 2026-11-10 21:36 北京

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 0x00 概要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 0.1 脉络

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 0.2 论文信息

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 0.3 关键图/表索引

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 0.4 注意说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 0x01 先懂 AttnRes:残差为什么是瓶颈

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 1.1 标准残差的展开

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 1.2 PreNorm 稀释与信息瓶颈

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 1.3 一句话痛点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 1.4 思路:把治疗时间维度的药,用在深度维度上

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 1.5 一句话直觉

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 0x02 演进脉络与定位

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 2.1 前身:标准残差连接及其痛点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 2.2 同期竞品:都是"残差路由"的玩家

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 2.3 深度信息流的五派方案

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 2.4 论文的关键消融结论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 2.5 一个常见的理解误区

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 2.6 定位一句话

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 0x03 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 3.1 直觉类比视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 3.2 准专业水平视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 3.3 专家视角(信息论 / 优化 / 计算复杂性)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 3.4 AttnRes 的数学机制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 3.5 伪代码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 3.6 真实代码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 3.7 伪代码 vs 本项目实现对照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 3.8 如何使用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 0x04 生产级实现与源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 4.1 SGLang 实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 4.2 vLLM 实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 4.3 源码伪代码总览(基于 SGLang/vLLM 共同语义)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 4.4 与 Kimi K3 架构的协同

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 0xFF 参考


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            0x00 概要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            一句话定位:标准残差是"深度维度的等权加法";AttnRes 把深度维的聚合换成"深度维的 softmax 注意力"——每层用一个可学习的伪查询向量(pseudo-query)去"注意"之前的各层输出,权重由内容和深度共同决定。这是对 RNN→Transformer 那场范式跨越在深度轴上的完整复刻。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            0.1 脉络

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标准 PreNorm Transformer 的残差流像“所有旧信息都以 1 倍权重倒进同一个桶”:层数越深,桶越大,新层信号越像一滴水。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Attention Residual (AttnRes)把这件事改成“当前层先问:我现在更需要哪些历史层/历史块?”再用 softmax 概率加权取一个混合表示,因此深度方向的信息流从固定累加变成了可学习的选择。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Block AttnRes 是工程化版本:不保存每一层输出,而是每若干层形成一个块表示,再在“历史块 + 当前块部分和”上做深度方向注意力。它牺牲块内分辨率,换来训练、推理和流水线并行可落地。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            0.2 论文信息

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            项

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            值

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Attention Residuals(TECHNICAL REPORT OF ATTENTION RESIDUALS)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            作者

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Kimi Team

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            机构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Moonshot AI(月之暗面 / Kimi)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            类型

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            技术报告(Technical Report,非会议论文)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            代码仓库

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            https://github.com/MoonshotAI/Attention-Residuals

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            0.3 关键图/表索引

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttenRes-overview
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttenRes-overview

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            以下是论文的关键图/表索引

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            编号

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            内容

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Figure 1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            三种残差结构总览((a)标准 / (b)Full / (c)Block)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Figure 2

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Block AttnRes 的 PyTorch 伪代码(block_attn_res + forward)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Figure 3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Cache-based pipeline 通信示例(P=4, V=2)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Figure 4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Scaling law 曲线(Baseline/Full/Block 三线拟合)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Figure 5

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            训练动态:(a)验证 loss (b)每块输出幅值 (c)每块梯度幅值

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Figure 6

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Block size S 对验证 loss 的影响(16 层模型)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Figure 7

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            固定算力架构扫描热图(d_model/L_b × H/L_b)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Figure 8

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            学到的深度注意力权重 α 分布(Full 上 / Block 下)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Figure 9

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            四种残差变体的深度混合矩阵 M

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Table 1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            每 token 每层的记忆访问成本(残差机制 I/O)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Table 2

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Scaling law 模型配置与验证 loss(5 规模)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Table 3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            48B 模型下游任务对比(Baseline vs AttnRes)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Table 4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            16 层模型消融实验

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Table 5

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            残差更新机制统一视角(Weight/Source 分类)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Algorithm 1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            两阶段计算(Phase 1 跨块并行 + Phase 2 块内顺序 + online softmax)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Appendix B

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Full AttnRes 优化推理 I/O 的完整推导

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            0.4 注意说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            0x01 先懂 AttnRes:残差为什么是瓶颈

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            现代 Transformer 几乎每一层都在用同一句话结束:x = x + F(x)。这句话叫 残差连接(residual connection),它在 2015 年(ResNet)就被证明能训很深的网络,2017 年被 Transformer 拿走。我们经常忘了它其实有一个很深的缺陷。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1.1 标准残差的展开

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标准残差可写为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            展开后近似是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            大白话:每一层看到的都是全部先前信息的"无差别大杂烩"——所有早期层的输出被 固定的单位权重 1 加在一起。最后一层拿到的不是"最近一层的干净结论",而是从 embedding 到所有层输出的总和。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1.2 PreNorm 稀释与信息瓶颈

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            论文 §2.1 明确指出,标准残差带来三个问题:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1. 无选择性访问(no selective access):不同类型的层(attention vs MLP)拿到同一个聚合状态,尽管它们可能从不同的加权方式中获益。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2. 不可逆损失(irreversible loss):聚合中丢失的信息,无法在更深层被选择性地找回。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            3. 输出增长(output growth):为了让自己的输出在累积残差里更有影响力,后面的层被迫学出越来越大的输出,这会破坏训练稳定。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            PreNorm 会把每层模块的输入归一化,所以每层新产生的残差增量常常有相近尺度。若这些增量方向大体独立,平方范数会随层数近似线性增长,L2 范数约随 增长;若方向更同向,增长可更接近。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            这不等于模型一定发散,但意味着一个固定尺度的新特征进入一个越来越大的残差流后,相对占比会下降——这就是深层网络的信息稀释:残差连接保护了梯度不消失,却没有给前向信息流提供选择机制。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1.3 一句话痛点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            残差连接把「历史上所有计算结果」压成一个"和"(深度方向的瓶颈),并且没有给网络"决定读哪一层"的能力。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1.4 思路:把治疗时间维度的药,用在深度维度上

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            我们回想序列建模领域有一个著名的"换药事件":RNN 把整段历史压缩进一个隐状态(h_t),这是"时间维度的瓶颈";Transformer 把它替换成 attention over time——每个位置可以选择性地读取所有过去位置,权重由内容决定(data-dependent weights)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttnRes 说:模型深度其实和序列时间是一模一样的困境。 残差连接把历史的计算压成一个状态(h_l),是无法选择的、等量的。那为什么不用同样的药?——把 attention 用在深度上:让第 l 层也把前面所有层当作一个"序列",用 softmax 注意力去挑选它真正想读的早期层。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1.5 一句话直觉

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标准 PreNorm Transformer 的残差流像"所有旧信息都以 1 倍权重倒进同一个桶":层数越深,桶越大,新层信号越像一滴水。Attention Residual (AttnRes) 把这件事改成"当前层先问:我现在更需要哪些历史层/历史块?"再用 softmax 概率加权取一个混合表示,因此深度方向的信息流从固定累加变成了可学习的选择。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Block AttnRes 是工程化版本:不保存每一层输出,而是每若干层形成一个块表示,再在"历史块 + 当前块部分和"上做深度方向注意力。它牺牲块内分辨率,换来训练、推理和流水线并行可落地。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            0x02 演进脉络与定位

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.1 前身:标准残差连接及其痛点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 前代方案:Pre-Residual(x = x + F(x)),2015 年 ResNet 提出、Transformer 沿用至今。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 缺陷:固定等权相加 → 深度稀释、hidden 范数随深度 O(L) 无界增长(PreNorm dilution)、无法按需选择性读取早期层。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              标准残差可写为:展,开后近似是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            大白话:最后一层拿到的不是“最近一层的干净结论”,而是从 embedding 到所有层输出的总和;每个历史项默认权重都是 1。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 论文证据:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 图 5(b):Baseline 的每块输出幅值随深度单调爬升(PreNorm 稀释的直接可视化);Block AttnRes 则呈现有界周期性模式(在块边界被重置)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 图 5(c):Baseline 的最浅层梯度幅值异常大(残差权重全为 1,无法调控跨深度梯度流);Block AttnRes 的梯度分布明显更均匀。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • Scaling law(图 4):Baseline 的 loss 曲线始终高于 AttnRes。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 论文引用「深层被裁剪掉一部分损失很小」作为"早期信息被埋没、无法选择找回"的旁证。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            training_dynamics
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            training_dynamics
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttenRes-loss
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttenRes-loss

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.2 同期竞品:都是"残差路由"的玩家

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            论文 Table 5 把所有残差变体分成三大类(单状态递推 / 多状态递推 / 跨层访问)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Comparison of residual update mechanisms
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Comparison of residual update mechanisms

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            以下按"权重来源 × 源访问范围"组织:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            方案

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            核心机制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            权重来源

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            可访问源

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            优势

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            劣势

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标准残差x + F(x)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            固定单位权重

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            仅 h_{l-1}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            简单、稳定、已被验证

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            无选择性;逐层稀释

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ReZero

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            每层可学习标量 λ_l

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            静态标量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            仅 h_{l-1}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            极简、深层稳定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            无选择性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            LayerScalediag(λ)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             逐通道缩放

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            静态对角向量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            仅 h_{l-1}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            稳定性好

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            无选择性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Highway(1-g)·x + g·F(x)输入相关

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标量门

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            仅 h_{l-1}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            输入相关

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            单状态;深度维 1-semiseparable

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            SiameseNorm

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            双流 PreNorm/PostNorm 共享参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            固定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2 条流

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            保恒等梯度 + 有界表示

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            缓解而非选择

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            mHC

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            m 条并行残差流 + 学习混合矩阵

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            输入相关

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            (动态)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            m 条流

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            状态扩张 rank↑、稳定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            I/O 高(~34d/层);仍是线性注意

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            DenseFormer

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            各层访问所有先前输出,加权求和

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            静态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标量系数(不随输入)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            [h_1..h_{l-1}]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            跨层访问

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            权重与输入无关(消融证实无收益)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            MRLA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            逐层 sigmoid 门控(可分离 QK 点积)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            输入相关

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            [h_1..h_{l-1}]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            跨层访问

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            更接近 linear attention 而非 softmax

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttnRes(Full/Block)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            深度维 softmax 注意力

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            输入相关

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            (softmax)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            [h_1..f_{l-1}]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             / [b_0..b_{n-1}]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            选择性最强;显式深度检索

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Full 内存 O(Ld);Block 块内压缩

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.3 深度信息流的五派方案

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            从更宏观的视角,可以把深度维度上的信息处理思路分成几大学派:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            (1) 稳定化/缩放派代表思路:PostNorm、PreNorm、残差缩放、ReZero、DeepNorm、LayerScale 等。它们主要调节信号幅度、初始化或梯度稳定性。优点是改动轻、系统友好;缺点是信息路径仍近似一条递推链,历史选择能力有限。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            (2) 门控递推派Highway、LSTM/GRU 类思想在深度方向的对应物,是为残差通道加门。可以把 Highway 视作一种不显式 softmax 的 stick‑breaking 式深度注意力:权重可以依赖输入,但仍沿递推传播。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            (3) 多状态流派mHC、MRLA、DDL 等方法维护多个并行状态或线性注意力式状态。它们把"单管道"拓宽成多管道,降低压缩瓶颈。局限是仍然更像递推系统:信息要经过状态转移,不是每层都直接访问任意历史层。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            (4) 跨层访问派DenseNet、ELMo、DenseFormer、MUDDFormer 等允许跨层组合。静态权重方法缺少输入依赖;部分动态方法更像线性注意力。AttnRes 的位置是:在深度轴上使用 softmax attention,使跨层访问既密集又竞争。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            (5) 结构化矩阵视角也可把第 l 层输入看成历史输出的加权和: $ x_l=\sum_{j<l}m_{\{l,j\}}y_j $<="" p="">

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 标准残差:M 是全 1 下三角矩阵。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Highway:M 由门控连乘产生,低秩但输入依赖。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • mHC:M 有多条状态流,半可分秩约为 m。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Full AttnRes:M 可接近稠密,按内容动态产生。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Block AttnRes:M 介于标准残差和 Full AttnRes 之间,块内共享粗粒度源。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.4 论文的关键消融结论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • DenseFormer(静态权重)1.767 ≈ baseline 1.766 → "可学习但静态"不够,必须输入相关。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 换成 input-independent 可学习标量混合 1.749 > Full 1.737 → 再次证明输入相关性是增益来源。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • mHC(动态)1.747 介于 DenseFormer 与 AttnRes 之间 → 动态但仍是线性注意;AttnRes 用软注意跨层选择性检索再进一步。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttenRes-table-4
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttenRes-table-4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.5 一个常见的理解误区

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            过去一些解读把 mHC 的权重描述为"可学习矩阵 + 正交约束",甚至直接说它"与输入无关"。这与论文 Table 5 不符——**mHC 是 Dynamic(输入相关)**的:其更新规则 H_l = H_{l-1}A_l + f_{l-1}(H_{l-1}α_{l-1})β^T_{l-1} 中,有效权重 M_{i→l}=β^T_i A_{i+1→l} α_l 含输入相关项(α、β 都依赖 H_{l-1},而 H_{l-1} 由之前的输入决定)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            paper-tab-5
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            paper-tab-5

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttnRes 与 mHC 的真正区别不在"是否输入相关",而在:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1. 注意力范式:mHC 是深度维 linear attention(m-semiseparable,低秩);AttnRes 是深度维 softmax attention(稠密 rank-L)——softmax 的竞争性归一化(probability mass 在源间竞争)带来更锐利的选择。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2. 状态形态:mHC 把历史压进固定 m 条流(RNN 式有限状态);AttnRes 保留块表示列表(可跨层检索)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            论文 Table 4 中 AttnRes(1.737/1.746)优于 mHC(1.747)的原因就是:softmax 的竞争性归一化 + 跨层直接检索。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.6 定位一句话

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            不同于 mHC 的"多流矩阵状态 + m-semiseparable 线性注意"、也不同于 DenseFormer 的固定系数加权,本方案(AttnRes)通过逐层可学习伪查询向量 + 深度维 softmax 注意力,让每一层内容相关地选择性读取所有先前层输出——把"深度维度的 linear attention"升级为"深度维度的 softmax attention",完成与序列维度"linear → softmax"相同的范式跨越。(论文核心观点 §6.2:把 HC/mHC 等统一看成"深度维的 linear attention",AttnRes 是深度维 softmax attention 的第一个实例,即"深度-时间对偶性"。)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            0x03 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            3.1 直觉类比视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            想象一个大学课堂上,讲台上正在讲一个很长的证明。标准残差连接就像老师每讲完一步,就把"之前所有内容的摘要"工工整整地写在同一张白纸上——越往后,白纸越乱,每一行旧字都被新字盖得几乎看不见(稀释),而且老师从不回头重读某一页(无选择)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            AttnRes 的做法是:把之前每一步的推导分别存成独立的小卡片(不是糊成一团的总和),第 l 步讲话之前,老师快速"扫一眼"所有卡片,用注意力加权挑出跟当前最相关的几张(例如上一步、以及最初的嵌入),按权重拼成这一讲的讲义。既不会稀释,又能精准引用早先的结果。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Block AttnRes 则是"每讲完一个知识块就把块里的卡片合并成一张总卡",只留 N 张总卡在桌上——白板没那么乱了,代价是块内的细致区分被牺牲。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            一句话:标准残差是"一张黑板的累积字迹",AttnRes 是"卡片目录上的检索注意力"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            3.2 准专业水平视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            输入输出的 shape 与含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            设 h_l ∈ R^{B×T×d} 为第 l 层(attention 或 MLP,论文把每个 self-attention 或 MLP 视为一个独立 layer)的输入(B:batch, T:序列长度, d:hidden dim)。本文全程使用 h_1 表示 token embedding(下标从 1 开始,与论文一致)。f_l 是第 l 层的变换函数。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标准做法的公式



                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              h_l = h_{l-1} + f_{l-1}(h_{l-1})          (PreNorm: x + F(x))

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              展开后它是等权累加:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                h_l = h_1 + Σ_{i=1}^{l-1} f_i(h_i)        # 每个累加项的权重都是固定 1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                AttnRes 的做法(论文 Eq. 2-4,即 Full 形式)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                第 l 层拥有一个逐层可学习伪查询向量q_l = w_l ∈ R^d。keys 与 values 取同样的东西——所有之前层的输出(以及 token embedding):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  k_i = v_i = { h_1                  if i = 0            ← 嵌入永远是一个 source
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                f_i(h_i)             if 1 ≤ i ≤ l-1 }    ← 第 i 层的输出


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  注意力权重:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  α_{i→l} = φ(q_l, k_i) / Σ_j φ(q_l, k_j)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  φ(q, k) = exp(q^T · RMSNorm(k))          # 核函数


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  h_l = Σ_i α_{i→l} · v_i                   # 加权和,而非单位加
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • α 是非负、且随 l 变化的 softmax 分布(对每一 l,Σ_i α_{i→l} = 1)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • RMSNorm 的作用:防止某个出口量级巨大的层靠"嗓门大"(大范数)垄断权重——归一化后每层方向等比同步,φ 只表达方向相似度、不表达量级。论文消融证实「去掉 RMSNorm 会掉点」(Full 1.743 vs 1.737,Block 1.750 vs 1.746)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • h_l 与标准残差的关键差别:标准残差的 h_l 是逐层累加的既有量 + 一位新贡献;AttnRes 的 h_l本身就是一次关于历史层的混合——它是"从历史中选出来的加权组合",而不是"上一个状态再加点什么"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  公式级对比表

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  标准残差

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  AttnRes(Eq. 2-4)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  输入

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  只用 h_{l-1}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  所有历史:h_1 到 f_{l-1}(h_{l-1})

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  权重

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  固定单位 1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  内容相关的 softmax α_{i→l}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  语义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  等权累加 Σ v_i

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  加权和 Σ α·v

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  选择性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  无

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  有(不同 task 学不同读取)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  参数开销

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  每层一个 w_l ∈ R^d

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  记忆

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  O(d)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Full:O(Ld)(保留所有历史层输出)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3.3 专家视角(信息论 / 优化 / 计算复杂性)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  为什么它理论上有用(深度-时间对偶)。论文提出一个统一视角:把「深度维的聚合」类比「时间维的递推」,把残差本身看成"深度维度的 linear attention":

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 标准残差 = 权重矩阵为全 1 的下三角(M_{i→l}=1),即"fixed uniform linear attention over depth"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • Highway = 标量门 g,权重可因子化成 M_{i→l} = γ_{i+1→l}·g_{i+1}(γ_{i→l} = Π_{j=i+1}^l (1-g_j)),1-semiseparable(秩 1),是 softmax-free 的 stick-breaking attention。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • (m)HC / mHC = m 个平行流 + 学习的段间转移矩阵 A,展开即 M_{i→l} = β^T_i A_{i+1→l} α_l,m-semiseparable,相当于"深度维的、具有 m 维状态(state expansion,RNN 状态从 d 扩到 d×m)的 linear attention"。mHC 进一步要求每个 A_l双随机(doubly stochastic),使跨深度的累积积稳定(Sinkhorn-Knopp 投影到 Birkhoff 多胞体)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • AttnRes = 深度维度的 softmax(dense rank-L)attention:M_{i→l} = α_{i→l} 由 input-dependent softmax 定义,矩阵稠密。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  也就是说:序列建模走了 "linear attention(RNN)→ softmax attention(Transformer)",而深度建模在 AttnRes 里完成了同一个过渡——把"深度维 linear attention"(residual/Highway/mHC)升级为"深度维 softmax attention"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  信息论视角:等权残差是"信息最差情况下的融合"(平均);softmax 让每层有选择地提取与任务最相关的深度表示,降低"单层输出的熵"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  下图是三个残差实现的对比图。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  AttnRes-vs-mHC-vs-Residual
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  AttnRes-vs-mHC-vs-Residual

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  论文尺度证据(ablation,Table 4,16 层模型)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  变体

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Loss

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  相对 Full 说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Baseline (PreNorm)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.766

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  参照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  DenseFormer

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.767

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  静态权重跨层,无增益

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  mHC

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.747

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  动态但线性注意

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Full AttnRes1.737

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  最优

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Block (S=4)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.746

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  接近 Full

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  SWA (W=1+8)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.764

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  只保留最近 8 层,远不如 Block

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  w/ input-dependent query

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.731

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  理论更优但参数/顺序访存代价

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  w/ input-independent mixing

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.749

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  去掉输入相关性掉点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  w/ sigmoid

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.741

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  无竞争性归一化,掉点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  w/o RMSNorm

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.743

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  RMSNorm 必要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  w/ multihead (H=16)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.752

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  多头反而有害

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  关键解读:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 输入依赖是杠杆点:DenseFormer(固定权重)看不到任何收益,证明 gain 来自 input-dependent 而非"多读一层"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • softmax vs sigmoid:softmax 的竞争性归一化(probability mass 在源间竞争)比 sigmoid 更锐利——用 sigmoid 掉点(1.741)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 多头有害(1.752 > 1.746):深度混合在各通道上基本均匀,多头引入冗余。论文解释:"当一层输出相关时,它是整体相关的"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • RMSNorm 必要:Full 去掉掉到 1.743、Block 掉到 1.750。对 Block 更关键,因为块表示跨更多层累积,量级差异更大。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • SWA 反直觉发现:只读最近 W=8 层(+embedding)远不如 Block(1.764 vs 1.746)——说明"选择性访问远层"比"访问很多近层"更重要。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 缩放曲线(图 4):Baseline L=1.891·C^-0.057,Block AttnRes 1.870·C^-0.058,Full 1.865·C^-0.057——斜率一致但截距更低,在整个算力区间持续拉开差距。按 5.6 PFLOP-s-days,Block AttnRes 达 1.692 vs baseline 1.714,等价 1.25× compute advantage。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  未解决 / 待探索的理论问题(论文 §6.1-6.2 明确列出的 future work):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 既然序列建模又被 linear attention(Mamba、GLA、DeltaNet 等)挑战,深度维度是否也有对应的"更高效 linear-complexity 深度注意"?论文明确说"incorporating more expressive yet memory-efficient (e.g. linear-complexity) alternatives is a natural direction"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • φ 可分解性揭示的规律(§6.2):当 φ(q,k)=φ(q)^T φ(k) 可分解时,深度注意会塌缩成递推——这正是 MRLA↔GLA、DDL↔DeltaNet 对应的结构根源。反过来,不可分解的 softmax 核是 AttnRes 保持"稠密可检索"的原因。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • Block size / N 与学到权重的交互(跨规模的实证尚未系统化)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 论文明确:"Attention sinks in depth" 与序列维 attention sink 同源(§6.2),但尚无理论刻画。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3.4 AttnRes 的数学机制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  从“求和”改成“期望”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  AttnRes 的目标不是把所有历史信号相加,而是在历史源集合  上形成概率分布:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  其中 是历史层或历史块表示, 是当前层对第 个源的打分。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  伪查询、RMSNorm 与 score

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  文章强调一种关键工程选择:查询向量可以是每层的可学习参数,而不必由当前 hidden state 动态投影得到。这样做的收益是:查询与当前前向值解耦,允许把一个 block 中多层对历史块的查询批处理,降低反复读历史 bank 的 I/O。常见 score 形式可简化为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  RMSNorm 的作用不是改变 value,而是让 score 不被某个天然范数更大的历史块垄断。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Full AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Full AttnRes 让每层直接看所有前面层输出:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  优势是跨深度检索最细;缺点是每层都要保留、访问、跨 stage 传递更多历史层输出。文章指出,深度  相比序列长度小,所以算术量本身不吓人,真正痛点是激活保存、重计算失效和流水线通信。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Block AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Block AttnRes 把层分成块。每个块内部仍维护局部前缀和;跨块只保存一个块表示。对某块内层而言,候选源约为:。其中  是已完成块的表示, 是当前块内前若干层的部分和。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  直观讲:跨楼层查档案时,不看每一页原始记录,而看每个文件夹的摘要;当前文件夹还没封档时,看当前草稿。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3.5 伪代码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  AttenRes-伪代码
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  AttenRes-伪代码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3.6 真实代码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    r"""Block Attention Residuals (paper section 2.2, Eqs. 8-10).


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    A standard residual stream compresses everything a network has computed into one
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    vector per position and hands it to the next layer -- a depth-wise bottleneck
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    directly analogous to the hidden state of an RNN over time.  Attention Residuals
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    apply the transformer's own fix to depth: layer ``l`` *attends* over the outputs
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    of all preceding layers instead of accumulating them uniformly.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    【中文释义】本模块实现了 Attention Residuals 的核心逻辑(论文 §2.2,Eqs. 8-10)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    它把「深度方向」看得与「时间方向」同构:标准残差流把网络算过的一切压缩成一个
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    逐位置的向量交给下一层——即"深度维的瓶颈",无差异、不可选择。AttnRes 的办法
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    是把 attention 迁移到深度维:第 ``l`` 层用逐层可学习的伪查询向量去**注意**之前
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    所有层的输出,而不是等权相加。从深度维的 linear attention(mHC)升级成
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    「深度维的 softmax attention」,是本实现的核心立意。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        q_l  = w_l                                  learned pseudo-query, per layer
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        k_i  = v_i = f_i(h_i),   k_0 = v_0 = h_1    the embedding is always a source
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        phi(q, k) = exp(q^T RMSNorm(k))             RMSNorm stops a layer with large
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        alpha_{i->l} = phi(q_l, k_i) / sum_j phi     outputs from dominating
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        h_l  = sum_i alpha_{i->l} v_i               Eq. 9


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Note what this replaces: ``h_l`` is the mixture itself, not "previous state plus
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    something".  Uniform accumulation is one particular setting of ``alpha``.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    The full form costs ``O(L^2 d)`` arithmetic -- affordable at ``L < 100`` -- but
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ``O(Ld)`` memory, which is not, once every layer output must stay resident across
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    pipeline stages.  The block form fixes that: partition ``L`` layers into ``N``
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    blocks, reduce each block to a single summed representation ``b_n``, and attend
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    over block representations plus the running partial sum of the current block.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Memory drops from ``O(Ld)`` to ``O(Nd)``.  For K3, ``N = 8`` blocks of 12 layers
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    (the last partial), giving 9 sources once the embedding is counted.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    【中文释义】数学结构:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    - 伪查询:``q_l = w_l``(每层一个可学习向量);key = value = 各层输出,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      且 embedding ``h_1`` 永远是第一个源(source)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    - 打分核:``phi(q,k) = exp(q^T RMSNorm(k))``,RMSNorm 防止某层输出幅值过大
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      垄断权重。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    - 混合:``h_l = sum_i alpha_{i->l} v_i``(Eq. 9),注意它不是"上一状态 + 新增",
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      而是**每次都用一次加权混合重新从历史中"选出"当前输入**——均匀累加只是
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ``alpha`` 的一个退化设置。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    复杂度权衡:完整(Full)形式算术 ``O(L^2 d)``(``L < 100`` 时可负担)但内存
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ``O(Ld)``——一旦每层输出都要在 pipeline stage 间常驻内存,就无法接受。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    块(Block)形式解决问题:把 ``L`` 层切成 ``N`` 块,每块塌缩成单个求和表示
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     ``b_n``,注意力只发生在"块表示 + 当前块的 running partial"上,内存降到
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     ``O(Nd)``。对 K3:``N = 8`` 块、每块 12 层(末块保留 partial),算上 embedding
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    共 9 个 source。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    @dataclass
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    class AttnResState:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        """Sources visible to the next sublayer.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ``blocks[0]`` is the token embedding (``b_0 = h_1``), followed by one entry per
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        completed block.  ``partial`` is the running sum inside the current block.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        【中文释义】跨层传播的状态机。当模型逐子层前向时,这个对象才是最真实的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        "深度历史":
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        - ``blocks``:已归档(完成)的块表示列表,``blocks[0]`` 恒为 token embedding
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (``b_0 = h_1``),其后每项是一个完成了的块塌缩表示;
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        - ``partial``:当前块内"正在累计"的运行和(running sum),一旦块写满就
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          并入 ``blocks`` 并清空;
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        - ``units_in_block``:当前块已经累计了多少个子层单位。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ``sources()`` 负责把"可读的历史"组装成深度注意力所见的 key/value 列表。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        blocks: list[Tensor] = field(default_factory=list)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        partial: Tensor | None = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        units_in_block: int = 0


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def sources(self) -> list[Tensor]:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """Return every source the next sublayer can attend over.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            已完成的块 + (若存在)当前块的运行 partial。只有一个块(即只含
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            embedding,尚未产出任何层输出)时就直接返回 ``blocks``。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return self.blocks if self.partial is None else [*self.blocks, self.partial]


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def detach(self) -> "AttnResState":
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """Detach a deep copy; used where gradients must not flow through history."""
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return AttnResState(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                blocks=[b.detach() for b in self.blocks],
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                partial=None if self.partial is None else self.partial.detach(),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                units_in_block=self.units_in_block,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            )



                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    class AttentionResiduals(nn.Module):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        """Owns the per-unit pseudo-queries and the block bookkeeping.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ``n_units`` counts the addressing units: sublayers when
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ``granularity="sublayer"`` (Figure 2 draws a residual arrow per module), or
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        decoder layers otherwise.  ``block_units`` is the block size measured in the
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        same unit.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        【中文释义】这是 AttnRes 的完整实现。它只管理两件事:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        1. 每子层(unit)一个可学习伪查询 ``w_l``,以及 key 归一化用的 RMSNorm
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           weight —— 即 S1 打分核;
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        2. Block 的台账逻辑(init_state/mix/add_output/finalize),即源列表如何
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           演进(S3/S4)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ``n_units`` 是"可寻址单位"数:granularity="sublayer" 时按子层计(论文
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Figure 2 每模块画一条残差箭头);否则按 decoder 层计。``block_units`` 是
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        以相同单位计的块大小。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def __init__(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            self,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            dim: int,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            n_units: int,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            block_units: int,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            *,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            eps: float = 1e-6,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            full: bool = False,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Args:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                dim: hidden size(隐藏维度,``d``)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                n_units: 可寻址的单位数(sublayer 数量)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                block_units: 块大小,以 unit(sublayer)为单位计。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                eps: RMSNorm 的 epsilon。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                full: 若为 True,则等价于 Full 形式(测试用 oracle)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            【中文释义】参数初始化:``queries`` 形状为 ``(n_units + 1, dim)``——每个
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            unit 一个伪查询,**多出的一个**供 ``finalize`` 时在所有块表示上做最终聚合;
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ``key_norm_weight`` 是 RMSNorm 的逐维缩放权重。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            super().__init__()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            self.dim = dim
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            self.n_units = n_units
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            self.block_units = block_units
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            self.eps = eps
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            self.full = full
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # One learned pseudo-query per unit, plus one extra for the final
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # aggregation over all block representations.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # 每个 unit 分配一个可学习的伪查询,外加一个给 finalize 的最终聚合项。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            self.queries = nn.Parameter(torch.zeros(n_units + 1, dim))
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            self.key_norm_weight = nn.Parameter(torch.ones(dim))


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def init_state(self, embedding: Tensor) -> AttnResState:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """``b_0 = h_1``: the token embedding is always an available source."""
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # 【中文释义】状态初始化:block 0 固定为 token embedding,保证 embedding
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # 永远是第一个可读源;partial 为空、计数为 0。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return AttnResState(blocks=[embedding], partial=None, units_in_block=0)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def mix(self, state: AttnResState, unit_idx: int) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """Eq. 9 -- the representation handed to unit ``unit_idx``.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            【中文释义】深度维 softmax 注意的核心算子(对应论文 Eq. 9):把当前可读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            源列表(``state.sources()``)叠成一个张量,其 key 统一过 RMSNorm,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            用本 unit 的伪查询 ``self.queries[unit_idx]`` 打分得到 ``alpha``(softmax
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            归一化),最后加权求和解组成交给该 unit 的表示 ``h_l``。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            当只有 embedding 一个源时直接返回(避免无谓的 einsum/softmax)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            shape 说明:source 叠成 ``(n, b, t, d)``,scores 为 ``(n, b, t)``,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            softmax 沿源维 ``n`` 归一化,输出回 ``(b, t, d)``。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            sources = state.sources()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            if len(sources) == 1:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                return sources[0]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            stacked = torch.stack(sources, dim=0)                     # (n, b, t, d)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            keys = rms_norm(stacked, self.key_norm_weight, self.eps)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            query = self.queries[unit_idx]                            # (d,)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            scores = torch.einsum("nbtd,d->nbt", keys, query)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            weights = torch.softmax(scores.float(), dim=0).to(stacked.dtype)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return torch.einsum("nbt,nbtd->btd", weights, stacked)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def add_output(self, state: AttnResState, output: Tensor) -> AttnResState:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """Fold a unit's output into the current block's partial sum, rolling the
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            block over when it is full.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            【中文释义】接收一个子层的输出 ``output``,把它累加进当前块的运行和:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1. ``partial`` = 已累计的输出之和(从 ``None`` 起);
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2. ``units_in_block`` 计数 +1;
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            3. 一旦达到 ``block_units``,就把这个 partial 打成包归档进 ``blocks``,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               并清空 partial/count,开始下一个块。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            这就是"块塌缩"发生的时刻——也是内存从 O(Ld) 降到 O(Nd) 的关键步骤。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            state.partial = output if state.partial is None else state.partial + output
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            state.units_in_block += 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            if state.units_in_block >= self.block_units:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                state.blocks.append(state.partial)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                state.partial = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                state.units_in_block = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return state


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def finalize(self, state: AttnResState) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """Aggregate every block representation for the output layer.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            【中文释义】整个模型走完所有子层后调用:若尾巴还有个未满的 partial,先
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            把它也并入 ``blocks``,然后用第 ``n_units`` 个伪查询(final 聚合项)在
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            所有块表示上再调一次 ``mix``,产出最终输出层看到的表示。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            if state.partial is not None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                state.blocks.append(state.partial)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                state.partial = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                state.units_in_block = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return self.mix(state, self.n_units)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def attention_weights(self, state: AttnResState, unit_idx: int) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """Expose ``alpha`` for analysis: which depths a unit actually reads.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            【中文释义】只算打分核而**不**做加权混合,返回形状 ``(n, b, t)`` 的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ``alpha`` 分布——用于分析/可视化:这个 unit 在深度维上到底读了哪些源、
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            权重多大。这是教学与调试(观察"选择性读取")的窗口。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            sources = state.sources()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            stacked = torch.stack(sources, dim=0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            keys = rms_norm(stacked, self.key_norm_weight, self.eps)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            scores = torch.einsum("nbtd,d->nbt", keys, self.queries[unit_idx])
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return torch.softmax(scores.float(), dim=0)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def extra_repr(self) -> str:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return (
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                f"dim={self.dim}, units={self.n_units}, block_units={self.block_units}, "
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                f"full={self.full}"
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            )



                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    class FullAttentionResiduals(AttentionResiduals):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        """The unblocked ``O(L^2 d)`` form of Eqs. 8-9, used as a test oracle.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Every unit output is kept as its own source, so ``block_units = 1`` recovers
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        this behaviour from the block implementation -- which is exactly the
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        equivalence the test suite asserts.


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        【中文释义】Full 形式(Eqs. 8-9,``O(L^2 d)`` 算术)——每个子层输出都保留为
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        独立 source,不做块塌缩。实现上仅靠 ``block_units=1`` 即可从 Block 实现
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        复原(每收到一个输出立即归档成"块"),因此本类主要作为**测试 oracle**:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        测试套件断言两者逐位等价。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def __init__(self, dim: int, n_units: int, *, eps: float = 1e-6):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            super().__init__(dim, n_units, block_units=1, eps=eps, full=True)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    3.7 伪代码 vs 本项目实现对照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    论文 Fig.2 元素

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    本项目实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    对应位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    block_attn_res(blocks, partial_block, proj, norm)AttentionResiduals.mix(state, unit_idx)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    attn_res.py 的 mix() 方法

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    V = torch.stack(blocks + [partial_block])stacked = torch.stack(state.sources(), dim=0)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    attn_res.py 的 torch.stack 行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    K = norm(V)keys = rms_norm(stacked, ...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    attn_res.py 的 rms_norm 调用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    logits = einsum('d,n b t d->n b t', proj.weight.squeeze(), K)scores = einsum('nbtd,d->nbt', keys, query)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    attn_res.py 的 einsum 行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    h = einsum('n b t,n b t d->b t d', softmax, V)return einsum('nbt,nbtd->btd', weights, stacked)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    attn_res.py 的加权求和 einsum

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    partial_block = hidden_states

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    (块初态)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    init_state(embedding)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     → blocks=[embedding]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    attn_res.py 的 init_state()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    if layer_number % (block_size//2) == 0: blocks.append(partial_block)add_output

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    :units_in_block >= block_units 时归档

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    attn_res.py 的 add_output()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    双 block_attn_res(attn 前 + MLP 前)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    每 block 两次 mix(model.py 集成)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    model.py 的 Kimi3Model.forward

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    proj.weight

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     / norm(每 unit 独立投影+norm)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    self.queries[unit_idx]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     / self.key_norm_weight

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    attn_res.py 的 queries 与 key_norm_weight

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    实现差异说明:论文伪代码把投影矩阵 proj(query 生成)与 norm 作为每个 unit 的属性传入;本项目等价地用 self.queries((n_units+1, d) 参数矩阵,按 unit_idx 取行)+ 共享 key_norm_weight。数学上 proj.weight.squeeze()(一行)= self.queries[unit_idx],完全等价。块边界判断的差异源于论文按 decoder 层计(block_size//2 因为每层 ATTN+MLP 两个 block_attn_res 调用),本项目按 sublayer/unit 直接计。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    3.8 如何使用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    在 Kimi3Model 中,给出了使用示例。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      class Kimi3Model(nn.Module):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          """K3 剔除 lm_head 的完整主杆:embedding + 全部 block + 最后 norm。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          额外管理一个可选的 AttentionResiduals 模块(跨层的深度方向注意力)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          AttnRes 启用时,每个 block 被**调用两次**(block 内前半个单元 da 次),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          AttnRes 在其间插入"层间混合"(brand-residual mix)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def __init__(self, config: Kimi3Config):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              super().__init__()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self.config = config
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self.tok_embed = nn.Embedding(config.model.vocab_size, config.model.dim)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              # 每层交替:偶数层 KDA(use_kda=True),奇数层 MLA(use_kda=False)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              # 这决定了 init_caches 返回的列表 K/ML 交替出现。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self.blocks = nn.ModuleList([
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Kimi3Block(config, i, use_kda=(i % 2 == 0))
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  for i in range(config.model.n_layers)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ])
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              if config.model.attn_res.enabled:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # 启用 AttentionResiduals:n_units = 2*n_layers(每 block 两个
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # unit:attn+ffn),block_size 决定多少个 unit 共享一个残差状态。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  n_units = config.model.n_layers * 2
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  block_units = config.model.attn_res.block_size
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self.attn_res = AttentionResiduals(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      config.model.dim, n_units, block_units,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      full=config.model.attn_res.full,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  )
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self._attn_res_state = None  # 前向过程中暂存的 AttnRes 状态缓存
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              else:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self.attn_res = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self.norm = RMSNorm(config.model.dim, config.model.norm_eps)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def forward(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              tokens: Tensor,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              doc_ids: Optional[Tensor] = None,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              caches: Optional[list] = None,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """完整模型前向。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ``caches`` 应与 ``self.blocks`` 等长(每 block 一个 cache)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              解码时与服务端相同:传一个 token,返回一层 logits,内部自动调用
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              cache 完成增量前向。训练时一次性给整段 tokens,cache 每层重新
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              复算或者用 cache 减少重复计算。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              h = self.tok_embed(tokens)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              reset_mask, attn_mask = doc_masks(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  doc_ids, tokens.shape[1], tokens.device
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              )


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              if self.attn_res is not None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # ---- 带 AttnRes 的路 =========================================
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self._attn_res_state = self.attn_res.init_state(h)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  unit_idx = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  for i, block in enumerate(self.blocks):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      cache = caches[i] if caches is not None else None  # 每 block 一个 cache
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 每个 block 被调度两次,中间混入一次 AttnRes 深度混合:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      #   mix -> attn -> add_output -> mix -> ffn -> add_output
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      h = self.attn_res.mix(self._attn_res_state, unit_idx)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      h = block(h, cache=cache, reset_mask=reset_mask, attn_mask=attn_mask)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self._attn_res_state = self.attn_res.add_output(self._attn_res_state, h)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      unit_idx += 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      h = self.attn_res.mix(self._attn_res_state, unit_idx)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      h = block(h, cache=cache, reset_mask=reset_mask, attn_mask=attn_mask)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self._attn_res_state = self.attn_res.add_output(self._attn_res_state, h)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      unit_idx += 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  h = self.attn_res.finalize(self._attn_res_state)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              else:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # 不带 AttnRes:每个 block 只调用一次。cache 也是"每 block 一个"。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  for i, block in enumerate(self.blocks):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      cache = caches[i] if caches is not None else None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      h = block(h, cache=cache, reset_mask=reset_mask, attn_mask=attn_mask)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              return self.norm(h)   # 最后一层 RMSNorm,喂给 lm_head


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      子知识点的详解将在下一篇完成。



                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      0x04 生产级实现与源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      以下为直接源码证据;「Infra 含义」为基于源码数据流的解读。本节把 SGLang 与 vLLM 两个推理框架的 AttnRes 实现合并到一张综合索引表中,避免同一份信息重复展示。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      4.1 SGLang 实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      4.1.1 Python 层:sglang-main/python/sglang/srt/layers/attn_residual.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      这是 SGLang 中 AttnRes 的核心运行时层。文件注释明确声明:此文件实现 Kimi‑K3 Attention Residual —— snapshot bank + aggregation;流程为 score rows → softmax → weighted sum → RMSNorm,并按硬件分发 fast/hip/fused 多条路径。dispatch(score→softmax→mix→norm)。SGLang 把 AttnRes 做成独立 runtime primitive。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      证据项

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      直接源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      简化逻辑

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Infra 含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      TMA fast gate

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 36‑50

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      _supports_attn_res_tma()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       要求 major >= 10 且不是 12; _use_fast() 还要求 hidden_size == 7168。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      if SM100-like and H=7168: use fast

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      NVIDIA 快路径高度绑定 K3 形状与新硬件。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      score 权重缓存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 66‑83

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      get_cw()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       缓存 norm.weight * proj.weight.squeeze(), 分别支持 bf16/fp32。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      cw = RMSNormWeight ⊙ queryWeight

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      把 RMSNorm scale 与投影预乘,减少每次聚合开销。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      TMA fast 调用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 86‑117

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      _aggregate_fast()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       创建 out, 调用 attn_res_fused_tma(prefix_sum, bank, cw, out_norm.weight, out, nvb, eps, write_prefix=...)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      out = fused_tma(prefix, bank, cw, out_norm, nvb)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      fast path 把 score、online softmax、加权和、输出 RMS 融进 bank write 融合。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Triton score kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 120‑155

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      _score_kernel()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       对每个 token 和 source row 扫 hidden 维,算 sumsq 与 dot, 输出 dot * rsqrt(mean_square + eps)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      score[j]=dot(v_j,cw)/rms(v_j)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      score 实际就是归一化后的源向量与伪查询的内积。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Triton combine kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 157‑207

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      _combine_kernel()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       对 scores 做 softmax, 再对 bank rows 与 prefix row 加权求和。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      p=softmax(scores); out=sum_j p_j*v_j

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      深度方向 softmax 在 source 维,而非序列维。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      NPU fallback

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 209‑230

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      _mix_fused()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       在 is_npu() 时导入 sgl_kernel_npu.kimi_k3.attn_residual.mix_fused。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      if NPU: external mix_fused(...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      SGLang 预留 NPU kernel 入口,但实现来自外部包。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      两段 Triton fallback

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 231‑280

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      _mix_fused()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       / _aggregate_fused() 先 _score_kernel 再 _combine_kernel; _aggregate_fused() 再接 out_norm(...)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      scores = score(); mixed = combine(); norm(mixed)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      fallback 牺牲一次中间 scores 读写,换跨硬件可用。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ROCm single kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 283‑315

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      _aggregate_hip()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       调用 attn_res_hip(), 可折叠 pending add; bank snapshot、output RMSNorm。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      hip(prefix, addend, bank, cw, out, write)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ROCm 避免两 kernel 和重复 HBM 读取。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      调度入口

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 400‑440

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      _aggregate()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       空 token 直接返回;fast 优先,其次 HIP,最后 Triton fused。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      fast → hip → triton

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      同一 API 下硬件选择最优路径。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      bank 生命周期

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 443‑465

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      AttnResidual.__init__()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       分配 [T, block_num, H], 若来自上个 PP rank,则拷贝已有 block_residual。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      bank=new_empty; copy(old)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      bank 是跨层/跨 PP 的状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      block 写入

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 467‑475

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      write()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       把 prefix_sum 写入 bank[num_valid_blocks, :], 然后计数加一;SP 时只写本地 rows。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      bank[nvb]=prefix; nvb++

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      block boundary snapshot。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      聚合 API

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 477‑539

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      forward()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       处理 nvb==0、pending add、fast/hip fused write、fallback write。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      prefix = hidden or prefix+delta; aggregate; maybe write

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      同一个函数服务 pre‑attn、pre‑MLP、输出侧聚合。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      SP all‑gather 融合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 541‑576

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      forward_sp_all_gather()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       本地聚合后调用 k3_sp_collective.attn_res_all_gather(),可写 bank。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      local aggregate + multicast AG

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      SP 场景下先 gather 的冗余。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      SP reduce‑scatter 融合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      行 578‑608

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      forward_sp_reduce_scatter()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       调用 k3_sp_collective.reduce_scatter_attn_res()。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      o_proj RS + prefix add + attn_res

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      把 attention 输出通信与 AttnRes 聚合合并。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      伪代码(基于该文件抽象):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        class AttnResidual:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            bank = empty(tokens, num_blocks, hidden)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            nvb = inherited_rows
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            def forward(hidden, prefix, proj, score_norm, out_norm, write=False):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                if nvb == 0:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    if write: bank[nvb] = hidden; nvb += 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    return out_norm(hidden), hidden
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                prefix = hidden if prefix is None else prefix + hidden
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                scores = dot(score_norm([bank[:nvb], prefix]), proj_weight)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                probs = softmax(scores, dim='source')
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                mixed = sum(probs * [bank[:nvb], prefix])
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                if write: bank[nvb] = prefix; nvb += 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                return out_norm(mixed), prefix

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.1.2 模型集成:sglang-main/python/sglang/srt/models/kimi_k3.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        证据项

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        直接源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        简化逻辑

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Infra 含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        KDA/MLA 选择

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2129‑2151

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        config.is_kda_layer(layer_idx)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         选 KimiK3DeltaAttention, 否则选 KimiK3MLAAttention。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        layer = KDA if listed else MLA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnRes 包在 KDA/MLA 层外围,和混合注意力共存。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnRes 参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2181‑2204

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        若 config.attn_res_block_size 非空,创建 self_attention_res_norm/proj 与 mlp_res_norm/proj。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        each layer has two q/norm pairs

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        pre‑attn 与 pre‑MLP 各有独立深度聚合。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        forward 分流

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2345‑2367

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        forward()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         检查 attn_res is not None 后转入 _forward_attn_residual()。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        if enabled: attnres path else standard path

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        标准残差路径仍保留。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        聚合 1: attention 侧

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2388‑2444

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        _forward_attn_residual()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         先用 self_attention_res_* 调 attn_res.forward(); block write layer 同调用写入 bank; 写后 prefix_sum=None。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        x = AttnRes(prefix, bank); if boundary: bank.write(prefix)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        attention 的深度聚合后的输入。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        attention 后通信

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2450‑2503

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        SP‑MoE 优先 forward_sp_reduce_scatter(); 否则可走 k3_ar_fusion.all_reduce(hidden_states, prefix_sum)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        finish o_proj reduce, maybe fold residual

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnRes 与 TP/SP 通信路径交织,不是纯算子替换。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        聚合 2: MLP 侧

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2504‑2519

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        未被 SP 融合时,使用 mlp_res_* 再次 attn_res.forward(), 然后 MLP 消费 prefix_sum。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        x = AttnRes(after attn, bank); y = MLP(x, prefix_sum)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        每个 Transformer block 内 attention 前和 MLP 前都可重路由残差信息。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        模型级 bank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2640‑2648

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        若开启 AttnRes,计算 attn_res_block_num, 构造 AttnResidual(hidden_states, block_num, block_residual=residual) 并清空标准 residual。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        residual becomes block bank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        PP 入口的 residual 语义变为块 bank。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        SP AttnRes 开关

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2650‑2659

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        sp_attn_res

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         要求 AttnRes、SGLANG_K3_SP_ATTN_RES、无 PP、无 dspark capture 且 collective enabled。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        enable local shared carry only in safe mode

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        源码限制了融合路径适用场景。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        PP stage 输出

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2685‑2695

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        非最后 PP rank 若有 AttnRes,会物化 delayed add, 并把 attn_res.block_residual 放进 'PPProxyTensors' 的 residual。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        send hidden_states + bank to next stage

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        pipeline 边界确实要携带 bank。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        最终输出聚合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2697‑2729

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        最后一段使用 output_attn_res_proj/norm 调 attn_res.forward()。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        final = AttnRes(prefix, bank, output q/norm)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        输出侧也按 AttnRes 混合,而非简单 hidden + residual。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        aux capture

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 2740‑2767

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        _dspark_capture_stream()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         对下游 consumer 的权重调用 aggregate_stream(), 输出 pre‑norm mixture。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        capture re what next consumer reads

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        辅助隐藏态要匹配 AttnRes 语义,不能直接拿 prefix。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        post‑load warm cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 3078‑3092

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        post_load_weights()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         预热 get_cw() 的 bf16/fp32 缓存。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        precompute cw before cuda graph

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        避免 lazy multiply 被捕获进 CUDA graph replay。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.1.3 SP 集合通信融合:sglang-main/python/sglang/srt/layers/k3_sp_collective.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        证据项

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        直接源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        简化逻辑

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Infra 含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        初始化条件

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 54‑119

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        _init_state()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         要求 SM103、TP4/TP8、MegaMoE/DeepEP、CustomAllReduceV2 multicast;可由 SGLANG_K3_SP_COLLECTIVE 控制。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        if hardware/topology ok: register comm

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        SP 集合通信融合只在验证过的拓扑上启用。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        对称 buffer

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 126‑132

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        _symm_buffer()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         使用 k3_ar_fusion.symm_buffer 创建命名持久对称缓冲。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        named symmetric storage

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        为 NVLS/direct multicast 保持跨 rank 地址一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        reduce‑scatter + AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 300‑360

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        reduce_scatter_attn_res()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         检查 SGLANG_K3_SP_ATTN_RES、形状、bank/cw/ow 后调用 attn_res.attn_res_fused_pull_rs()。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        pull RS → local add → aggregate → norm

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        把通信和深度聚合成一个局部 shard 输出。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        all‑gather + AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 413‑469

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        attn_res_all_gather()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         本地聚合并将规范化向量 multicast 到全输出。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        local aggregate → direct AG

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        避免完整 token 张量先聚合再通信。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        相关配置:sglang-main/python/sglang/srt/environ.py 行 1476‑1492 定义 SGLANG_K3_AR_FUSION、SGLANG_K3_SP_COLLECTIVE、SGLANG_K3_SP_ATTN_RES、SGLANG_K3_GEMM_AR。其中注释明确说 SP AttnRes 在 consecutive SP‑MoE 层间保持 token‑shared residual stream,下一次 AttnRes 聚合和 bank write 在本地 shard 上运行,然后只 all‑gather 归一化后的 attention 输入。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        配置入口:sglang-main/python/sglang/srt/configs/kimi_linear.py 行 45‑55 接收 attn_res_block_size, 行 109 保存到配置;行 117‑120 校验 linear_attn_config 的 KDA/full attention 层表,行 156‑168 提供 is_kda_layer()、linear_layer_ids、full_attention_layer_ids。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.1.4 SGLang Kernel 层(TMA + HIP)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        attn_res.py(kernels 目录下):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • _jit_fused_tma_module() 行 30‑61:JIT 编译 SM100 TMA kernel wrappers。NVIDIA fast path 来自 CUDA JIT。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • _TMA_BEST_CONFIG / _tuning() 行 64‑97:按 nvb 选择 chunk/occupancy/registers。针对 bank rows 调参。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • attn_res_fused_tma() 行 153‑190:TMA kernel 做 score、online softmax、combine、RMSNorm、可选 write。GB200/GB300 类 fast aggregation。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • attn_res_fused_direct_ag() 行 226‑260:本地聚合后 direct multicast all‑gather。聚合与 AG 合并。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • attn_res_fused_pull_rs() 行 263‑300:pull reduce‑scatter、local residual add、TMA aggregation。聚合与 RS 合并。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        attn_res_hip.py(ROCm 路径):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • supports_attn_res_hip() 行 26‑34:用 register tile budget 判断 ROCm 是否可走单 kernel。ROCm 快路径受寄存器容量限制。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • _agg_kernel() 行 37‑133:一个 CTA/token 内完成 score、softmax、mix、norm、write。ROCm 用 register tile 复用 bank。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • attn_res_hip() 行 136‑212:Python wrapper 检查 nvb/shape 并 launch kernel。ROCm single kernel 入口。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.2 vLLM 实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.2.1 NVIDIA 模型路径:vllm-main/vllm/models/kimi_k3/nvidia/model.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        证据项

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        直接源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        简化逻辑

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Infra 含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        operator 导入

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 100‑109

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        从 vllm.models.kimi_k3.nvidia.ops 导入 attn_res。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        attn_res = nvidia op wrapper

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        NVIDIA 路径使用专门 op,而非普通 PyTorch 拼装。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        层级配置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 971‑996

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        attn_res_block_size

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         非空则设置 is_block_write_layer、block_write_idx、prev_valid_blocks, 并创建两套 norm/proj。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        block_idx = layer_idx // S

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        与论文 Block AttnRes 的块边界一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        pre‑attn 聚合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 1016‑1045

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        _pre_attn_norm()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         在 AttnRes 开启时调用 attn_res(prefix_sum, hidden_states, residual, self_attention_res_norm.weight, self_attention_res_proj.weight, input_layernorm.weight, ...)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        x = op(prefix, delta, bank, q/norm, out‑norm)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        把 pending delta、bank 写入和输入 RMSNorm 合成一个 op。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        post‑attn 聚合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 1047‑1078

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        _post_attn_norm()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         在 block write layer attention 输出重启 prefix,否则作为 delta;随后用 mlp_res_* 调 attn_res()。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        if boundary: prefix=attn_out else delta=attn_out

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        块内 partial prefix 由 attention/MLP 输出共同演化。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        模型级 bank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 1350‑1361

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        forward 开启 AttnRes 时分配 block_residual = new_empty(T, num_blocks, H), 继承 PP residual 后把 prefix_sum=hidden_states, hidden_states=None。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        residual slot becomes block bank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vLLM 和 SGLang 一样改写 residual 语义。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        PP 边界

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 1388‑1396

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        非最后 PP rank 返回 IntermediateTensors(hidden_states=hidden_states, 'residual': residual), 若有 prefix 则先加回。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        send current hidden + block bank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        PP 必须传 AttnRes bank。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        最终聚合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 1398‑1411

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        最后 rank 调 attn_res() 使用 output_attn_res_norm/proj, block_write_idx=-1。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        final = output‑side depth mix

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        输出不是标准 residual 加法。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        sequence parallel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 1332‑1408

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        SP 时先 sp‑shard, 层内 attention 需要 all‑gather, 末尾并 all‑gather。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        shard tokens, gather when needed

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vLLM NVIDIA 支持 AttnRes 与 SP 的显式编排,但代码断言 SP 不支持 PP 同时开启。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        aux hidden state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 1230‑1247、1249‑1307

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        _set_aux_hidden_state_layers()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         记录 mode; _capture_aux_hidden_stream() 可在 VLLM_KIMI_K3_AUX_ATTN_RES_STREAM 开启时输出 pre‑norm AttnRes mixture,否则 prefix‑only。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        aux = prefix or attnres‑stream

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        speculative/drafter 需要知道拿到的是哪种语义的 hidden。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        final norm 位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 1430‑1434

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        注释称 final norm 在 compute_logits 中做,以便 MTP draft model 收到 pre‑norm hidden。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        return pre‑norm hidden

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnRes 输出还要配合 vLLM 的 logits/MTP 生命周期。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.2.2 NVIDIA operator:vllm-main/vllm/models/kimi_k3/nvidia/ops/attn_res.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        证据项

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        直接源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        简化逻辑

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Infra 含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        warmup profiles

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 18‑31

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        get_attn_res_triton_warmup_profiles()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         生成不同 num_blocks/has_delta/block_write/apply_norm 组合。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        profiles = common decode/prefill paths

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        warmup 覆盖 fallback Triton 编译形态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Triton kernel 参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 34‑59

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        attn_res_triton()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         接收 prefix、delta、blocks、norm_weight、qk_weight、output_norm_weight、num_blocks、block_write_idx。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        one kernel for add/write/mix/norm

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        op 直接表达 Block AttnRes 数据面。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        prefix + delta

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 67‑85

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        若 HAS_DELTA, 加载 delta 加到 prefix,并写回 prefix。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        prefix += delta; store prefix

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        delayed residual add 在 kernel 内物化。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        block write

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 86‑94

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        WRITE_BLOCK

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         时把 updated‑prefix 写入 blocks[:, block_write_idx, :]。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        blocks[write_idx] = prefix

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        块边界 snapshot 同内核。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        source softmax

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 95‑148

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        num_blocks==0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         时 softmax 退化为 prefix;否则遍历 num_blocks+1 源,RMSNorm score, online softmax 累加 mixed。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        mixed = online_softmax(bank rows + prefix)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        使用 online softmax 避免物化大 attention 矩阵。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        output norm

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 154‑167

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        若 APPLY_OUTPUT_NORM, 对 mixed 做 RMSNorm。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        out = norm(mixed)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        与 pre‑attn/pre‑MLP 的 LayerNorm/RMSNorm 是 epilogue 融合。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        native vs Triton

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        行 170‑248

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        attn_res()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         在 H=7168、有 delta、有输出 norm、num_blocks>0、非 block write、SM100 且 _C.kimi_k3_attn_res 存在时走 native;否则走 Triton。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        if native‑eligible: C++/CUDA, else triton

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        常见 decode 路径走 C++/CUDA,边界 / 最终输出走 Triton。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        C++/CUDA 路径

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vllm-custom-ops.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 2850‑2874 包装 torch.ops._C.kimi_k3_attn_res; csrc/libtorch_stable/ops.h 行 409‑418 声明在 VLLM_ENABLE_KIMI_K3_ATTN_RES 下编译;csrc/libtorch_stable/kimi_k3_attn_res_kernel.cu 行 916‑1006 检查 SM100、dense row stride,并按 num_blocks: 1..8 专门化 launch。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        native kernel 限制清楚。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.2.3 AMD operator: vllm-main/vllm/models/kimi_k3/amd/linear.py 与 amd/ops/attn_res.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        证据项

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        直接源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        简化逻辑

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Infra 含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AMD op 导入

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        amd/linear.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 60‑66

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        导入 vllm.models.kimi_k3.amd.ops.attn_res.attn_res。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        use ROCm Triton op

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AMD 路径不走 NVIDIA native op。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        wrapper

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        amd/linear.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 140‑162

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        _apply_attn_res()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         把 RMSNorm.weight、proj.weight.squeeze()、可选 output_norm 传给 attn_res()。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        op(prefix, delta, bank, norm_w, q_w, out‑norm_w)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Python 层保持和 NVIDIA 的调用语义。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        层级配置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        amd/linear.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 555‑579

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        设置 use_attn_residuals、block write、valid blocks,并创建 pre‑attn/pre‑MLP norm/proj。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        same block schedule

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AMD 模型层支持同一 Block AttnRes 结构。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        forward_attn_residual

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        amd/linear.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 619‑662

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        先 pre‑attn _apply_attn_res, block 边界清 prefix; attention 后 pre‑MLP _apply_attn_res, MLP 后更新 prefix_sum 并返回。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        pre‑attn mix → attn → pre‑MLP mix → mlp → prefix

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AMD 推理链路,便于验证输出。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        模型 bank/PP

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        amd/linear.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 810‑850

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        创建 block_residual, 继承 PP residual, 循环层;非最后 PP rank 返回 hidden/bank;最后 _apply_attn_res 输出聚合。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        bank crosses PP as residual

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        PP 通信语义与 NVIDIA/SGLang 一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AMD Triton kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        amd/ops/attn_res.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 16‑137

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        kernel 处理 prefix+delta、block write、source softmax、output norm。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        single Triton on kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ROCm 路径用 Triton 直接覆盖全部核心逻辑。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AMD op wrapper

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        amd/ops/attn_res.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 139‑193

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Python wrapper 检查 contiguous, 选择 BLOCK‑L/warps, launch kernel。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        num_tokens>=256 or blocks<=1 → source tile 1 else 4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        decode/prefill 使用不同 source tiling。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.2.4 vLLM warmup、env 与配置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        证据项

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        直接源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        简化逻辑

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Infra 含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        KimiLinearConfig

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vllm/transformers_utils/configs/kimi_linear.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 45‑52、110

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        attn_res_block_size

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         是文本配置字段,默认 None。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        None disables AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        是否启用由模型 config 控制。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        KimiK3Config 包装

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vllm/transformers_utils/configs/kimi_k3.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 86‑131

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        多模态配置内嵌 KimiLinearConfig。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        text_config carries AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        K3 文本侧继承该配置。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        env 默认值

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vllm/env.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 200‑214

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        VLLM_KIMI_K3_AUX_ATTN_RES_STREAM=False

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        、GEMM_AR=True、GEMM_RS=False。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        aux off, GEMM‑AR on by default

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        性能路径可环境开关控制。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        env 解释

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vllm/env.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 1597‑1612

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        注释说明 aux stream 改变 drafter 看到的数值,GEMM‑AR/RS 要求同一 NVLink domain。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        opt‑in numeric mode + topology limits

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnRes 与 speculative / 通信优化有显式风险开关。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        warmup 调度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vllm/model_executor/warmup/kernel_warmup.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 34‑36、153‑155

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        导入并在 enable_jit_warmup 时调用 kimi_k3_triton_warmup(worker)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        global warmup → K3 warmup

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        请求前预编译 Triton kernels。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        AttnRes warmup

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vllm/model_executor/warmup/kimi_k3_triton_warmup.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 42‑89

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        warm_attn_res()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         读取 attn_res_block_size, 构造零张量,对所有 warmup‑profile 调 attn_res()。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        compile common AttnRes profiles

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        避免线上首次遇到某种 block/delta/norm 组合时 JIT 抖动。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        MTP 禁用 AttnRes

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vllm/models/kimi_k3/nvidia/mtp.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         行 88‑90; amd/mtp.py 行 75‑84

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        MTP block 浅拷贝 config 后设 attn_res_block_size=None。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        draft block starts without bank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        推测模型不继承主模型 AttnRes 状态,避免状态不匹配。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.3 源码伪代码总览(基于 SGLang/vLLM 共同语义)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          # 模型入口
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          hidden = embed(input) or recv_pp_hidden
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          bank = empty(T, ceil(end_layer / block_size), H)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          if recv_pp_bank:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              bank[:, :old_rows] = recv_pp_bank
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          prefix = hidden


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          for layer in layers:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              # 聚合 1: attention 输入
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              write_idx = layer.block_write_idx if layer.is_block_write_layer else -1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              x = attn_res(prefix, delta=None_or_pending, bank,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           layer.self_attention_res_norm.weight,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           layer.self_attention_res_proj.weight,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           layer.input_layernorm.weight,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           num_blocks=layer.prev_valid_blocks,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           block_write_idx=write_idx)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              if layer.is_block_write_layer:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  prefix = None  # 新块开始
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              attn_out = attention(x)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              # 聚合 2: MLP 输入
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              if prefix is None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  prefix, delta = attn_out, None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              else:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  delta = attn_out
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  x = attn_res(prefix, delta, bank,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               layer.mlp_res_norm.weight,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               layer.mlp_res_proj.weight,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               layer.post_attention_layernorm.weight,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               num_blocks=layer.prev_valid_blocks + layer.is_block_write_layer,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               block_write_idx=-1)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              mlp_out = mlp(x)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              prefix = prefix + mlp_out


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          # 输出侧
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          hidden = attn_res(prefix, pending_mlp, bank,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            output_attn_res_norm.weight,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            output_attn_res_proj.weight,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            final_norm_or_none,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            num_blocks=all_blocks,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            block_write_idx=-1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.4 与 Kimi K3 架构的协同

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          AttnRes 不是替代 KDA 或 MLA 的 attention 算法;它重写的是 residual stream 的输入选择。KDA/MLA 负责序列维度信息混合,AttnRes 负责深度维度信息混合,MoE/MLP 负责非线性变换和容量扩展。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          源码层面可验证:SGLang 配置通过 linear_attn_config['kda_layers'] 决定哪些层是 KDA,其他为 MLA;模型构造时在 KimiK3DecoderLayer 内二选一。vLLM NVIDIA 路径也导入 KimiK3DeltaAttention 与 MultiHeadLatentAttention,并在同一 decoder layer 的外层挂 AttnRes 参数。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          TransFormer-封面
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          TransFormer-封面


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • [1] Kimi Team. Attention Residuals(技术报告), arXiv:2602.15031, 2026. 仓库:https://github.com/MoonshotAI/Attention-Residuals

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • [2] Kimi Team. Kimi K3 Technical Report §2.2(Eqs. 8-10 与 8 块×12 层=9 源配置), arXiv:2607.24653.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • [3] Zhenda Xie et al. mHC: Manifold-Constrained Hyper-Connections, arXiv:2512.24880.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • [4] Yongyi Yang & Jianyang Gao. mHC-lite: You Don't Need 20 Sinkhorn-Knopp Iterations, arXiv:2601.05732.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • [5] Yu Zhang et al. Kimi Linear: An Expressive, Efficient Attention Architecture, arXiv:2510.26692.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          阅读原文

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          跳转微信打开

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          •  

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          【轻量化复刻大模型 / KIMI K3】Gated MLA 梳理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          原创 罗西的思考 2026-11-09 20:35 北京

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          【轻量化复刻大模型 / KIMI K3】Gated MLA 梳理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 0x00 概述

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 0.1 原始论文

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 0.2 直接相关的图/表

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 0.3 本文说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 0x01. 演进脉络与定位

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 1.1 脉络

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 1.2 同期竞品

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 1.3 定位一句话

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 0x02. 原理讲解

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 2.1 引入 MLA 的必要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 2.1 直觉类比视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 2.3 准专业水平视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 2.4 专家视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 2.5 实现代码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 2.6 Gated 体现在哪里?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 0x03. 子知识点拆解

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 0x04 子知识点深度分析

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 4.0 共享抽象与设计动机

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 4.1 子知识点:latent 压缩-重构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 4.2 子知识点:全秩输出门(Eq.7)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 4.3 子知识点:NoPE(无位置编码)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 4.4 子知识点:解码缓存 MLACache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 4.5 子知识点:FP32 注意力累加

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 0x01 实现概述

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 1.1 模块范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 1.2 实现思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 1.3 目录结构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 1.4 运行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 0x02 核心数学

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 2.1 总体公式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 2.2 子机制分解

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 2.3 关键洞察

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 0x03 设计思路与实现细节

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 3.1 复用策略

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 3.2 测试驱动

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 3.3 数学规律总结

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 0x04 每个 Tab 的详细说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Tab 1: Cache Size

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Tab 2: Gate Suppression

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Tab 3: Rank Scan

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Tab 4: Incremental Decode

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Tab 5: NoPE

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Tab 6: Output Gate

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Tab 7: FP32 Accumulation

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          0x00 概述

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          知识点:Gated Multi-head Latent Attention(门控多头潜在注意力)— K3 混合架构中的全局注意力组件。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          0.1 原始论文

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          论文

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          出处

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Kimi K3: Open Frontier Intelligence

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (K3 技术报告,Gated MLA 最终定义 §2.1.2)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          arXiv:2607.24653(2026-07-27);Kimi Team;Moonshot AI

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          DeepSeek-V2: A Strong, Economical, and Efficient Mixture-of-Experts Language Model

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (MLA 原始提出者)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          arXiv:2405.04434(2024-05);DeepSeek-AI

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          0.2 直接相关的图/表

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          K3 架构总览,MLA 与 KDA 层 3:1 交错:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Kimi K3 architecture
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Kimi K3 architecture

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Gated MLA 公式(NoPE + 全秩输出门 Eq.7):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          gated mla
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          gated mla

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          0.3 本文说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          本文分为两部分:第一部分是 MLA 原理/代码解读。第二部分是 MLA demo 解读(因为每一部分的文字都太少了)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          其次,关于项目:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          0x01. 演进脉络与定位

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          1.1 脉络

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Gated MLA 的谱系:MLA 最早由 DeepSeek-V2 提出,用"压缩-重构"把 KV cache 从 O(T·H·D) 降到 O(T·kv_lora_rank)。K3 继承 MLA 框架,做了两处关键改动使其适配 K3 混合架构。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          1.2 同期竞品

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          方案名

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          核心机制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          优势

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          劣势

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          标准 MHA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          每 token 存 K/V

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          精确检索、简单

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          cache 随 T 线性爆炸

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          DeepSeek MLA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          latent 压缩 K/V

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          cache 小、有 RoPE

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          位置参数扩展需手术

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          K3 Gated MLA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          latent 压缩 + NoPE + 输出门

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          cache 小 + 无位置参数 + 可门控

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          压缩有损、需 KDA 提供位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          GQA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          共享 KV head

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          cache 减半

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          压缩比有限(~8×)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          1.3 定位一句话

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          不同于 DeepSeek-V2 仍需 RoPE 的 MLA,K3 的 Gated MLA 通过 NoPE(位置交给 KDA 递推) + 全秩输出门 实现"cache 小 + 免位置参数手术 + 逐通道可门控"的全局注意力。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          0x02. 原理讲解

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          2.1 引入 MLA 的必要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA 固定大小的状态不可能无损保存无限长历史。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          随着上下文不断变长,新 Token 会持续写入、覆写和冲刷旧状态。因此,在需要精确回忆某个细节的任务中,例如“needle in a haystack”任务,线性状态可能逐渐遗忘目标信息,导致精准召回能力下降。遗忘门和 Delta Rule 能改善写入策略,但它们不会让固定容量变成无限容量。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          一个自然的折中方案是 Hybrid:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • KDA 层负责低成本地聚合长历史;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • Full Attention 或 Sparse Attention 层提供更直接的历史访问路径;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 两者结合,在效率和精确回忆之间取平衡。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          2.1 直觉类比视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          想象你有一个智能摘要员(latent 压缩)。每来一条新信息(token),它不存全文,只记一句高度压缩的摘要(latent c)放进小本子(latent cache)。要回答问题时,再根据摘要"脑补"细节(up 投影重构 K/V)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          关键两点:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          1. 本子很小 —— 摘要只有 kv_lora_rank(如 512)维,而非原文 H·D(如 96×128)维,1M 条信息只占很小空间。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          2. 它不记位置 —— 摘要员不关心"这是第几条"(NoPE);位置由搭档 KDA 负责(其递推衰减天然知道先后)。上下文扩到 100 万条也无需"重新编号"手术。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          最后,摘要员交出答案前根据当前问题决定每块读多少(输出门 sigmoid(W_g x))—— 这就是"Gated"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          2.3 准专业水平视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          输入输出

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 输入:x ∈ R^{B×T×d}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 压缩 latent:c = RMSNorm(W_dkv x) ∈ R^{B×T×r},r = kv_lora_rank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 重构:k = W_uk c、v = W_uv c(每 head 展开)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          gated-mla-picture
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          gated-mla-picture

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          核心公式(单 head)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            q = W_upq( RMSNorm(W_dq x) )           # query(q-LoRA 分支)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            c = RMSNorm( W_dkv x )                 # 唯一缓存对象
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            k = W_uk c ;  v = W_uv c               # 注意力时重构
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            o = softmax( q k^T / sqrt(d_qk) ) v    # 标准因果注意力
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            y = W_o [ sigmoid(W_g x) ⊙ o ]         # Eq.7 逐通道输出门
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • W_dkv ∈ R^{r×d}:压缩投影(唯一真正"压信息"处)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • W_uk, W_uv:从 latent 展开 K/V

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • sigmoid(W_g x):全秩门,逐通道在 (0,1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            与标准做法公式级对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            标准 MHA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Gated MLA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            记忆

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            O(T·H·D)O(T·r)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            检索

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            精确

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            来自压缩 latent,有损

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            RoPE

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            无(NoPE)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            输出调制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            无

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            sigmoid(W_g x)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             逐通道门

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.4 专家视角

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 为什么压缩 work:K/V 高维表示冗余大,低秩 latent 捕获主要信息是合理低秩近似。代价是逐 token 精确检索被"模糊化"——这正是 K3 用 KDA(线性注意力)+ MLA(全局注意力)混合的原因。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • NoPE 必要性:位置由 KDA 递推衰减(recency-aware)提供。上下文到 1M 无需位置参数手术(不调 RoPE 频率基、不用 YaRN)——这是 K3 支持 1M 上下文的关键系统设计。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 为什么全秩门:KDA 输出门是"head-wise RMSNorm + 低秩门";MLA 用全秩门让每 token 独立调制每个通道,表达力更强。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 论文未解决问题:压缩信息损失在多大程度可被"全局模糊检索"弥补?latent 秩是否需按层自适应,仍开放。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2.5 实现代码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              # -*- coding: utf-8 -*-
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """Gated Multi-head Latent Attention(门控多头潜在注意力,K3 报告 §2.1.2)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              解决的问题:标准 softmax 注意力的 KV cache 随序列长度线性增长。在 1M 上下文下,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              cache 显存与带宽会成为瓶颈。MLA 的核心思想是**压缩 + 重构**:把每个 token 的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              key/value 先压进一个低维潜在向量 ``c = W_dkv x``(``kv_lora_rank`` 维),只在
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              cache 里存这个压缩后的 latent;真正参与注意力时再用学到的 up 投影把每 head 的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              k/v 展开出来。于是 cache 大小由 ``kv_lora_rank`` 决定,而不是
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ``num_heads * head_dim``。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              K3 在继承 DeepSeek-V2 的 MLA 基础上做了两处改动:


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              1. **NoPE(完全不施加位置编码)**:MLA 层不应用 RoPE,也没有解耦的 rope head
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 维。位置信息完全由与之交错的 KDA 层提供 —— KDA 的递推衰减和 delta 更新天然
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 位置敏感(recency 由衰减累积编码)。好处是:把上下文扩到 1M **不需要任何
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 位置参数手术**(不用调 frequency base、不用 YaRN)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2. **全秩输出门(Eq. 7)**:``y = W_o [ sigmoid(W_g x) * o ]``,让每个 token 按
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 其输入调制它从全局注意力中读取哪些通道。这里 ``W_g`` 是**全秩**的(输出维等于
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 拼接后的 v 维),而非低秩门 —— 低秩门在 KDA 上换成了 head-wise RMSNorm。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              数值:训练时注意力输出在 FP32 累加(``attn_out_fp32``),用于修正 flash
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              attention 的偏向舍入误差(biased rounding)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              本项目实现与 ``kimi3-master/kimi3/modules/mla.py`` 逐位对齐(同公式、同投影命名、
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              同 cache 结构);SGLang 在独立 ``kimi-k3`` 分支里把输出门融合成单 CUDA kernel
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              (``mla_output_gate.cuh``:``out = x * sigmoid(gate)``)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              class MLACache:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  """解码缓存:**只存压缩后的 latent**。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  这是 MLA 的意义所在:cache 随 ``kv_lora_rank``(如 512)增长,而不是随
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ``num_heads * head_dim``(如 96*128=12288)增长。相比之下标准 attention 的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KV cache 每个 token 都要存原始 K/V,MLA 只需存压缩表示,省下约一个数量级。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ``kv_latent`` 形状 ``(batch, seq, kv_lora_rank)``;``append`` 沿 seq 维追加
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  新 latent 并返回完整历史(供当前步展开全部 k/v)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  __slots__ = ("kv_latent", "length")


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  def __init__(self, kv_latent: Tensor, length: int = 0):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.kv_latent = kv_latent
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.length = length


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  def append(self, latent: Tensor) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """追加 ``(batch, new, rank)``,返回完整 latent 历史。"""
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.kv_latent = (
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          latent if self.kv_latent is None else torch.cat([self.kv_latent, latent], dim=1)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      )
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.length = self.kv_latent.shape[1]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      return self.kv_latent


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  def clone(self) -> "MLACache":
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """深拷贝本 cache(投机解码 / beam search 需要在候选续写间分支状态)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      与 ``KDACache.clone`` 语义一致:返回独立副本,改动副本不影响原对象。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      MLA 的 cache 只是 ``kv_latent`` 一个压缩 latent 张量,深拷贝即可。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      return MLACache(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          None if self.kv_latent is None else self.kv_latent.clone(),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          length=self.length,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      )


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  def truncate(self, length: int) -> None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """原地截断 latent 到 ``length`` 个位置(回滚到被接受前缀末尾)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      投机解码部分接受时,草稿被拒绝的位置对应的 latent 必须丢弃,否则
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      下一轮会把“未验证的续写”当成历史。MLA 是逐 token 追加的压缩 latent,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      直接按 seq 维切回 ``length`` 即可精确回滚。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      if self.kv_latent is not None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.kv_latent = self.kv_latent[:, :length]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.length = length


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              class GatedMLA(nn.Module):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  """完整的门控 MLA 层。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  参数结构(§2.1.2):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  - ``q_down / q_norm / q_up``(q-LoRA 分支):query 也走低秩压缩
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ``dim -> q_lora_rank -> qk_dim``;若 ``q_lora_rank is None`` 则直接用
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ``q_proj: dim -> qk_dim`` 全秩投影。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  - ``kv_down / kv_norm / k_up / v_up``:key/value 的压缩-重构。``kv_down``
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    是唯一的压缩投影(``dim -> kv_lora_rank``),``k_up / v_up`` 在注意力时
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    把 latent 展开成每 head 的 qk 维 / v 维。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  - ``g_proj``:**全秩输出门** ``sigmoid(W_g x)``(Eq. 7)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  - ``o_proj``:最终输出投影 ``v_dim -> dim``。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  数据流(forward):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      q = W_upq(RMSNorm(W_dq x))                  (b,h,t,dqk)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      c = RMSNorm(W_dkv x)                        (b,t,kv_lora)  ← 唯一 cache
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      k = W_uk(c)  (b,h,t,dqk)  ;  v = W_uv(c)  (b,h,t,dv)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      o = softmax(q k^T / sqrt(dqk)) v            (b,h,t,dv)  [fp32 累加]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      y = W_o [ sigmoid(W_g x) * o ]              (b,t,dim)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  def __init__(self, dim: int, cfg: MLAConfig, *, layer_idx: int = 0, eps: float = 1e-6):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      super().__init__()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.dim = dim
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.cfg = cfg
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.layer_idx = layer_idx
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      h = cfg.num_heads
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.num_heads = h
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.qk_head_dim = cfg.qk_head_dim
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.v_head_dim = cfg.v_head_dim
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 注意力缩放因子 1/sqrt(qk_head_dim)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.scale = cfg.qk_head_dim**-0.5


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # query 投影:可选 q-LoRA 低秩分支,或全秩直连。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      if cfg.q_lora_rank is None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.q_proj = nn.Linear(dim, cfg.qk_dim, bias=False)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.q_down = self.q_up = self.q_norm = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      else:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.q_proj = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.q_down = nn.Linear(dim, cfg.q_lora_rank, bias=False)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.q_norm = RMSNorm(cfg.q_lora_rank, eps)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.q_up = nn.Linear(cfg.q_lora_rank, cfg.qk_dim, bias=False)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # key/value 的压缩与重构。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.kv_down = nn.Linear(dim, cfg.kv_lora_rank, bias=False)  # W_dkv:压缩
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.kv_norm = RMSNorm(cfg.kv_lora_rank, eps)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.k_up = nn.Linear(cfg.kv_lora_rank, cfg.qk_dim, bias=False)  # W_uk
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.v_up = nn.Linear(cfg.kv_lora_rank, cfg.v_dim, bias=False)   # W_uv


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.g_proj = nn.Linear(dim, cfg.v_dim, bias=False)   # 全秩门,Eq. 7
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self.o_proj = nn.Linear(cfg.v_dim, dim, bias=False)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  def _queries(self, x: Tensor) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """计算 query。q-LoRA 分支:``W_upq(RMSNorm(W_dq x))``;否则 ``W_q x``。"""
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      if self.q_proj is not None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          return self.q_proj(x)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      assert self.q_down is not None and self.q_norm is not None and self.q_up is not None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      return self.q_up(self.q_norm(self.q_down(x)))


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  def forward(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      self,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      x: Tensor,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      *,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      attn_mask: Tensor | None = None,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      cache: MLACache | None = None,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      b, t, _ = x.shape
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      h, dqk, dv = self.num_heads, self.qk_head_dim, self.v_head_dim


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # query -> (b, h, t, dqk)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      q = self._queries(x).view(b, t, h, dqk).transpose(1, 2)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 压缩 latent;有 cache 则追加历史(decode 时只传当前 token,靠 append 累积)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      latent = self.kv_norm(self.kv_down(x))
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      if cache is not None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          latent = cache.append(latent)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      kv_len = latent.shape[1]


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 从 latent 展开每 head 的 k/v。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      k = self.k_up(latent).view(b, kv_len, h, dqk).transpose(1, 2)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      v = self.v_up(latent).view(b, kv_len, h, dv).transpose(1, 2)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 训练时在 FP32 累加注意力,修正低精度舍入偏置。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      if self.cfg.attn_out_fp32 and self.training:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          q, k, v = q.float(), k.float(), v.float()


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      is_causal = attn_mask is None and kv_len == t
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      if hasattr(F, 'scaled_dot_product_attention'):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          out = F.scaled_dot_product_attention(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              q, k, v, attn_mask=attn_mask, is_causal=is_causal, scale=self.scale
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          )
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      else:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          # torch < 2.0(本仓库 CPU 环境):手动因果 softmax 注意力。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          attn = torch.matmul(q * self.scale, k.transpose(-2, -1))
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          if is_causal:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              mask = torch.triu(torch.full((t, kv_len), float('-inf'), device=x.device), diagonal=1)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              attn = attn + mask
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          elif attn_mask is not None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              attn = attn + attn_mask
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          attn = F.softmax(attn, dim=-1)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          out = torch.matmul(attn, v)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # (b,h,t,dv) -> (b,t,h*dv),降回输入 dtype。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      out = out.transpose(1, 2).reshape(b, t, h * dv).to(x.dtype)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # Eq. 7:依赖输入的、逐通道的、全秩输出门。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # sigmoid(W_g x) 逐通道在 (0,1),决定该 token 从注意力输出里读取多少。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      out = out * torch.sigmoid(self.g_proj(x))
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      return self.o_proj(out)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  def init_cache(self, batch: int, *, device=None, dtype=torch.float32) -> MLACache:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """为 decode 初始化空 latent cache:``(batch, 0, kv_lora_rank)``。"""
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      return MLACache(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          torch.zeros(batch, 0, self.cfg.kv_lora_rank, device=device, dtype=dtype)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      )


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  def extra_repr(self) -> str:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      return (
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          f"dim={self.dim}, heads={self.num_heads}, qk={self.qk_head_dim}, "
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          f"v={self.v_head_dim}, q_lora={self.cfg.q_lora_rank}, "
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          f"kv_lora={self.cfg.kv_lora_rank}, nope=True"
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      )

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2.6 Gated 体现在哪里?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              "Gated" 体现在 mla.py 三处,核心是一个全秩输出门(Eq.7):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              1. 门的参数定义(mla.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                self.g_proj = nn.Linear(dim, cfg.v_dim, bias=False)   # 全秩门,Eq. 7
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • g_proj: dim -> v_dim,v_dim = num_heads * v_head_dim(拼接后的 v 全宽)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • "全秩"指它输出维等于 v 全宽(不是低秩),让每个通道都有独立的门值。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                2. 门真正作用的计算(mla.py,这是"Gated"的落点)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # Eq. 7:依赖输入的、逐通道的、全秩输出门。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  out = out * torch.sigmoid(self.g_proj(x))
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  return self.o_proj(out)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • torch.sigmoid(self.g_proj(x)) 产生一个逐通道、值在 (0,1) 的掩码。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • out * 掩码:逐元素乘,决定该 token 从注意力输出里读多少。这就是"门控" —— 门在"读之前/读之后"逐通道地放行或削弱全局信息。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3. 门的设计意图(模块 docstring,mla.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    **全秩输出门(Eq. 7)**:``y = W_o [ sigmoid(W_g x) * o ]``

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    数据流定位:门作用在注意力输出之后、o_proj 之前:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      注意力输出 o (b,t,h*dv)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      sigmoid(g_proj(x))  ← 逐通道 (0,1) 掩码,依赖输入 x
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ↓ 逐元素乘
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      o * sigmoid(g_proj(x))   ← 门控后的输出
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      o_proj → (b,t,dim)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      "Gated" vs 普通 MLA 的区别:标准 MLA(DeepSeek-V2)是 y = W_o o,直接输出;K3 的 Gated MLA 插入了一个依赖输入的逐通道乘法门 sigmoid(W_g x)。这正是类名 GatedMLA 与变量名 g_proj(g = gate)的来源。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      对比 KDA:KDA 的输出门(kda.py:254)也是 out * sigmoid(g_proj(x)),但前面多了一步 HeadRMSNorm(kda.py:253);MLA 的门则直接作用在注意力输出上。两者共用"全秩 sigmoid 门"这个思路。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      0x03. 子知识点拆解

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Gated MLA
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ├── 3.1 latent 压缩-重构(kv_down/norm/k_up/v_up)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │   └── 依赖:mla.py:75-78 + mla.py:101-107
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ├── 3.2 q-LoRA 分支(或全秩 q_proj)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │   └── 依赖:mla.py:66-73 + mla.py:83-87
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ├── 3.3 全秩输出门(Eq.7)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │   └── 依赖:mla.py:80 + mla.py:128-130
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ├── 3.4 NoPE
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │   └── 依赖:mla.py:141
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ├── 3.5 解码缓存 MLACache(只存 latent)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │   └── 依赖:mla.py:34-51 + mla.py:132-135
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            └── 3.6 FP32 注意力累加
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                └── 依赖:mla.py:109-110

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        代码对应

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        子知识点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        代码位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        变体/切换入口

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        latent 压缩-重构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        mla.py:75-78kv_lora_rank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        (config.py:45)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        q-LoRA 分支

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        mla.py:66-73, 83-87q_lora_rank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        (config.py:44,None 时全秩 q_proj)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        全秩输出门

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        mla.py:80, 128-130

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        无

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        NoPE

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        mla.py:141

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        恒为 True

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        解码缓存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        mla.py:34-51, 132-135

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        无

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        FP32 累加

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        mla.py:109-110attn_out_fp32

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        (config.py:46)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        0x04 子知识点深度分析

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.0 共享抽象与设计动机

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        统一符号:r = kv_lora_rank,d_qk/d_v 为每 head 的 qk/v 维,H 为 head 数,d = H·d_v。压缩 latent c 是 MLA 唯一需缓存的张量。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        为什么只缓存 latent:标准 MHA 缓存 (k_i,v_i) 每 token O(2H·d_qk);MLA 缓存 c_i 每 token O(r)。以 K3 配置(H=96,d=128,r=512)为例,压缩比约 2·96·128/512 = 48×。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.1 子知识点:latent 压缩-重构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.1.1 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 直觉:摘要员只记摘要,回答时脑补。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 准专业:c = RMSNorm(W_dkv x),k=W_uk c,v=W_uv c。这是秩 r 的低秩近似(W_uk W_dkv 有效秩 ≤ r)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 专家:等价于 K/V 的低秩分解。信息论上 r 决定可保留的"自由信息"上界;r 越大越接近无损但 cache 越大。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.1.2 对比基线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 标准:直接存 W_k x、W_v x(无损)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 本方案:存 W_dkv x,注意力时展开。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 收益:cache 压缩;代价:检索有损。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.1.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • a) 最强反对:压缩丢失逐 token 细节,长程精确检索受损。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • b) 若失败,最可能错在:假设 K/V 冗余度足够高。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • c) 胜出:长上下文、cache 内存敏感、容忍模糊检索;失败:需精确逐 token recall 的任务。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • d) 更稳健:提高 r,或按层混合 r。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • e) 受影响方:需要精确检索的任务方。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.1.4 计算复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • FLOPs:注意力本身 O(T²·d_qk) 不变;K/V 投影从 O(T·d·H·d_qk) 降到 O(T·d·r)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 内存:标准 cache O(T·2H·d_qk),MLA O(T·r)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 参数:新增 W_dkv(r×d)+ W_uk/W_uv(H·d_qk×r)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.1.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 关键超参:kv_lora_rank(r)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • r 增大:cache 大、检索准;r 减小:cache 小、表达被压平(实验见 §4.7 E2)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 论文经验:K3 取 r=512(相对 2H·d_qk 是 48× 压缩)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.1.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        伪代码(对齐 mla.py):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          latent = self.kv_norm(self.kv_down(x))        # (B,T,d)->(B,T,r) 压缩+归一化
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          if cache is not None: latent = cache.append(latent)  # 追加历史
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          k = self.k_up(latent).view(b,kv_len,h,dqk).transpose(1,2)  # 展开 K
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          v = self.v_up(latent).view(b,kv_len,h,dv).transpose(1,2)   # 展开 V

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          真实代码:mla.py:。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          与 kimi3-master 核对:本项目 mla.py 与 kimi3-master/kimi3/modules/mla.py 逐位对齐(同投影命名、同 forward 结构、同 cache)。test_mla.py(增量解码 vs prefill)验证一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          与 kimi-k3-pytorch-main 差异:kimi-k3-pytorch-main/src/mla/ 的 MLA 无 q-LoRA(query 用单一全秩 W_q),本项目 K3 有 q_down/q_up;二者 KV 压缩-重构一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          与 SGLang 核对:SGLang K3 分支用 DeepSeek-V2 的 DeepseekV2AttentionMLA + skip_rope=True(NoPE),输出门融合成单 CUDA kernel mla_output_gate.cuh(out = x·sigmoid(gate),bf16 双舍入位对齐)。本项目 CPU 版用 torch.sigmoid(g_proj(x)),语义一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.1.7 探讨代码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          见 experiments/models/llm/kimi_k3/modules/gated_mla/discussion.py:E1 验证门可关断(gate→0 时输出被抹掉到 0.0e+00);E2 扫描 kv_lora_rank,观察输出离散度(检索丰富度)随压缩下降(r=8 时 std=0.0053,r=48 时 std=0.0215)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.1.8 验证 demo

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          见 experiments/models/llm/kimi_k3/modules/gated_mla/plot_gated_mla.py:plot_gate_suppression.png、plot_rank_scan.png、plot_cache_size.png。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          可视化脚本

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          experiments/models/llm/kimi_k3/modules/gated_mla/plot_gated_mla.py 运行后生成三图:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • plot_gate_suppression.png(门强度 vs 输出幅度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            plot_gate_suppression
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            plot_gate_suppression
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • plot_rank_scan.png(kv_lora_rank vs 检索丰富度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            plot_rank_scan
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            plot_rank_scan
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • plot_cache_size.png(cache 大小 vs 序列长)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            plot_cache_size
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            plot_cache_size
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          截图说明
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 门抑制图:横轴 g_proj 偏置,纵轴 MLA 输出 max|·|,S 形曲线 —— 展示门从"全开"到"全关"的抑制能力,支撑"门可关断"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 蓝色圆点线:偏置从 -1e4 到 50 时的输出幅度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 当偏置 < -10 时,输出迅速趋近 0(门完全关闭)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 当偏置 > 0 时,输出稳定(门完全打开)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 布局:1×1 单图(折线图,symlog x 轴)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              X 轴:g_proj 权重偏置(-1e4 ~ 50,symlog 刻度,中心 = 0)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Y 轴:MLA 输出 max|·|

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              曲线:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              你该看什么:曲线的 S 形特征——左侧平台(输出≈0)到右侧平台(输出最大)的过渡。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              理想情况:偏置=-1e4 时输出 < 1e-3,偏置=50 时输出 > 0.1,中间有平滑过渡。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              异常指示:如果偏置=-1e4 时输出仍然很大,说明门没有正确乘到输出上(可能 W_g 没连接到前向路径)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • rank 扫描图:横轴 latent 秩,纵轴输出 std,上升曲线 —— 展示 latent 越窄信息越被压平,支撑 4.1.3 的"压缩有损"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 紫色方点线:不同 rank 下的输出 std

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 随 rank 增大,std 单调递增(信息越丰富)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 低 rank 区间(8→16)斜率陡峭(信息损失严重)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 高 rank 区间(24→48)斜率趋缓(边际收益递减)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 布局:1×1 单图(折线图)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              X 轴:kv_lora_rank(8 ~ 48,线性刻度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Y 轴:重构输出 std(检索丰富度代理)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              曲线:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              你该看什么:曲线的单调递增趋势。如果曲线不单调或有异常跳变,说明实现有 bug。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              理想情况:rank=8 时 std 最低(信息被严重压平),rank=48 时 std 最高(接近无压缩)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              异常指示:如果 rank=8 时 std 很高(与 rank=48 相近),说明压缩没有生效(kv_down 权重可能全零)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • cache 大小图:双 log 轴,MLA latent cache 远低于标准 KV cache —— 展示 MLA 核心卖点。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 红色圆点线:标准 KV cache,斜率 = 1(线性增长)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 绿色方点线:MLA latent cache,斜率 = 1(线性增长但截距低约 48×)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 布局:1×1 单图(双对数折线图)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              X 轴:序列长度 T(512 ~ 1M,对数刻度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Y 轴:cache 元素数(百万,对数刻度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              曲线:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              你该看什么:两条线的垂直间距即压缩比。在 T=1M 处,标准 KV 约 24,576M 元素,MLA 约 512M 元素。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              理想情况:两条线平行(都是 O(T)),但绿色线始终在红色线下方约 1.5 个对数单位。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              异常指示:如果两条线交叉或绿色线更高,说明实现有 bug(cache 未正确压缩)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          实测数值回填

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          关键读数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          关键推论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          plot_gate_suppression

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          gate_bias=-1e4: out=0.0;0: 2.2e-02;+50: 4.3e-02

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          门强抑制、输入驱动

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          plot_rank_scan

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          r=8: std=0.0053;r=48: std=0.0215

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          秩越低表达越压平

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          plot_cache_size

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          T=1M: 标准KV=25770M,MLA=537M 元素

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          压缩约 48×(支撑 MLA 核心卖点)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.2 子知识点:全秩输出门(Eq.7)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.2.1 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 直觉:每个 token 像"读者",决定从全局信息里读多少。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 准专业:y = W_o [ sigmoid(W_g x) ⊙ o ]。sigmoid(W_g x) 逐通道在 (0,1)(g_proj: d -> H·d_v,全秩)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 专家:门是输入依赖的、逐通道的乘法调制。相比加法偏置,乘法门能更直接地"打开/关闭"某条通道。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.2.2 对比基线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 标准 MLA:y = W_o o(无门)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 本方案:y = W_o [ sigmoid(W_g x) ⊙ o ]。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 收益:逐通道可门控;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 代价:新增参数 W_g(H·d_v × d)与一次额外 matmul。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.2.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • a) 最强反对:门若训练中全关,MLA 退化为直通,全局注意力失效。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • b) 若失败,最可能错在:初始化让门过早饱和到 0。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • c) 胜出:需要模型自适应忽略某些全局通道;失败:门饱和(梯度消失)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • d) 更稳健:门加偏置初始化(sigmoid 偏置为正),避免过早关断。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • e) 受影响方:若门退化,全局注意力失效,拖累需要全局信息的任务。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.2.4 计算复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • FLOPs:o 是 O(T·H·d_v),门 sigmoid(W_g x) 是 O(T·d·H·d_v)(与 o_proj 同级)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 内存:门与 o 同形状,无额外 cache。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 参数:W_g 为 H·d_v × d,与 o_proj 相同规模。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.2.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 关键:W_g 的尺度决定门在 (0,1) 的分布;初始化小权重 → 门 ≈ 0.5(中性)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 实测(discussion.py E1):全 1 输入、W_g 推向 -1e4 时输出被抹到 0.0e+00;随机输入时门值范围约 [0.13, 0.86](输入依赖、逐通道)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.2.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            out = out * torch.sigmoid(self.g_proj(x))   # 全秩门,逐通道
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return self.o_proj(out)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            与 SGLang 核对:SGLang mla_output_gate.cuh 实现 out = x·sigmoid(gate)(bf16),与本项目 torch.sigmoid(g_proj(x)) 语义逐位一致,仅做 kernel 融合与双舍入对齐优化。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.2.7 探讨代码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            experiments/models/llm/kimi_k3/modules/gated_mla/discussion.py E1 直接操纵 g_proj 验证门能彻底关断输出(0.0223 → 0.0e+00),证明门是强抑制机制;同时展示随机输入下门值随输入变化(全秩、输入依赖)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.2.8 验证 demo

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            plot_gate_suppression.png 展示门偏置 vs 输出幅度曲线。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            plot_gate_suppression
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            plot_gate_suppression

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.3 子知识点:NoPE(无位置编码)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.3.1 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 直觉:摘要员不记"第几条",位置交给搭档 KDA。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 准专业:MLA 完全不含 RoPE 参数(无 rotary_emb、无 rope head 维)。mla.py 的 extra_repr 恒标记 nope=True。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 专家:位置信息由 KDA 层的递推衰减(recency-aware)提供。这让 MLA 层上下文扩展无需位置参数手术,是 K3 支持 1M 上下文的关键系统协同设计。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.3.2 对比基线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 标准 MLA(DeepSeek-V2):带 RoPE(解耦 rope head 维)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 本方案:NoPE。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 收益:免位置参数手术、cache 再省一个 rope 维;代价:MLA 层本身无位置先验,须依赖 KDA。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.3.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • a) 最强反对:若 KDA 的递推无法可靠提供位置/顺序信息,MLA 会混淆远距离 token 的相对顺序。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • b) 若失败,最可能错在:KDA 衰减的"recency"编码不够强以承载全部位置语义。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • c) 胜出:长上下文、KDA 比例高(3:1);失败:KDA 过少、需绝对位置的任务。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • d) 更稳健:保留少量 rope 维(如 K3 用 NoPE 前几层)。但 K3 选择全 NoPE。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • e) 受影响方:依赖精确顺序推理的任务。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.3.4 计算复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 相比带 RoPE 的 MLA,NoPE 省去每步 RoPE 旋转计算(O(T·H·d_qk))与 rope 维 cache。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.3.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 无位置超参;test_mla.py:50-56 断言参数/缓冲区不含 rope/freq/pos/alibi/yarn。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.3.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • mla.py 无任何 RoPE 相关层;extra_repr 输出 nope=True。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 与 SGLang 核对:SGLang kimi_linear.py:464 传入 skip_rope=True 关闭 RoPE,deepseek_v2.py 里 self.rotary_emb = None —— 与本项目 NoPE 完全一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.4 子知识点:解码缓存 MLACache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.4.1 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • MLACache 只存压缩 latent (B, T, r)。append 沿 seq 维 torch.cat 追加当前 token 的 latent。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 增量解码(test_mla.py:78-85)验证:逐 token 解码拼接结果与整段 prefill 逐位一致(max diff ≈ 0)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.4.2 对比基线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 标准 MHA cache:每 token 存 K、V(O(2H·d_qk))。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 本方案:每 token 只存 latent(O(r))。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 收益:cache 内存 48× 压缩;代价:decode 时仍需 k_up/v_up 展开。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.4.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • a) 最强反对:latent 无法像原始 K/V 那样精确逐 token 检索。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • b) 若失败,错在假设 latent 含足够检索信息。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • c) 胜出:长上下文、内存受限;失败:精确记忆任务。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • d) 稳健做法:保留一个小的"精确 cache"作为 MLA 补充(K3 用 KDA 承担)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • e) 受影响方:长程精确检索任务。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.4.4 计算复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • cache 内存:O(T·r) 每序列。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • decode 每步:需对全量 latent 重算 k_up/v_up(无吸收优化,本项目为教学性简化);SGLang 用 matrix absorption(w_kc/w_vc 折叠)优化。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.4.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 无独立超参;随 kv_lora_rank 变化。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4.4.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              def append(self, latent):  # mla.py
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self.kv_latent = latent if self.kv_latent is None else torch.cat([self.kv_latent, latent], dim=1)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self.length = self.kv_latent.shape[1]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  return self.kv_latent

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              与 SGLang 核对:SGLang 用 MLATokenToKVPool 分页存储 latent(服务端优化),本项目的 MLACache 是教学性连续存储。语义一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              4.5 子知识点:FP32 注意力累加

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              4.5.1 原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • attn_out_fp32:训练时把 q/k/v 升到 fp32 再做 SDPA,修正 flash attention 的偏向舍入误差。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 本项目 CPU 路径(torch<2.0)手动实现因果 softmax 注意力,同样支持 fp32 累加(mla.py:109-110)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              4.5.2 对比基线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 标准:bf16/fp16 直接算注意力。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 本方案:训练时 fp32 累加。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 收益:数值更准;代价:训练更慢、显存更高。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              4.5.3 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • a) 最强反对:fp32 累加拖慢训练。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • b) 失败点:精度收益 < 速度损失(在不需要高精度的场景)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • c) 胜出:训练稳定性敏感;失败:追求极致吞吐。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • d) 稳健做法:仅对累加部分 fp32(如 SGLang 的做法)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • e) 受影响方:训练方(速度)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              4.5.4 计算复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 注意力 FLOPs 不变,但 fp32 运算带宽更高。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              4.5.5 参数敏感性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 超参 attn_out_fp32(config.py:46),默认 True。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              4.5.6 工程实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                if self.cfg.attn_out_fp32 and self.training:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    q, k, v = q.float(), k.float(), v.float()   # mla.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                【附录】Gated MLA 模块交互式演示

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x01 实现概述

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1.1 模块范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                本演示覆盖 src/models/llm/kimi_k3/modules/mla.py 中的 GatedMLA 和 MLACache 两个类,对应 K3 报告 §2.1.2 的门控多头潜在注意力。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1.2 实现思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                核心卖点是压缩 + 重构:把每个 token 的 key/value 压进低维潜在向量 c = W_dkv x(kv_lora_rank 维),cache 里只存这个 latent;真正参与注意力时再展开成每 head 的 k/v。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                重构策略:plot_gated_mla.py 的三个绘图函数已重构为返回 (fig, text) 元组,Gradio demo 直接 import 这些函数,避免维护两份代码。独立实验(incremental decode、NoPE、output gate、FP32)内联定义。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1.3 目录结构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  experiments/models/llm/kimi_k3/modules/gated_mla/
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ├── discussion.py          # 探讨实验(门可关断 + latent 压缩信息损失)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ├── plot_gated_mla.py      # 可视化脚本(3 个 plot 函数,返回 fig+text)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ├── gradio_mla_demo.py     # Gradio 交互式演示(7 Tabs)



                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.4 运行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    python experiments\models\llm\kimi_k3\modules\gated_mla\gradio_mla_demo.py


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    * Running on local URL:  http://0.0.0.0:7860

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    0x02 核心数学

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    2.1 总体公式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      输入: x ∈ R^{B×T×dim}                    # 隐藏状态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      输出: y ∈ R^{B×T×dim}                    # 注意力输出


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # Query 路径(可选 q-LoRA)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      q = W_upq(RMSNorm(W_dq x))              # (B,T,qk_dim) → reshape → (B,H,T,dqk)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # Key/Value 压缩-重构(MLA 核心)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      c = RMSNorm(W_dkv x)                     # (B,T,kv_lora) ← 唯一 cache
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      k = W_uk(c)                              # (B,H,T,dqk)  从 latent 展开
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      v = W_uv(c)                              # (B,H,T,dv)   从 latent 展开


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # Softmax 注意力
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      o = softmax(q k^T / √dqk) v             # (B,H,T,dv)   [FP32 累加]


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 全秩输出门 (Eq. 7)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      y = W_o [ sigmoid(W_g x) * o ]          # (B,T,dim)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      2.2 子机制分解

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      2.2.1 压缩缓存 (MLACache)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      公式:c = RMSNorm(W_dkv x),其中 W_dkv ∈ R^{kv_lora_rank × dim}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      直觉解释:将高维隐藏状态压缩到低维 latent,cache 只需存储 kv_lora_rank 维而非 num_heads × head_dim 维。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      关键性质:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • Cache 大小:O(B × T × kv_lora_rank) vs 标准注意力 O(B × T × num_heads × head_dim)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 压缩比:2 × num_heads × head_dim / kv_lora_rank(典型 K3 配置下约 48×)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • clone() 支持投机解码 / beam search 的状态分支

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • truncate() 支持投机解码拒绝后的精确回滚

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      2.2.2 全秩输出门 (Eq. 7)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      公式:y = W_o [ sigmoid(W_g x) * o ]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      直觉解释:每个 token 按其输入调制它从全局注意力中读取哪些通道。W_g 是全秩的(输出维 = v_dim),而非低秩门。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      关键性质:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 值域:sigmoid(W_g x) ∈ (0, 1),逐通道调制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 输入依赖:不同输入产生不同门值(token 自适应)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 可压制:W_g → -∞ 时 sigmoid → 0,输出被完全抹掉

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 全秩:每个输出通道可被独立调制(vs KDA 的 head-wise RMSNorm 低秩门)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      2.2.3 NoPE(无位置编码)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      设计:MLA 层不应用 RoPE、ALiBi、YaRN 等位置编码。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      直觉解释:位置信息完全由与之交错的 KDA 层提供。KDA 的递推衰减天然位置敏感(recency 由衰减累积编码)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      关键性质:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 上下文扩到 1M 不需要位置参数手术

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • MLA 层参数名白名单不含 rope/freq/pos 等关键词

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • qk_head_dim × num_heads == qk_dim 配置一致性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      2.2.4 FP32 注意力累加

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      公式:训练时 q, k, v → float() → 注意力计算 → 输出降回输入 dtype

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      直觉解释:修正 flash attention 的偏向舍入误差(biased rounding)。训练时在 FP32 累加,推理时降精度。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      关键性质:通过 MLAConfig.attn_out_fp32 开关控制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      2.3 关键洞察

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      关键洞察:MLA 的 cache 只存压缩 latent c,不存展开的 k/v。decode 时每步追加一个 latent,重新展开全部历史做注意力——这保证了 incremental decode 与 prefill 的逐位一致性,同时 cache 大小从 O(H·D) 降到 O(kv_lora)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      0x03 设计思路与实现细节

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      3.1 复用策略

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Gradio demo 直接调用 plot_gated_mla.py 的三个绘图函数(plot_gate_suppression, plot_rank_scan, plot_cache_size),避免维护两份代码。独立实验(incremental decode、NoPE、output gate、FP32)因逻辑较复杂,内联定义。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      3.2 测试驱动

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      每个 Tab 对应 test_mla.py 中的一个或多个测试函数:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Tab

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      对应测试

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Cache Size

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      test_latent_cache_is_small

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Gate Suppression

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      test_gate_can_suppress_the_attention_output

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Rank Scan

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      (discussion.py E2 实验)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Incremental Decode

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      test_incremental_decoding_matches_prefill

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      NoPE

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      test_no_positional_parameters_exist

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Output Gate

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      test_output_gate_is_input_dependent_and_full_rank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      FP32 Accumulation

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      test_attention_output_kept_in_fp32_during_training

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      3.3 数学规律总结

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      1. 压缩比:2 × H × D / kv_lora_rank,K3 典型配置下约 48×

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      2. 门抑制:sigmoid 的 S 形曲线,偏置 < -10 时输出趋近 0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      3. 信息-压缩权衡:rank 增大,输出 std 单调递增,但边际收益递减

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      4. 一致性:incremental decode 与 prefill 的误差 < 1e-5(float32 精度下为 0)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      0x04 每个 Tab 的详细说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Tab 1: Cache Size

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      展示 MLA 的核心卖点:latent 压缩使 cache 大小从 O(T·num_heads·head_dim) 降到 O(T·kv_lora_rank)。对应 K3 报告中"MLA 使 1M 上下文可行"的论述。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      背景概念

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 标准 KV cache:每个 token 存 K 和 V 两个张量,大小 = T × 2 × num_heads × head_dim

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • MLA latent cache:每个 token 只存压缩 latent c,大小 = T × kv_lora_rank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 压缩比:2 × num_heads × head_dim / kv_lora_rank

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      默认

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      无参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      点击按钮直接运行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      布局:1×1 单图(双对数折线图)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      X 轴:序列长度 T(512 ~ 1M,对数刻度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Y 轴:cache 元素数(百万,对数刻度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      曲线:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 红色圆点线:标准 KV cache,斜率 = 1(线性增长)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 绿色方点线:MLA latent cache,斜率 = 1(线性增长但截距低约 48×)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      你该看什么:两条线的垂直间距即压缩比。在 T=1M 处,标准 KV 约 24,576M 元素,MLA 约 512M 元素。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      理想情况:两条线平行(都是 O(T)),但绿色线始终在红色线下方约 1.5 个对数单位。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      异常指示:如果两条线交叉或绿色线更高,说明实现有 bug(cache 未正确压缩)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      这个验证展示了 MLA 存在的根本意义——没有压缩,1M 上下文的 KV cache 需要 ~96GB 显存(fp32),而 MLA latent cache 只需 ~2GB。如果验证失败,说明 cache 压缩没有生效,MLA 层退化为标准注意力。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Tab 2: Gate Suppression

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      验证输出门 sigmoid(W_g x) 的强抑制能力:门越负 → sigmoid→0 → 输出被完全抹掉。对应 K3 报告 Eq. 7 及 test_mla.py 的 test_gate_can_suppress_the_attention_output。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      背景概念

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 输出门:y = W_o [ sigmoid(W_g x) * o ],W_g 是全秩投影

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 抑制机制:训练中若门全关(W_g → -∞),MLA 层退化为恒等直通

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 风险:门过强抑制会削弱全局信息注入

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      默认

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      无参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      点击按钮直接运行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-2
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-2

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      布局:1×1 单图(折线图,symlog x 轴)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      X 轴:g_proj 权重偏置(-1e4 ~ 50,symlog 刻度,中心 = 0)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Y 轴:MLA 输出 max|·|

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      曲线:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 蓝色圆点线:偏置从 -1e4 到 50 时的输出幅度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 当偏置 < -10 时,输出迅速趋近 0(门完全关闭)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 当偏置 > 0 时,输出稳定(门完全打开)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      你该看什么:曲线的 S 形特征——左侧平台(输出≈0)到右侧平台(输出最大)的过渡。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      理想情况:偏置=-1e4 时输出 < 1e-3,偏置=50 时输出 > 0.1,中间有平滑过渡。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      异常指示:如果偏置=-1e4 时输出仍然很大,说明门没有正确乘到输出上(可能 W_g 没连接到前向路径)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      输出门是 K3 MLA 的关键创新——它让每个 token 能独立决定"从注意力读多少"。如果门不能有效抑制输出,训练时模型无法关闭不需要的注意力路径,Eq. 7 的调制语义失效。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Tab 3: Rank Scan

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      扫描不同 kv_lora_rank,观察重构输出的离散度(std,作为检索丰富度的代理指标)。验证 latent 压缩的信息损失:rank 越低 → 信息被压平 → 检索越粗糙。对应 discussion.py 的 E2 实验。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      背景概念

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • kv_lora_rank:压缩维度,决定 latent 的容量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 检索丰富度:用重构输出的 std 代理——std 越低说明信息越被压平

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 权衡:低 rank → 省 cache → 信息损失;高 rank → 费 cache → 信息保真

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      默认

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      无参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      点击按钮直接运行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-3
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      布局:1×1 单图(折线图)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      X 轴:kv_lora_rank(8 ~ 48,线性刻度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Y 轴:重构输出 std(检索丰富度代理)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      曲线:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 紫色方点线:不同 rank 下的输出 std

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 随 rank 增大,std 单调递增(信息越丰富)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 低 rank 区间(8→16)斜率陡峭(信息损失严重)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 高 rank 区间(24→48)斜率趋缓(边际收益递减)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      你该看什么:曲线的单调递增趋势。如果曲线不单调或有异常跳变,说明实现有 bug。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      理想情况:rank=8 时 std 最低(信息被严重压平),rank=48 时 std 最高(接近无压缩)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      异常指示:如果 rank=8 时 std 很高(与 rank=48 相近),说明压缩没有生效(kv_down 权重可能全零)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      这个实验量化了 MLA 压缩的代价:省 cache 不是免费的,信息损失是固有的。K3 选择 kv_lora_rank=512 是在 cache 节省和信息保真之间的平衡点。如果验证失败(std 不随 rank 变化),说明 latent 压缩机制有问题。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Tab 4: Incremental Decode

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      验证 incremental decode(逐 token 追加 latent 到 cache)与 prefill(一次性整段输入)的输出逐位一致。对应 test_mla.py 的 test_incremental_decoding_matches_prefill。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      背景概念

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • Prefill:一次性输入整段序列,得到完整输出

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • Incremental Decode:从空 cache 开始,每步输入一个 token,追加 latent 到 cache,重新展开全部历史做注意力

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 一致性要求:两种方式的输出必须逐位一致(atol < 1e-5)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      默认

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      无参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      点击按钮直接运行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-4
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      布局:1×2 双联图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      左图:逐 token 误差柱状图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • X 轴:Token 位置(0 ~ 9)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • Y 轴:abs 误差(head 0, dim 0)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 所有柱应接近 0(误差 < 1e-5)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      右图:误差热图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 颜色越深(红/黑)= 误差越大

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 理想情况:全图为均匀深色(误差接近 0)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      你该看什么:所有 token 位置的误差都应该 < 1e-5。如果某个位置误差突然增大,说明 cache 追加顺序有误。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      理想情况:max abs 误差 < 1e-5,所有柱几乎不可见。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      异常指示:如果 max 误差 > 1e-3,说明 incremental decode 与 prefill 不一致——可能是 cache.append 逻辑有误,或 latent 展开顺序错了。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      这是 MLA 缓存机制正确性的关键测试。自回归推理必须保证"每一步看到的注意力视野"与"prefill 一次性算完对应前缀"完全一致。若不一致,decode 阶段的输出分布偏离训练时分布,模型质量严重下降。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Tab 5: NoPE

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      验证 MLA 层不含任何位置编码参数(NoPE 设计)。对应 test_mla.py 的 test_no_positional_parameters_exist。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      背景概念

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • RoPE:旋转位置编码(Rotary Position Embedding)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • ALiBi:线性偏置注意力

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • YaRN:扩展 RoPE 的方法

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • NoPE:MLA 层完全不使用位置编码,位置信息由交错的 KDA 层提供

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      默认

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      无参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      点击按钮直接运行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-5
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-5

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      布局:1×2 双联图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      左图:参数组分布饼图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 展示 MLA 层各投影组(q_down/q_up/kv_down/k_up/v_up/g_proj/o_proj)的参数占比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 没有 rope/freq/pos 等位置相关组

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      右图:白名单检查柱状图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • X 轴:禁用词(rope/freq/inv_freq/pos/alibi/yarn)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • Y 轴:匹配参数数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 所有柱应为 0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      你该看什么:所有白名单检查柱都为 0。如果有任何非零,说明误加了位置编码参数。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      理想情况:6 个检查项全部为 0,参数分布合理。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      异常指示:如果 "pos" 或 "rope" 柱非零,说明有人在 MLA 层加了位置编码——这违背了 K3 的 NoPE 设计。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      NoPE 是 K3 与 DeepSeek 路线的核心分歧点。K3 的 MLA 不做位置编码,位置信息全交给 KDA。若有人误加了 RoPE,会导致:(1) 位置信息冗余(KDA 和 MLA 都编码位置);(2) 1M 上下文扩展需要位置参数手术(调 frequency base),违背 NoPE 的设计初衷。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Tab 6: Output Gate

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      验证输出门(Eq. 7)的三个关键性质:输入依赖、全秩、可压制输出。综合 test_mla.py 的 test_output_gate_is_input_dependent_and_full_rank 和 test_gate_can_suppress_the_attention_output。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      背景概念

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 输入依赖:门值随输入变化(token 自适应),而非常数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 全秩:g_proj.weight.shape = (v_dim, dim),输出维 = num_heads × v_head_dim

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 可压制:W_g → -∞ 时 sigmoid → 0,输出完全归零

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      默认

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      无参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      点击按钮直接运行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-6
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-6

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      布局:1×3 三联图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      左图:输入依赖性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 两个不同输入(x1, x2)的门值分布直方图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 蓝色 = x1,橙色 = x2

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 两个分布应有明显差异(证明输入依赖)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      中图:门值范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 大量随机输入的 sigmoid(W_g x) 分布

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 值域 (0, 1),红线 = 0(完全抑制),蓝线 = 1(完全通过)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 分布应集中在 (0, 1) 内

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      右图:压制能力

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 与 Gate Suppression Tab 类似,但更聚焦于门的极端行为

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 偏置→-∞ 时输出→0,偏置→+∞ 时输出稳定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      你该看什么:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 左图:两个分布不重叠(输入依赖)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 中图:分布完全在 (0, 1) 内(sigmoid 值域正确)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 右图:偏置=-1e4 时输出 < 1e-3(可压制)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      理想情况:三个子图都符合预期,文本输出确认三个性质全部通过。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      异常指示:如果左图两个分布完全重叠,说明门不依赖输入(可能 W_g 全零);如果中图分布超出 (0, 1),说明 sigmoid 没有正确应用。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      全秩输出门是 K3 MLA 的关键创新——它让每个 token 能在所有输出通道上独立决定"从注意力读多少"。若门是低秩的,某些通道永远无法被独立调制,表达能力受限。若门不能压制输出,训练时模型无法关闭不需要的注意力路径。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Tab 7: FP32 Accumulation

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      验证 MLAConfig.attn_out_fp32 配置:训练时注意力输出在 FP32 累加,修正 flash attention 的偏向舍入误差。对应 test_mla.py 的 test_attention_output_kept_in_fp32_during_training。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      背景概念

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 偏向舍入误差:flash attention 在 FP16/BF16 下累加时存在系统性偏向

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • FP32 累加:训练时将 q/k/v 升级为 FP32 计算注意力,输出降回输入 dtype

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 配置开关:MLAConfig.attn_out_fp32=True 启用,推理时通常关闭

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      默认

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      调节效果

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      无参数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      -

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      点击按钮直接运行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-7
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      tab-7

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      布局:1×2 双联图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      左图:输出统计对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 两根柱子:FP32 累加 vs 默认

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 展示输出 mean 值

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • dtype 标注(FP32 累加应为 float32,默认也应为 float32,因为输入是 float32)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      右图:输出分布对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 两个直方图叠加:FP32 累加(绿色)vs 默认(红色)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 两者分布应非常接近(因为输入是 FP32,配置差异主要影响内部计算精度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      你该看什么:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 两个分布的形状应相似(主要差异在内部累加精度,不在最终输出 dtype)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • FP32 累加的输出可能有更小的数值偏差

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      理想情况:两个分布重叠度高,max abs 差异 < 1e-5。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      异常指示:如果两个分布差异很大,说明 FP32 累加开关没有正确影响计算路径(可能 q/k/v 的 float() 转换没有生效)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      FP32 累加是训练稳定性的重要保障。如果训练时悄悄降到 FP16/BF16,误差特性改变,可能导致训练不稳定或收敛变慢。该测试验证配置开关确实通过前向路径生效,而不是写死在代码里。



                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      TransFormer-封面
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      TransFormer-封面

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      阅读原文

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      跳转微信打开

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      •  

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      【轻量化复刻大模型 / KIMI K3】Serve 模块交互式演示

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      原创 罗西的思考 2026-11-08 15:13 北京

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      【轻量化复刻大模型 / KIMI K3】Serve 模块交互式演示

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x00 概述
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x01 核心数学
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 1.1 KDA 投机回放:投影缓存 vs 完整快照
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 1.2 verify_and_replay 重演一致性
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 1.3 KDA 递推核心 (kda_step /kda_recurrent)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 1.4 ReplaySSM 环形缓冲
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 1.5 统一页池 (PagedCache)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 1.6 前缀缓存:两阶段 lookup + chained hash + KDA checkpoint 原子性
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 1.7 引擎 before/after
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 1.8 Fleet 调度:一致哈希 + 预算隔离
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x02 设计思路与实现细节
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.1 文件
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.2 覆盖范围
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.3 设计决策
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.4 依赖
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.5 运行方式
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 2.6 依赖
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x03 Tab 功能说明
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 1 — 投机回放原理
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 2 — 快照成本分析
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 3 — 重演一致性
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 4 — ReplaySSM 环形缓冲
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 5 — 统一页池
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 6 — MLA 分页
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 7 — KDA 存储
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 8 — 前缀缓存命中
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 9 — 前缀缓存未命中
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 10 — 引擎 before/after
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 11 — Fleet 一致哈希
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 12 — Fleet 最小扰动
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 13 — Fleet 预算隔离
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Tab 14 — Fleet 综合仿真
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x04 Tab 1: 投机回放原理
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 4.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 4.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 4.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 4.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x05 Tab 2: 快照成本分析
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 5.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 5.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 5.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 5.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x06 Tab 3: 重演一致性
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 6.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 6.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 6.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 6.4  三种场景构建方式
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 6.5 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x07 Tab 4: ReplaySSM
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 7.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 7.2 背景知识
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 7.3 设计思路
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 7.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 7.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 7.6 调节建议
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 7.7 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x08 Tab 5: 统一页池
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 8.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 8.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 8.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 8.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x09 Tab 6: MLA 分页
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 9.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 9.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 9.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 9.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x10 Tab 7: KDA 存储
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 10.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 10.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 10.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 10.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x11 Tab 8: 前缀缓存命中
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 11.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 11.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 11.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 11.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x12 Tab 9: 前缀缓存未命中
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 12.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 12.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 12.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 12.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x13 Tab 10: 引擎 before/after
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 13.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 13.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 13.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 13.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x14 Tab 11: Fleet 一致哈希
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 14.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 14.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 14.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 14.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x15 Tab 12: Fleet 最小扰动
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 15.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 15.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 15.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 15.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x16 Tab 13: Fleet 预算隔离
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 16.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 16.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 16.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 16.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x17 Tab 14: Fleet 综合仿真
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 17.1 目的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 17.2 UI 组件与参数影响
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 17.3 输出图解读
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 17.4 为什么重要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0x018 验证策略总览
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      0x00 概述

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      本文是 K3 Serve 模块的完整交互式演示,14 个 Tab 覆盖投机回放(投影缓存 vs 快照)、重演一致性验证、ReplaySSM 环形缓冲、统一页池(MLA 分页 + KDA 恒定)、前缀缓存两阶段 lookup + KDA checkpoint 原子性、引擎 before/after、Fleet 一致哈希路由 + 预算隔离。全部 CPU 实时运行,复用 decode.py、replayssm.py、paged_cache.py、prefix_cache.py、engine.py、fleet.py 真实源码算子。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      注:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      0x01 核心数学

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      1.1 KDA 投机回放:投影缓存 vs 完整快照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      KDA 的递归状态 S 每步就地更新,投机被拒时无法直接回滚。两条策略:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      路线 A: 完整快照 (replayssm.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        每步缓存: S_t ∈ R^{H × dk × dv}


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        每步字节: H * dk * dv * sizeof (dtype)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        回滚: pop 最旧快照 → O (1) 取回,代价是存储翻倍

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        路线 B: 投影缓存 + 重演 (decode.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          每步缓存: (q_t, k_t, v_t, g_t, beta_t)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          每步字节: H * (3*dk + dv + 1) * sizeof (dtype)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          回滚:从 committed 状态用 kda_step 逐位重演 n_accepted 步 → 精确重建

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          代价比 (draft 长度在分子分母抵消):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            snapshot_cost_ratio = (H * dk * dv) / (H * (3*dk + dv + 1))

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            例: H=16, dk=32, dv=32 → 比值 = 4.0x(投影每步只需快照的 1/4 字节)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 直觉: 投影只存 "输入"(5 个小向量),快照存 "整个状态矩阵";dk*dv 越大,投影优势越明显

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 关键性质: 比值与 draft 长度无关 —"draft 越长越省" 体现在绝对字节差随 draft 线性增大

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1.2 verify_and_replay 重演一致性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            输入: committed 状态 S_0, DraftProjections (q,k,v,g,beta)[:n_accepted]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            输出: (S_new, output_stacked)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              S = S_0.clone()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              for i in 0..n_accepted‑1:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  out_i, S = kda_step(q[i], k[i], v[i], g[i], beta[i], S)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              output_stacked = stack(out_0, ..., out_{n‑1})   # (B, H, n, Dv)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 一致性保证: verify_and_replay 的输出与 kda_recurrent 对前 n 个位置的完整递推逐位一致(float64 下 max|diff| < 1e‑12)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • clone 必要性: committed 是 cache 里共享的对象,必须拷贝一份避免重演污染共享状态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              1.3 KDA 递推核心 (kda_step /kda_recurrent)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Delta Rule 递推:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                delta_t = v_t − S_{t‑1}^T k_t        # 纠错项
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                S_t     = Diag(alpha_t) · S_{t‑1} + beta_t · k_t · delta_t^T


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                读出:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                o_t = S_t^T · q_t
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • alpha_t = g_min * sigmoid(...) − 有界衰减,alpha_t ∈ [g_min, 0]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • beta_t = sigmoid(...) − 写入强度,beta_t ∈ [0, 1]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • delta‑rule vs 线性注意力: delta_t 是 "新值减去旧预测" 的纠错,而非直接加 k*v

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1.4 ReplaySSM 环形缓冲

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  push(state):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      if len(states) == capacity: states.pop(0)   # 满员覆盖最旧
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      states.append(state)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  pop() → states.pop(0)                           # 始终返回最旧快照
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • FIFO‑overwrite 语义: 满员时新状态覆盖最旧,pop() 无条件返回队首

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 为什么不用纯游标环形: 满→pop 再 push 会导致游标错位,pop 取到较新快照而非最旧(test_replayssm.py 的回归测试覆盖此场景)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • copy_from 深拷贝: 保证两环相互独立,修改一个不影响另一个

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.5 统一页池 (PagedCache)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1. PagePool:单一 free list 管理两种 page kind(MLA_KV / KDA_STATE)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  2. MLA 分页:append_mla(n_tokens)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • tokens_per_page=512,每写满 512 token 分配新页

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 页数 = ceil(n_tokens / tokens_per_page)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3. KDA 恒定:store_kda(layer, state)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 每层 KDA 状态 S (B,H,dk,dv) 固定字节,占一页

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 页数 = n_layers(与序列长度无关)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    pack_heads: (B,H,dk,dv) → flat    # 按 head 连续摊平
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    unpack_heads: flat → (B,H,dk,dv)  # 无损还原
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 统一池的价值: 两种 page 共享同一份 free list,上层只需操作 PagePool 一个对象,不必区分 "这是 MLA 页还是 KDA 页"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • pack/unpack 无损: float64 下 max|diff| < 1e‑12

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    1.6 前缀缓存:两阶段 lookup + chained hash + KDA checkpoint 原子性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    chained hash:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      H_0 = sha256("", tokens[0:512])
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      H_1 = sha256(H_0, tokens[512:1024])
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ...
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      H_i 认证 "直到该端点的整个前缀" → hit = 内容完全一致

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      两阶段 lookup:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      阶段 1 (MLA 细粒度): 从 t=0 按 hash_block_tokens=512 逐块计算 chained hash,在 index 中命中且 ready → 继续;miss → 停止

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      阶段 2 (KDA 原子性): 从最深匹配边界往回退,找到 endpoint 处每个 KDA group 都有 checkpoint → 命中,缺一个 group → 不可用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ”
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 原子性: KDA 递推状态必须整组一起恢复,只要有一个 group 缺快照,这个边界就不可复用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • chained hash vs 独立 hash: chained hash 保证 hit = 内容完全一致,不存在 "高 prefix 撞车" 歧义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • ready 标志: 异步登记时 ready=False,lookup 只认 ready=True 的块,避免 false hit

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      1.7 引擎 before/after

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        首请求: prefill 512 token → PagedCache 存 KDA page → register + persist checkpoint
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        第二请求 (命中): prefix lookup → 复用 MLA page + KDA checkpoint → reused_tokens=512
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        第二请求 (未命中): 全重算 → reused_tokens=0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        KCP 通信量:与序列长度无关 O (1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          comm_bytes = KDAContextParallel.communication_volume(B, H, dk, dv, world)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          1.8 Fleet 调度:一致哈希 + 预算隔离

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          一致哈希环:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            add_cluster(id, vnodes=8): 把 id 散布 vnodes 个虚拟节点到环上
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            route(session_id) → (primary, secondary)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              * primary: session 的 md5 顺时针落入的集群
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              * secondary: 顺移下一个不同集群 (primary != secondary) 硬约束
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • hopscotch 性质:移除 1 集群只扰动 O (1/N) 的 session

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            预算准入:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              BudgetController:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  budgets = {"short": S, "long": L}
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  weights = {"short": 1, "long": 3}
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  admit(class, usage) = usage[class] + weight[class] <= budget[class]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 隔离效果: 长突发只消耗自己的配额,短请求配额不受影响 → 短 P95 TTFT 显著更低


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              0x02 设计思路与实现细节

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2.1 文件

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              experiments/models/llm/kimi_k3/serve/gradio_serve_demo.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2.2 覆盖范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              serve 模块全部 7 个源文件、6 个测试文件,共 14 个交互 tab:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Tab

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              函数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              覆盖源文件

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              覆盖测试

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_replay_principle

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              decode.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_decode.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_snapshot_cost

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              decode.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_decode.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_replay_consistency

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              decode.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_decode.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_replayssm

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              replayssm.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_replayssm.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              5

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_page_pool

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              paged_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_paged_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              6

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_mla_paging

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              paged_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_paged_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              7

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_kda_store

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              paged_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_paged_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              8

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_prefix_hit

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              prefix_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_prefix_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              9

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_prefix_miss

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              prefix_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_prefix_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              10

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_engine_before_after

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              engine.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_demo_engine.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              11

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_fleet_hash_ring

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fleet.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_fleet.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              12

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_fleet_minimal_perturbation

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fleet.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_fleet.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              13

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_fleet_budget

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fleet.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_fleet.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              14

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fig_fleet_simulation

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              fleet.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              test_fleet.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2.3 设计决策

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 纯计算可视化:所有 tab 的数据均来自 verify_and_replay、kda_recurrent、PagePool、PrefixCache、FleetSimulator 等真实模块,无硬编码数据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • sys.path:5 级上溯至 src/ + 1 级上溯至当前目录(_THIS_DIR)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • gr.Plot:Gradio 6 内部处理 Figure -> base64,无需手动转换

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 主题:gr.themes.Soft()(移到 launch() 参数,Gradio 6 规范)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2.4 依赖

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • models.llm.kimi_k3.modules.kda_ref — kda_recurrent, kda_step

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • models.llm.kimi_k3.serve.decode — DraftProjections, verify_and_replay, snapshot_cost_ratio

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • models.llm.kimi_k3.serve.replayssm — ReplaySSM

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • models.llm.kimi_k3.serve.paged_cache — PageKind, PagePool, PagedCache, pack_heads, unpack_heads

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • models.llm.kimi_k3.serve.prefix_cache — PrefixCache, chained_hash

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • models.llm.kimi_k3.serve.engine — run_once

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • models.llm.kimi_k3.serve.fleet — ConsistentHashRing, BudgetController, FleetSimulator, Request


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2.5 运行方式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              运行demo:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                python experiments\models\llm\kimi_k3\serve\gradio_serve_demo.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                启动后访问 http://localhost:7860,14 个 tab 垂直排列,点击切换。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                运行所有测试:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                python -m pytest tests/models/llm/kimi_k3/serve/ tests/models/llm/kimi_k3/parallel/ -q

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                2.6 依赖

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • plot_utils.py — 字体配置 + 工具函数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • plot_decode_replay.py — 快照成本曲线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • plot_verify_principles.py — 成本对比 + 原理示意图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • plot_paged_cache.py — 统一页池 MLA vs KDA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • plot_prefix_cache.py — 前缀缓存命中/未命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • plot_fleet.py — 一致哈希 + 预算隔离

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • demo_engine.py — 引擎 before/after

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • tests/.../test_helpers.py — make_projection, to_batch, make_state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x03 Tab 功能说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 1 — 投机回放原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 左上:draft 阶段投影缓存 vs 完整状态的内存对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 右上:快照 vs 投影每步字节成本(随 dk 变化)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 中左:verify_and_replay 重演流程图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 中右:三种接受场景(部分/全部/零接受)的输出对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 底部:代价对比公式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 2 — 快照成本分析

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 左:比值随 dk 扩展(dv=32 固定)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 右:绝对字节差随 draft 线性增大

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 3 — 重演一致性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 三种场景下 verify_and_replay 输出与 kda_recurrent 逐位对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 状态最大差显示

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 4 — ReplaySSM 环形缓冲

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • push/pop 时序、pop 返回最旧、capacity 满覆盖、copy_from 深拷贝独立性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 5 — 统一页池

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 初始空闲、分配 KDA+MLA、释放回收的三阶段可视化

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 6 — MLA 分页

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • append_mla 跨页、pack/unpack 往返验证

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 7 — KDA 存储

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • store_kda 流程、load_kda 往返验证

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 8 — 前缀缓存命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 两阶段 lookup 流程图、chained hash 链式依赖

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 9 — 前缀缓存未命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 无 checkpoint miss、部分 checkpoint 回退

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 10 — 引擎 before/after

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 前缀命中 vs 未命中的复用 token 数、四项指标对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 11 — Fleet 一致哈希

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 环分布可视化、600 session 路由均匀性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 12 — Fleet 最小扰动

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 移除 1 集群的扰动比例、只有指向失效集群的 session 改绑

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 13 — Fleet 预算隔离

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 有/无预算隔离的短请求 P95 TTFT 对比、拒绝数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab 14 — Fleet 综合仿真

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 命中率、集群负载、TTFT 分布、汇总指标

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x04 Tab 1: 投机回放原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                展示投机解码两条回滚策略的核心设计:投影缓存(decode.py) vs 完整快照,以及 verify_and_replay 的重演流程(KDA‑Infra §4)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                3×2 六联图:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                左上 (a): Draft 阶段缓存投影而非完整状态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱状图,交替蓝色 (Blue)(状态 S)和绿色 (Green)(投影 q/k/v/g/beta)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 蓝色柱高 = 1.0(完整状态),绿色柱高 = 0.4(投影更小)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 投影每步远小于完整状态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右上 (b): 快照 vs 投影每步字节成本

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 分组柱状图,红色 (Red)= 快照 Hdkdv,绿色 (Green)= 投影 H*(3Dk+Dv+1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • X 轴 = dk 值 (16/32/64)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: dk 越大,快照与投影的字节差距越大

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                中左 (c): verify_and_replay 重演流程

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 方框箭头示意图:committed → projections [:n] → kda_step × n → 与 kda_recurrent 逐位对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 重演路径与完整递推数值一致

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                中右 (d): 三种接受场景

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 水平柱状图:部分接受 (n=2) 橙色 (Orange)、全部接受 (n=4) 绿色 (Green)、全部拒绝 (n=0) 红色 (Red)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱旁标注输出步数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 接受数决定重演步数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                底部 (e): 代价 "代价公式"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 文字框:快照每步 Hdkdv 字节 | 投影每步 H*(3Dk+Dv+1) 字节 | 比值公式 + 数值示例

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 比值与 draft 长度无关

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这是理解 K3 投机解码回滚策略的入口图。投影缓存是 K3 的核心设计选择 — 比 SGLang 的快照策略每步节省数倍内存,代价只是一次短重放 O(n_accepted) 步 kda_step。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x05 Tab 2: 快照成本分析

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                5.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                画出 draft 长度 vs 投影/快照字节比,验证比值恒定且 >1(投影永远更省)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                5.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                5.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-2
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-2

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                单图(折线图):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • X 轴 = draft 长度(1/2/4/8/16/32),Y 轴 = 投影 vs 快照字节比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么:比值是水平线(与 draft 无关),恒 ≈3.94

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                5.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                量化证明"投影缓存比快照更省"的核心论点。比值与 draft 无关说明优势来自每步字节差,而非 draft 长度。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x06 Tab 3: 重演一致性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                6.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                验证 verify_and_replay 与 kda_recurrent 在三种接受场景下的逐位一致性(float64 精度)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                6.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                6.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-3
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1×3 布局,每个子图一种场景:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 绿色(Green)边框 + "PASS": 输出一致

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 红色(Red)边框 + "FAIL": 输出不一致(不应出现)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 文字标注:场景名、输出一致判定、状态最大差(应为 ~1e‑15)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么:三种场景全部 PASS,最大差 < 1e‑12。即,三种场景 (部分/全部/零接受) 输出均与 kda_recurrent 逐位一致 最大差: 0.00e+00 (float64 精度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                6.4  三种场景构建方式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                verify_and_replay(s0, proj, n) 模拟投机解码的"草稿-验证-回滚"流程。三种场景通过**控制 n(实际接受的草稿 token 数)**构造:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                场景

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                n

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                构建方式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                验证目标

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                部分接受

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                n=2

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                让 4 个草稿 token 中只有前 2 个通过验证(其余 2 个被拒绝)→ 重演时只回滚这 2 个,S 状态也要回滚到接受第 2 个后的位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                验证"部分接受时,输出和状态都能精确回滚"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                全部接受

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                n=4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4 个草稿 token 全部通过验证 → 无回滚,输出 = 4 个 token 的完整前向,S 推进到第 4 个后的位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                验证"零回滚时输出与 kda_recurrent 完全一致"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                全部拒绝

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                n=0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4 个草稿 token 全部被拒绝 → 完全回滚,输出为空(shape 第 2 维 = 0),S 状态保持为 s0 不变

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                验证"全拒绝时 S 状态完全不变(s_replay == s0)"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                底层机制:投机解码每轮提出 4 个草稿 token,验证后决定接受 0~4 个。kda_recurrent 是"标准答案"(一次性跑完整序列),verify_and_replay 是"工程实现"(按需回滚)。三种场景覆盖全部边界情况:n=0(纯回滚)、n=4(纯前向)、0<n<4(混合),确保实现与参考一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                6.5 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这是重演策略正确性的数值证明。如果 verify_and_replay 与 kda_recurrent 不一致,投机解码的回滚路径会产生错误输出。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x07 Tab 4: ReplaySSM

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                7.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                本 Tab 验证 RawInputRing 流式 raw-input 窗口 与 SGLang ReplaySSM fold-every-commit 语义 的一致性(对应 replayssm.py 实现,SGLang server_args.py:2688-2696 与 hybrid_linear_attn_backend.py:1261-1283)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                核心验证逻辑:RawInputRing 与 decode.py 批量构造的 DraftProjections 共享同一个 verify_and_replay 重演引擎,两者在数学上完全等价——缓存内容相同(raw input (q,k,v,g,beta))、回滚结果相同(与 kda_recurrent 参考逐位一致)、差异仅在写入时机(流式 vs 批量)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                7.2 背景知识

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                SGLang ReplaySSM 不是存快照,而是 fold-every-commit: verify 期间流式存 raw input,commit 时重演 accepted prefix。 与 decode.py 投影重放共享 verify_and_replay,差异只在写入时机。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                RawInputRing(raw-input 环形窗口):SGLang ReplaySSM 的真实实现语义——投机验证期间不存完整状态快照,而是把每步 draft 的原始输入投影 (q,k,v,g,beta) 流式写入 per-slot 环形窗口;commit 时取窗口内容,用 kda_step 重演被接受前缀。与 decode.py 的 DraftProjections(批量构造载体)是同一数据的不同封装。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                fold-every-commit:SGLang 术语,指"验证期间折叠(不保存中间状态),提交时重演"。这是 KDA 投机回滚的唯一可行方案,因为 KDA 的 delta-rule 状态递推不可加、不可截断(见 kda.py 与 KCP 前缀扫描)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                7.3 设计思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 为什么这样设计实验**:采用 2×2 四联图布局,分别展示"时序行为→数据结构→正确性→成本"四个维度。左上用水平条形图展示 push/覆盖时序(直观呈现环形语义);右上用热图展示 window() 输出的 DraftProjections 布局(验证数据格式正确性);左下用双柱对比图展示两条路线的数值误差(验证数学等价性);右下用折线图展示带宽账随 draft 长度的增长趋势(验证成本优势)。本 Tab 是 serve 模块的正确性锚点,与 Tab 3(verify_and_replay 批量重演)形成"流式 vs 批量"的互补对照。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 想验证什么:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1. RawInputRing 的 push/覆盖时序符合环形缓冲语义(capacity=4 时第 4 步起窗口大小恒为 4)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  2. window() 输出的 DraftProjections 布局为 (draft, B, H, D),且第 i 行对应第 i 步 push 的数据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3. RawInputRing 与批量构造的 DraftProjections 经 verify_and_replay 后,与 kda_recurrent 参考的 max err = 0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  4. raw input 的缓存字节数恒小于假想快照,比值 = snapshot_cost_ratio

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 希望读者学到什么:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1. SGLang ReplaySSM 不是"存快照",而是"存 raw input + commit 时重演"——与 decode.py 投影重放同宗同源

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  2. RawInputRing 与 DraftProjections 是协作关系(流式写入管理器 vs 批量数据载体),不是替代关系

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 希望从图上看到什么:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 成功信号:左上 push(3) 起窗口大小恒为 4(红色);右上三行色带分明、数值逐行递增;左下两根柱子均标注"误差 = 0.00e+00";右下蓝线(raw input)始终在红线(假想快照)下方,且差距随 draft 长度线性扩大

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 失败信号:左上窗口大小超过 capacity;右上数值错乱或布局维度不对;左下误差非零;右下两线交叉或蓝线在上

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                7.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                7.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-4
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                布局:2×2 四联图。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                左上 (a):push/窗口溢出时序(capacity=4)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 图类型:水平条形图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • X/Y 轴:X 轴为"窗口中投影组数"(线性刻度,0-4);Y 轴为操作步骤(push(0) 到 push(6),自下而上)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 颜色含义:蓝色 = 窗口未满(大小 < 4);红色 = 窗口已满(大小 = 4),表示最旧投影被覆盖

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么:push(0) 到 push(2) 窗口大小从 1 增至 3(蓝色);push(3) 起窗口大小恒为 4(红色),且后续 push 不再增加——直观展示环形缓冲"满则覆盖最旧"的语义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 理想情况:前 3 根蓝色条形高度递增,第 4 根起转为红色且高度恒为 4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 异常指示:若窗口大小超过 4,或红色条形高度不恒定,说明 capacity 控制逻辑有 bug


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右上 (b):window() → DraftProjections 布局

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 图类型:热图(heatmap)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • X/Y 轴:X 轴为"H × D 展平"(0-5,对应 H=2 × D=3);Y 轴为"draft 步"(第 0 步、第 1 步、第 2 步)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 颜色/数值含义:viridis 色阶,单元格内白色数字为实际值。第 0 步全为 0,第 1 步全为 1,第 2 步全为 2(代码中刻意用 torch.full(..., float(i)) 填充,便于验证布局)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么:三行色带分明(紫→青→黄),数值严格逐行递增;每行 6 个单元格(H=2 × D=3 = 6),验证 DraftProjections.q 的形状为 (draft=3, B=1, H=2, D=3)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 理想情况:色带整齐、数值与步数一一对应、X 轴单元格数 = H × D

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 异常指示:若色带混杂、数值跳跃、或单元格数不对,说明 window() 的 torch.stack 布局有 bug


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                左下 (c):RawInputRing vs 投影重放:共享重演引擎

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 图类型:双柱对比图(占位柱,因误差为 0 无法显示高度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • X/Y 轴:X 轴为两条路线("批量构造 (decode.py)" vs "RawInputRing (replayssm.py)");Y 轴为占位(误差为 0,无实际刻度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 颜色含义:浅蓝柱 = decode.py 批量构造;浅红柱 = RawInputRing 流式写入。柱内绿色文字标注"误差 = 0.00e+00"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么:两根柱子内均显示"误差 = 0.00e+00"——这是最关键的正确性信号,证明两条路线经 verify_and_replay 后与 kda_recurrent 参考逐位一致

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 理想情况:两柱等高(占位),内部文字均为绿色"误差 = 0.00e+00"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 异常指示:若任一柱内文字非零、或显示红色/警告色,说明重演逻辑或数据传递有 bug


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右下 (d):带宽账:raw input vs 假想快照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 图类型:双折线对比图(带填充区域)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • X/Y 轴:X 轴为"draft 长度"(1-8,线性刻度);Y 轴为"缓存字节数 (B)"(0-8000+,线性刻度)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 颜色/线型含义:蓝色圆点线 = raw input (q,k,v,g,beta);红色方块线 = 假想快照(完整状态 S)。两线之间粉色填充区域表示成本差距

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么:蓝线始终在红线下方,且差距随 draft 长度线性扩大;右下角注释框标注"快照是 raw input 的 1.94 倍"(H=2, dk=8, dv=8, fp64)及"KDA 的 per-channel gate 让差距更大"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 理想情况:蓝线斜率 < 红线斜率,两线间距随 X 增大而扩大,填充区域清晰可见

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 异常指示:若两线交叉、或蓝线在上、或比值注释与 snapshot_cost_ratio 计算结果不符,说明成本模型有 bug

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                7.6 调节建议

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 想看环形覆盖的临界行为 → 调 capacity 到更小值(如 2),观察 push(1) 起即出现红色

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 想看不同 H/D 下的布局 → 调 _make_projections 的 h/dk 参数,观察右上热图 X 轴单元格数变化

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 想看更大 draft 下的带宽差距 → 调 draft_lens 范围到 16 或 32,观察右下两线分离程度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                7.7 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                本 Tab 是 KDA 投机解码正确性的主锚点。它验证了 RawInputRing 与 decode.py 批量构造在数学上的完全等价性——如果左下误差非零,说明 verify_and_replay 的重演逻辑或 RawInputRing 的数据封装有 bug,将直接导致在线投机解码产生错误输出。同时,右下的带宽账从工程角度论证了"为什么必须走 raw-input 路线而非快照路线":KDA 的 per-channel gate 让完整状态矩阵的存储成本随 dk·dv 乘积膨胀,而 raw input 仅随 3dk+dv+1 线性增长。若错误地采用快照方案,在大 batch、长 draft 的生产环境中,状态深拷贝的带宽开销将抵消投机解码的全部收益。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x08 Tab 5: 统一页池

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                展示统一页池中 MLA 页随序列长度线性增长 vs KDA 恒定一页(KDA‑Infra §2)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-5
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-5

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                单图(log‑log 折线图):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 蓝色(Blue)折线:MLA 占用 page 数 vs 序列长度(512/1024/4096/16384/65536)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 橙色(Orange)虚线:KDA 一层固定 1 page(水平线 y=1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • X 轴 = 序列长度(tokens),Y 轴 = 页池 page 数,双对数刻度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么:MLA 是斜率=1 的直线(线性增长),KDA 是水平线(恒定)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                量化展示混合架构下两种注意力的内存增长行为差异。统一页池让两种 page 共享同一份 free list,上层不必区分类型。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x09 Tab 6: MLA 分页

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                展示 MLA 按 token 分页跨页 + pack_heads/unpack_heads 无损往返。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-6
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-6

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1×2 布局:左图:append_mla(600), tokens_per_page=512

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱状图,X 轴 =Page #id,Y 轴 =filled(token 数)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 红色(Red)虚线:页容量 512

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱旁标注 "512/512" 和 "88/512"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么:600 token 跨 2 页,第一页满 512,第二页 88

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图:pack_heads / unpack_heads 无损往返

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 文字标注:原始形状 → pack → flat 形状 → unpack → 还原形状

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 最大差 + PASS/FAIL 判定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么:往返最大差 < 1e‑12,PASS

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                MLA 分页是 PagedAttention 语义的基础。pack/unpack 无损是跨节点传输和页池存储正确性的前提。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x10 Tab 7: KDA 存储

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                10.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                展示 KDA 状态 store_kda / load_kda 的无损往返。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                10.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                10.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-7
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-7

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1×2 布局:左图:store_kda: (B,H,dk,dv) → flat → page.data

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 文字标注:state 形状 → pack → flat 形状 → 写入 page.data

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 底部灰色文字:后续为 pad 零

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图:load_kda 往返验证

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 蓝色(Blue)文字:load_kda → 还原形状

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 绿色(Green)/红色(Red)文字:最大差 + PASS/FAIL

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么:往返最大差 < 1e‑12,PASS

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                10.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                KDA 状态的 store/load 是投机解码回滚和前缀缓存 checkpoint 持久化的基础。如果往返有损,恢复出的状态会偏离正确值。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x11 Tab 8: 前缀缓存命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                11.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                展示前缀缓存两阶段 lookup 流程 + chained hash 链式依赖(KDA‑Infra §2 双粒度)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                11.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                11.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-8
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-8

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1×2 布局:左图:两阶段 lookup 流程

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 方框箭头示意图:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 蓝色(Blue): 阶段 1 MLA chained hash 逐块匹配

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 橙色(Orange): 候选边界 [512, 1024, ...]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 紫色(Purple): 阶段 2 KDA 从最深回退找 checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 红色(Red): MLA miss → break

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 黄色(Yellow): checkpoint 原子性检查

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 绿色(Green): hit! matched_tokens

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 两阶段串行,阶段 2 从阶段 1 的最深匹配往回退

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图:chained hash 链式依赖

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 文字标注:H1 = sha256("", [0..511]), H2 = sha256(H1, [512..1023])

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • "H2 depends on H1 → entire prefix"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 底部:H1 前 12 位 hex

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: chained hash 保证 hit = 内容完全一致

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                11.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                前缀缓存是 K3 服务层的关键优化—1M 上下文下 prefix 400K,命中一次避免重算整个前缀,比 miss 便宜几个数量级。两阶段 lookup 是混合架构(KDA+MLA)的必然选择。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x12 Tab 9: 前缀缓存未命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                12.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                展示前缀缓存两种未命中场景:无 KDA checkpoint → miss,部分 checkpoint → 回退到最近可用边界。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                12.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                12.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-9
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-9

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1×2 布局:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                左图:场景 1 * 无 KDA checkpoint → miss

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 红色(Red)边框

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 文字: matched: 0, checkpoint: None

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • "hit: False → 必须从头重算"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 没有 checkpoint 时即使 MLA hash 匹配也无法复用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图:场景 2 * checkpoint 仅在 512 → 回退到 512

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 橙色(Orange)边框

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 文字: matched: 512, checkpoint: 512

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • "阶段 1 匹配到 1024,但 1024 无 checkpoint → 回退到 512"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 原子性约束导致回退—1024 处缺 checkpoint 则不可用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                12.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                理解未命中场景是调试前缀缓存命中率的关键。无 checkpoint 和部分 checkpoint 是生产环境最常见的两种 miss 原因。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x13 Tab 10: 引擎 before/after

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                13.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                收官汇总:多请求共享前缀时,前缀缓存到底省了什么—reused_tokens、MLA KV 线性 vs KDA 恒定、KCP 通信量 O(1)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                13.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                13.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-10
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-10

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1×3 布局:左图 (a): prefix‑cache reuse of 2nd request

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱状图: without_prefix (reused=0) vs with_prefix (reused=512)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱旁标注数值

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 命中时第二请求免重算 512 token

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                中图 (b): KV cache vs KCP comm

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 双折线(semilogx): MLA KV (linear) 随序列增长,KDA KCP (constant) 水平

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: KCP 通信量与序列长度无关

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图 (c): KCP comm is O(1) in length

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 单折线(semilogx): KCP 通信量水平线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: KCP 通信量恒定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                13.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这是前 4 个子系统的收官汇总—量化回答"第二个请求复用前缀时到底省了什么"。reused_tokens=512 vs 0 是前缀缓存收益的直接度量。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x14 Tab 11: Fleet 一致哈希

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                14.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                展示一致哈希环的虚拟节点分布 + 600 session 路由分布均匀性(K3 报告 §5.4.3)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                14.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                14.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-11
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-11

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1×2 布局:左图:一致哈希环分布(8 集群 × 8 vnodes)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 圆环散点图,8 种颜色对应 8 个集群

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 每个集群 8 个虚拟节点均匀散布在环上

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 虚拟节点在环上分布均匀

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图:600 session 路由分布

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱状图,8 根柱对应 8 个集群,Y 轴=session 数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 灰色虚线:均匀线 (75)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 各集群 session 数接近 75,分布均匀

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                14.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                一致哈希是 cache‑aware affinity scheduling 的基础—session 稳定路由到持有其 prefix cache 的集群。均匀分布保证负载均衡。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x15 Tab 12: Fleet 最小扰动

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                15.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                验证一致哈希的 hopscotch 性质:移除 1 集群只扰动 O(1/N) 的 session。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                15.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                15.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-12
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-12

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1×2 布局:左图:移除 c3 后扰动

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱状图:绿色(Green)=未扰动,红色(Red)=扰动

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱旁标注数值

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 扰动数 ≈ 600/8 = 75(理论 12.5%),远小于总数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图:移除 c3 后无 session 指向 c3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 绿色(Green)文字:指向 c3 的 session: 0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 蓝色(Blue)文字:改绑比例 = X%(理论 ~1/8 = 12.5%)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 失效集群不再接收任何 session

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                15.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                最小扰动是 failover 可预期性的基础—集群故障时只有绑定到该集群的 session 需要改绑,re‑prefill 工作量被均匀分散到全 fleet。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x16 Tab 13: Fleet 预算隔离

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                16.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                展示预算隔离前后短请求 P95 TTFT 的差异(K3 报告 §5.4.3)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                16.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                16.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-13
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-13

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1×2 布局:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                左图:长突发混流 − 隔离后 P95 反而更糟

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 分组柱状图:红色(Red)=无预算(全通),绿色(Green)=预算隔离

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • X 轴 = 请求类(short/long),Y 轴 = P95 TTFT

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 隔离后 short 的 P95 ≈ 2,001,000,反而高于无隔离时的 ~6.0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 原因: 预算隔离把大量请求拒绝了(short 拒绝 52 个,long 拒绝 14 个),被拒绝的请求 P95 TTFT 被计为无穷大(或极大值),拉高了整体 P95

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图:预算隔离 − 短请求被拒绝更多

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱状图:rejected(long)=14 和 rejected(short)=52

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 短请求被拒绝 52 个,远多于长请求的 14 个——这与"短请求零拒绝"的宣称完全相反

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 原因: short_budget=8 意味着同时只能有 8 个 short 请求在飞,而场景提交了 60 个 short 请求,超额的 52 个全部被拒绝;long_budget=8 只提交了 20 个 long,所以只拒绝 14 个

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                真正的预算隔离机制:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • short_budget / long_budget 是并发上限,不是"保护短请求"的配额

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 当某类请求超过并发上限时,超额部分直接被拒绝(不是排队等待)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 这个 demo 的参数设置(short_budget=8 vs 60 个 short 请求)故意制造了大量拒绝,用来演示"限流"行为,而不是"保护短请求"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                实际行为是:预算隔离通过拒绝超额请求来保护系统容量,而不是通过"优先服务短请求"来降低短请求延迟。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                16.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                生产流量混着短请求和超长请求,长度横跨 3 个数量级。预算隔离保证长突发不拖累短请求的 TTFT。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x17 Tab 14: Fleet 综合仿真

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                17.1 目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Fleet 综合仿真:8 集群、20 long + 50 short 请求,产出命中率/代价/P95 TTFT/负载均衡/failover 汇总指标。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                17.2 UI 组件与参数影响

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无参数,页面加载时自动运行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                17.3 输出图解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-14
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tab-14

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1×3 布局:左图:命中率 + 集群负载分布

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 柱状图,X 轴=集群 id,Y 轴=累计负载

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 标题显示命中率

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 各集群负载接近均匀

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                中图:TTFT 分布(short)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 直方图,X 轴=TTFT,Y 轴=频次

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 红色(Red)虚线:P95 TTFT

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: P95 TTFT 越低越好

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图:汇总指标

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 文字列表:命中率、总代价、短/长 P95 TTFT、拒绝数、Failover 数、负载标准差

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 你该看什么: 命中率 > 0、负载标准差小(均衡)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                17.4 为什么重要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这是 Fleet 层的端到端验证—命中率、P95 TTFT、负载均衡、failover 四个维度的汇总指标直接反映服务层质量。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x018 验证策略总览

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Tab

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                测试函数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                验证点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                通过标准

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                投机回放原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_verify_replay_partial_matches_full_recurrence

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                verify_and_replay 部分接受与 kda_recurrent 一致

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                2

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                快照成本

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_snapshot_cost_ratio_exceeds_one_and_grows_with_state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                比值 >1 且随 dk*dv 增大

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                重演一致性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_verify_replay_accept_all_matches_full

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                全部接受与完整递推一致

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                重演一致性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_verify_replay_reject_zero_is_identity

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                零接受 = 原状态不变

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ReplaySSM

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_ring_evicts_oldest_at_capacity

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                满员覆盖最旧

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ReplaySSM

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_pop_after_refill_returns_oldest

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                满pop→push→pop仍返回最旧

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ReplaySSM

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_copy_from_is_deep_and_independent

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                深拷贝独立

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                5

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                统一页池

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_append_mla_increments_pages_across_boundary

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                600 token 跨 2 页

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                6

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                MLA 分页

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_pack_unpack_roundtrip

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                pack→unpack 无损

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                7

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                KDA 存储

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_store_and_load_roundtrip

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                store→load 无损

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                前缀命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_register_then_lookup_at_same_prefix_hits

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                同前缀命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                前缀命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_two_stage_uses_longest_checkpoint_boundary

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                两阶段回退到有 checkpoint 的边界

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                前缀未命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_lookup_without_checkpoint_misses

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                无 checkpoint → miss

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                前缀未命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_checkpoint_atomic_across_groups

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                原子性:缺一个 group → 不可用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                10

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                引擎

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_engine_returns_hit_stats

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                命中时 reused=512

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                10

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                引擎

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_engine_miss_returns_zero

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                未命中时 reused=0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                11

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Fleet 哈希

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_ring_distributes_sessions_uniformly

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                路由分布均匀

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                12

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Fleet 扰动

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_remove_cluster_only_affects_few_sessions

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                移除 1 集群扰动 < 60%

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                13

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Fleet 预算

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_budget_isolates_long_burst_from_short

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                长满不影响短准入

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                14

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Fleet 仿真

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                test_simulator_routes_to_primary_on_hit

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                同 session 第二请求命中



                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                TransFormer-封面
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                TransFormer-封面

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                阅读原文

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                跳转微信打开

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                •  

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                【轻量化复刻大模型 / KIMI K3】KDA Serving 基础设施 — 设计 / 实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                罗西的思考 2026-11-06 15:27 北京

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                【轻量化复刻大模型 / KIMI K3】KDA Serving 基础设施 — 设计 / 实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x00 概要
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0.1 主要内容
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0.2 注意说明
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x01 先懂 KDA:为什么它会颠覆 serving
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 1.1 从最朴素的「KV 缓存」说起
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 1.2 KDA 把这张清单换成了一个「状态矩阵」
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 1.3 关键:`M` 是「逐 token 相关」的矩阵
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 1.4 释疑
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x02 总纲:三个天然属性如何变成三层 Infra
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 2.1 为什么要做这一套
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 2.2 范围与边界(本项目做了什么 / 刻意没做什么)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 2.3 术语
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x03 实现全貌
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 3.1 总览图
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 3.2 组件数据流
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 3.3 组件快速浏览
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x04 组件一:统一页池
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 4.1 它要解决什么问题
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 4.2 难在哪
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 4.3 总体思路
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 4.4 落地架构(类 / 函数 / 数据结构)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 4.5 数据流 / 执行流
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 4.6 反方辩手(自我质疑)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 4.7 何时用 / 何时不用
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 4.8 可视化:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x05 组件二:双粒度前缀缓存
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.1 它要解决什么问题
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.2 难在哪
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.3 总体思路
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.4 背后的原理
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.5 关键:group 到底是用来做啥的?
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.6 checkpoint 的原子性与「all()」的含义
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.7 落地架构与数据结构
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.8 数据流 / 执行流(lookup 的两段式)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.9 反方辩手
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.10 何时用 / 何时不用
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.11 对比:SGLang 是如何处理 KDA prefix cache 的?
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 5.12 可视化
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x06 组件三:投机解码 · 投影重放(decode.py)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 6.1 要解决什么问题
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 6.2 难在哪
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 6.3 一个推测解码例子
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 6.4 总体思路
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 6.5 背后的原理
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 6.6 落地架构与数据结构
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 6.6 数据流 / 执行流
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 6.7 反方辩手
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 6.8 何时用 / 何时不用
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 6.9 可视化
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x07 组件四:投机解码 · RawInputRing 环形缓冲(replayssm.py)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 7.1 问题所在
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 7.2 SGLang ReplaySSM
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 7.3 总体思路
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 7.4 背后的原理
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 7.5 落地架构与数据结构
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 7.6 何时调用
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 7.7 关键对比:投影重放 vs RawInputRing —— 两条路线各在何时适用
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 7.8 示例
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 7.9 可视化
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x08 组件五:KDA 上下文并行(KCP)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 8.1 它要解决什么问题
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 8.2 难在哪
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 8.3 总体思路
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 8.4 背后的原理
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 8.5 落地架构与数据结构(parallel/kcp.py)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 8.6 数据流 / 执行流
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 8.7 反方辩手
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 8.8 何时用 / 何时不用
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 8.9 实测数值(CPU 可复现)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 8.10 验证
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x09 组件六:Fleet 层调度(serve/fleet.py)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 9.1 它要解决什么问题
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 9.2 难在哪
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 9.3 总体思路(两个策略)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 9.4 背后的原理
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 9.5 落地架构与数据结构
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 9.6 数据流 / 执行流
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 9.7 反方辩手
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 9.8 何时用 / 何时不用
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 9.10 可视化
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0x10 收官引擎:把它们咬合成一个「第二个请求到底省了什么」
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 10.1 它要解决什么问题
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 10.2 总体思路与原理
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 10.3 落地与实测
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 附录 A:跨仓库核对 — group 语义与每层状态的归属
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • A.1 kimi3-master(本项目镜像的来源)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • A.2 kimi-k3-pytorch-main(模块化参考)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • A.3 SGLang K3 分支(生产实现)—— 前缀复用的事实真相
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • A.4 合成的结论
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 附录B: 与 vLLM KV Cache Group 的对比
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • B.1. 项目中的 `group` 是什么
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • B.2. vLLM 中的 `KVCache Group` 是什么
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • B.3. 逐项对比
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • B.4. 两者为什么容易被认为相同
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • B.5. 最接近的对应关系
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • B.6. 关键差异:checkpoint 原子性 vs. 物理 cache 管理
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • B.7. 最终判断
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x00 概要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0.1 主要内容

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这份文档写给谁:给想理解「Kimi Delta Attention(KDA)这种新注意力,到底把整个 serving(推理服务)体系颠覆成了什么样」的人。假定你知道一些 Transformer,但完全不懂 KDA 的服务端细节——我们从最朴素的问题出发,一路讲到每一层基础设施为什么要那么设计。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                serving 相关的主要组件如下:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 页池把「两类异构缓存」归一成同一种「页 + kind 标签」;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 前缀缓存只信「hash 块的整数边界 + 每个 group 都有 checkpoint」(组 = "必须一起存在"的抽象分区,默认整模型 1 组);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 投机不是「删 KV」而是「不存状态存投影、失败时重演」(或「存快照、失败时 O(1) 取最旧」);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • KCP 用「每段分解 (M̄,S̃) + 一次固定 all-gather + 前缀扫描」击穿「状态不可加」;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • Fleet 层用「亲和路由 + 一致哈希双绑定 + 预算隔离」把命中率和故障、长短流都管起来;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 收官引擎把它们串成一个「第二个请求到底省了什么」的 before/after。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这些"因固定状态而生的 Infra 挑战"在 KCP、投机解码、前缀缓存等相关章节展开。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0.2 注意说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 项目 https://github.com/RossiLH/Model-Viz  和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x01 先懂 KDA:为什么它会颠覆 serving

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1.1 从最朴素的「KV 缓存」说起

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                标准的 Transformer 注意力(softmax attention)在服务阶段有一个叫 KV cache 的东西。它的作用是:记住已经看过的 token,这样生成下一个字时,不用把整个句子重新算一遍,只要用「记住的」K 和 V 去算就行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                KV cache 有一个朴素的特性:它是一张「逐 token 的清单」。每个位置一个条目,随句子变长而变长。正因为它是一张清单,你可以:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 按 token 索引它(第 3 个位置是什么);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 把它截断(不要后面几个);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 把它拼接(两份清单接起来);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 把它哈希复用(两条请求共享同一段前缀,直接抄)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这一整套 serving 基础设施(前缀缓存、内存池、上下文并行、投机解码的回滚)——全都是建立在「KV 是一张可以随便索引、截断、拼接的清单」这个前提上的。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1.2 KDA 把这张清单换成了一个「状态矩阵」

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Kimi Delta Attention(KDA)是 Kimi K3 混合架构(3 份 KDA + 1 份 MLA)里的主力。它不存逐 token 的 KV 清单,而是维护一个固定尺寸的状态矩阵S,每读一个 token 就原地更新一次:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  S ← M · S + β · k · vᵀ

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  其中:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    M = (I − β k kᵀ) · Diag(α)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这里 k, v 是当前 token 的 key 和 value,α 是逐通道衰减,β 是门控。这就是论文 Eq.1 的 delta rule(δ 规则)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    为什么是固定状态而不是 KV cache:因为核心卖点是"1M 上下文可负担"。KV cache 随 T 线性增长,KDA 状态固定 d_k×d_v/head。但固定状态带来三方面代价,也是我们整个文档反复出现的主题:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    1. 检索是压缩的(近似)→ 需要 MLA 混合。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    2. 状态跨段不可加(转移矩阵非可交换)→ 需要 KCP 前缀扫描。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    3. 状态无法简单截断回滚(整体快照)→ 需要 clone()/ReplaySSM。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    State 与 KV Cache 的硬件类比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • Linear state 像 register file: 固定大小;访问快;反复更新;容量有限。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • Full/Sparse KV 像 cache: 地址明确;容量更大;读写更依赖带宽和缓存命中;可以共享 prefix。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 模型架构和芯片内存系统因此是共同设计问题。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    1.3 关键:M 是「逐 token 相关」的矩阵

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这是整个故事的源头。注意 M 里有一个 − β k kᵀ,它依赖当前的 k。也就是说:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    每次状态更新,不是简单「往清单末尾加一行」,而是先拿一个跟当前 token 有关的矩阵,把旧状态整体缩放一遍,再加一条新记录。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这带来几个让 serving 工程师头疼的「天然属性」,正是它们,把上面那套「建立在清单前提上」的基础设施全部作废:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    #

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    状态的天然属性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    它把哪个「清单前提」击穿了

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    需要的新基础设施

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    A固定尺寸

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    (S 不随序列变长,每请求一份)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    内存池假设「KV 随 T 增长、逐 token 分页」

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    统一页池:让两种缓存共用一套内存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    B整体不可分割

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    (状态是一团,不能按 token 截断/拼接/哈希)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    前缀缓存假设「前缀可逐 token 哈希复用」

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    双粒度前缀缓存 + KDA checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    C原地更新不可回滚

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    (没有「删最后几个」这种操作)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    投机解码假设「验证失败可以回滚 KV」

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    投影重放 / ReplaySSM 快照回滚

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    C'跨段不可加

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    (每段都先被各自的 M 缩放)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    上下文并行假设「各段自状态直接求和」

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KCP 前缀扫描

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这份文档,就是依次解决 A、B、C、C',再加上把这些组件调度起来的 fleet 层。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    通俗解释:普通注意力让服务器「记账本」,KDA 让服务器「算一个不断被改写的滚动数字」。以前所有「翻到第几页」的技巧都不能用了,你得发明新的。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    1.4 释疑

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Q1:KDA 的"状态"到底包含哪几部分?decode 时每一步都在更新什么?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA 每一层的解码状态(在本项目里由 KDACache 承载)其实不只一块状态矩阵,而是由四块东西拼起来的:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    1. state:(B, H, dk, dv) 的递推矩阵 S——这是 KDA 与 MLA 最本质的差别,delta rule 的核心,随每步 S ← M·S + β·k·vᵀ 原地更新。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    2. conv_q / conv_k / conv_v:三条 ShortConv 的滑动窗口——每条形状 (B, k_dim/v_dim, kernel-1)(kernel 通常 = 4),存着"前 kernel-1 个 token 的 q/k/v 投影输入",每步把当前 token 推进窗口、最老那个滑出去。ShortConv 给无位置编码的 KDA 注入 token 级"位移"信息,是位置编码的替代。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    所以完整地说,KDA 的"cache"是一份状态矩阵 + 三个卷积窗口。它们每 token 都在推进,都是 decode 不能丢的状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Q2:为什么"KDA 状态会随着 decode 继续更新"?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这话听起来是废话,但它恰好是 KDA 颠覆整个 serving 栈的根因:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 对 MLA(Gated MLA / softmax 注意力),decode 时 KV cache 的动作是追加——每生成一个 token,往末尾追加一行新的 K/V。前面已有的 KV 原封不动。所以"回滚到第 n 步" = 把末尾若干行删掉,"截断/拼接/哈希复用" = 对清单做列表操作。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 对 KDA,decode 时状态的动作是原地改写——S ← M·S + β·k·vᵀ,每走一步,整张矩阵的每个元素都被缩放 + 叠加新记录。前面"曾经的"状态没有任何痕迹残留。所以不存在"删最后几行"这种操作,不存在"按 token 索引旧状态"这种能力,也不存在"直接拼两段状态"这种操作。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这条性质往下传导:前缀缓存不能做逐 token 哈希(只能在稀疏边界快照整块状态)、投机解码失败不能直接回滚(只能快照或重演)、上下文并行不能直接相加(必须前缀扫描重组)、内存池不能再按 token 分页(得把状态当整块来管)——这篇文档后面所有组件,全都是从这个"状态是原地更新的整体"这一条性质长出来的。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    0x02 总纲:三个天然属性如何变成三层 Infra

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这一节把全文的因果链先立起来。下面的表 ——每个基础设施层 = 状态的一个「不适配」 + 一个「工程解法」:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    基础设施层

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    softmax/KV 的假设

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA 状态的不适配

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    工程解法

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    内存池

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KV 逐 token 分页、随 T 增长

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    S 固定大小、每请求单份;且与 MLA KV 异构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    统一页池

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    :byte 对齐,KDA 页 + MLA 页共用一套 alloc/evict

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    前缀缓存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    前缀可逐 token 哈希复用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    状态是整体,只有稀疏边界可快照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    双粒度解耦

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    :512-token hash 块(MLA 细粒度)+ KDA checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    上下文并行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    各段 KV 可直接拼接

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    状态跨段不可加(M 逐 token 相关)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KCP

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    :每段分解 (M̄, S̃),一次固定 all-gather + 前缀扫描

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    decode/投机

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KV 可逐 token 截断回滚

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    S 原地更新无法回溯

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    缓存投影而非状态;失败时重放

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    集群调度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    传统负载均衡

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    前缀缓存 miss 比 hit 贵几个数量级

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Fleet 层

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    :亲和路由 + 预算隔离

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    一句话总纲:KDA 的 serving 设计,本质是把状态 S 的三种天然属性(固定 / 整体 / 原地更新)系统性转换成对应的基础设施机制。没有哪一层是「顺带就能支持」的——每一层都要针对性改造。这就是 K3 报告把 算法-系统协同设计(algorithm–system co-design) 列为关键基础设施创新的原因。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    2.1 为什么要做这一套

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    K3 = 3 份 KDA + 1 份 MLA 的混合架构(每个 block 内 3 层 KDA + 1 层 Gated MLA)。任何 serving 引擎都必须同时管理两种根本不同的缓存:MLA 的 KV(逐 token、随 T 增长)和 KDA 的状态 S(固定、每请求一份)。它们物理性质完全不同,却要共享同一台机器的显存/内存、走同一套分配/淘汰/传输机制。这是 K3 与所有「纯 softmax」模型最大的工程差异。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    2.2 范围与边界(本项目做了什么 / 刻意没做什么)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    做了(6 个组件,全部 CPU 可运行、可测试、有 before/after 可视化):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    1. 统一页池(models/llm/kimi_k3/serve/paged_cache.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    2. 双粒度前缀缓存(models/llm/kimi_k3/serve/prefix_cache.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    3. 投机解码·投影重放(models/llm/kimi_k3/serve/decode.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    4. 投机解码·ReplaySSM 环形缓冲(models/llm/kimi_k3/serve/replayssm.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    5. KDA 上下文并行 KCP(models/llm/kimi_k3/parallel/kcp.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    6. Fleet 层调度(models/llm/kimi_k3/serve/fleet.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    刻意没做:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 不做真实多机通信 / TP / DP 调度(KCP 用单进程分段模拟 world 个 rank);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 不做 Triton/GPU 内核分发;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 不做真实 1M token 计算(代价用公式折算成时间);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 不做 WebSocket 实时前端。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    为什么这些「没做」仍值得写?因为原理正确性与工程形态是两回事。我们要证明的是「这套设计在数学上成立、在代码上可复现」,而不是「能跑到多快」。CPU 上能逐位对拍出正确性,就已经把设计讲明白了。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    2.3 术语

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    术语

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    S(状态)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA 的递归状态矩阵 (B,H,dk,dv),固定尺寸,每 token 原地更新

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    M(过渡矩阵)(I − β k kᵀ)Diag(α)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ,逐 token 相关,先缩放旧状态再加新记录

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA group

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    一组 KDA 层的集合(组件二详解:为什么是「组」而不是「层」)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    在某个稀疏边界上把当时的 S 快照下来,用于跳过递推

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    投影(projection)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    投机的每 draft token 的 (q,k,v,g,β) 输入(远小于整个状态)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    replay / 重演

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    用已接受的投影,从已提交状态重新跑 kda_step,得到正确状态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ReplaySSM

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    SGLang 的快照路线:环形缓冲存最近若干状态快照,回滚时直接取

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KCP

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA 上下文并行:把序列分段,用前缀扫描重组各段入态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    fleet

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    一组 serving 集群(默认 8 个)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    P95 TTFT

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    time-to-first-token(首个 token 的延迟)的 95 分位


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    0x03 实现全貌

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    3.1 总览图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    先给一张总览图。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    总览图
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    总览图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    3.2 组件数据流

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    我们再看看「这六个东西为什么放在一起、数据怎么流」:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    组件数据流
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    组件数据流

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    依赖方向(单向,不反向 import):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      paged_cache.py(基础,无依赖)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↑
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      prefix_cache.py(依赖 paged_cache 的物理块 id)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↑
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      decode.py(投影重放)  ← 与 replayssm.py(快照)互为对照的两种策略
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↑
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      kcp.py(上下文并行,独立,依赖 kda_ref 的 kda_chunkwise)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↑
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      fleet.py(调度,复用 prefix_cache + paged_cache)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↑
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      engine.py / demo_engine.py(收官汇总,依赖全部)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      3.3 组件快速浏览

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Q1:这个组件在解决什么「真问题」?(不是「实现了什么功能」,而是「不解决会怎样」)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 页池:两种缓存怎么共用一块内存?(不解决 → 内存割裂浪费)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 前缀缓存:状态不可分割,怎么复用前缀?(不解决 → 每个请求重算 400K)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 投影重放 / ReplaySSM:投机失败怎么恢复状态?(不解决 → 投机不成立,或快照成本吃掉收益)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • KCP:状态不可加,怎么并行?(不解决 → 长序列没法跨设备并行)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • Fleet:命中率与故障怎么两全?(不解决 → miss 贵几个数量级 / 集群一挂全断)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Q2:这个组件的「核心机制」一句话是什么?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 页池:字节层归一化 + 一个 free list + kind 标签

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 前缀缓存:双粒度(MLA hash 块 + KDA checkpoint)+ 两段式 lookup + group 原子性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 投影重放:不存状态存投影,失败时重演

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • ReplaySSM:环形缓冲存快照,失败时 O(1) 取最旧

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • KCP:每段分解 (M̄,S̃) + 一次固定 all-gather + 前缀扫描

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • Fleet:亲和路由 + 一致哈希双绑定 + 预算隔离

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Q3:这个组件的「边界 / 何时不用」是什么?(识别滥用场景)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 页池:纯 softmax / 纯 KDA 时退化成单种页

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 前缀缓存:无共享前缀时是纯开销

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 投影重放 vs ReplaySSM:状态宽/长 draft 选重演,状态窄/短 draft 选快照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • KCP:短序列时通信是浪费

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • Fleet:单实例 / 无共享前缀时退化

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      下面从底层往上,一章一个组件。每个组件都按同一套模板讲:① 它要解决什么问题 → ② 难在哪 → ③ 总体思路 → ④ 背后的原理 → ⑤ 落地架构(类/函数/数据结构)→ ⑥ 数据流/执行流 → ⑦ 反方辩手(自我质疑)→ ⑧ 何时用/何时不用。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      0x04 组件一:统一页池

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      K3 把缓存看成 MLA KV + KDA recurrent/convolution state 的联合对象;以共同前缀边界保存 checkpoint;区分稳定共享副本和请求活动副本;在缓存预算内选择值得保存的恢复点。核心是把缓存键从 "token prefix" 升级为包含模型版本、tokenizer、前缀边界和多种状态的联合键。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      4.1 它要解决什么问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      K3 一个请求要同时存两种完全不同的东西:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • MLA 的 KV:随序列变长,像一条会增长的清单;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • KDA 的 S:固定尺寸,每请求一份(每个 KDA 层一份)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      它们占同一块显存/内存,但「长得」完全不一样。传统 serving 引擎会为每种缓存各开一块内存(一份 KV 池、一份状态池)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      问题:两块池子边界固定,浪费(某时 KV 挤爆、状态闲置),而且每次 load/store/evict 要分别处理,代码重复。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      4.2 难在哪

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      难在**「异构」**:一个按 token 增长、一个固定尺寸;一个内容是 latent_kv、一个是状态矩阵。你怎么让两个「性格完全不同」的东西,共用一套内存管理代码,还不互相踩踏?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      4.3 总体思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      在字节层面把它们「归一化」成同一种东西——页(page)。把所有缓存切成固定字节宽度的页,页上贴一个 kind 标签(是 MLA 页还是 KDA 页),然后用同一个 free list 管理所有页的分配/释放/引用计数。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      背后的原理如下:虽然 MLA 页和 KDA 页内容结构完全不同,但在「分配/释放/引用计数」这个操作层面,它们是一样的——都是一块固定宽度的内存。只要在页上标清 kind,上层只需要对着一个 PagePool 对象操作,永远不用关心「这块是 MLA 还是 KDA」。这就是「统一」的含义。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      这个「标签」还带来了一个免费的 sanity check:两种页内容结构完全不同,任何「类型混淆」的访问都会产生明显的垃圾数据,而不是「看起来正常的数据」——零成本的布局正确性自检。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      4.4 落地架构(类 / 函数 / 数据结构)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      models/llm/kimi_k3/serve/paged_cache.py 里三个关键角色:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        PageKind (str Enum)          # 页的类型标签:MLA_KV | KDA_STATE
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Page (@dataclass)            # 一页物理内存
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │   ident     全局唯一 id(分配时从 free list 弹,释放时还回去)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │   kind      页类型(决定内容是 KV 还是状态)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │   data      固定字节宽的扁平 Tensor
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │   refcount  引用计数(共享页 / 前缀复用);归 0 的那一刻回到 free list
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │   filled    已用的元素数(load 按它切「真数据」和「补齐空位」)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        PagePool (@dataclass)        # 管理所有页:分配 / 释放 / 保留 / 利用率
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                free   —— 一个共享的 id 列表,两种页共用同一个分配池
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                allocate(kind)  → 从 free 弹 id,refcount=1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                release(ident)  → refcount 减到 0 则删页、id 还回 free
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                retain(ident)   → 显式 refcount+1(共享页)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                utilization()   → 1 - 空闲页/总页

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        配套的两个「布局转换」函数:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • pack_heads(state):把 (B,H,dk,dv) 的状态压平成一维字节流,且每个 head 的字节保持连续。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • unpack_heads(flat, heads, dk, dv):反向还原;只切 batch*H*dk*dv 个元素,把 padding 的零丢弃,保证补位值永远不进重建的状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        PagedCache 是「请求级」的视图,不独立持内存,而是指向共享的 PagePool:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • mla_pages: list[int] —— 本请求按 token 顺序的 MLA 页 id;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • kda_pages: dict[int,int] —— 层号 → KDA 页 id(每层一页);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • append_mla(n_tokens):PagedAttention 语义,当前尾页满了就新开一页,逐 token 填充;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • store_kda(layer, state):一层一页,重复写同层复用同一页(覆盖);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • load_kda(layer, ...):按 filled 切片读回,unpack_heads 还原;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • release():把所有页还回池。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        常见疑问:ShortConv 的卷积窗口(conv_q/conv_k/conv_v)也存在页池里吗?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        目前没有。本项目的 PageKind 枚举只有两值:MLA_KV 和 KDA_STATE。store_kda / load_kda 只存/取递推矩阵 S,conv_q / conv_k / conv_v 三条滑动窗口不在 paged_cache 里管理,也不在 prefix_cache 的 checkpoint 里。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        这是因为目前的 serving 实现偏"设计验证"层面,重点放在状态矩阵 S 的管理(这是 KDA 与 MLA 最本质的差别、也是最颠覆 serving 的地方)。卷积窗口只是「宽度 kernel-1 的小尾巴」,字节开销远小于 S(3 × k_dim × (kernel-1) vs H × dk × dv),工程上可以先简化处理。如果要做完整的生产级 serving,需要把三条 conv 状态也纳入页池 / checkpoint 原子性——它和 S 一样,是"必须一起恢复"的状态,只是小很多。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4.5 数据流 / 执行流

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          一次 prefill:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            请求进来 → view1 = PagedCache(pool, tokens_per_page=512)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     → view1.append_mla(512)               # MLA:512 token 铺进页(满则新页)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     → 每层 KDA: view1.store_kda(layer, S)  # KDA:一层一页,固定尺寸
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            请求结束 → view1.release()                       # 页还回池,id 回 free list

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          append_mla 的细节(为什么 is_full 是关键):PagedAttention 的核心是「KV 按 token 分页、只在页满时分配新页」。Page.is_full(tokens_per_page) 检查当前尾页是否装满,装满才 allocate 下一页——这是 MLA 侧「随 T 增长」的落地。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.6 反方辩手(自我质疑)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          「MHA 也能做成池,分页不稀罕。」 对,分页本身不稀罕。但关键是:这个池必须同时装得下「随 T 增长的 token」和「尺寸对 T 不敏感的整块状态」——这是 MLA+KDA 的独特混合,普通的 KV 桶做不到。PageKind 的双值枚举正是「两种物理性质共存于一个分配池」的体现。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          「为什么 pack_heads 要保持 head 连续,直接 flatten 不行吗?」 因为 head 是跨节点传输的最小语义单元。未来的 KCP(上下文并行)按 head 拆分通信;如果一个 head 的字节被切到不同页/不同段,传输时就要额外拼装。保持 head 连续 = 每个 head 的字节流「自包含」,可独立搬运。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.7 何时用 / 何时不用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 何时用:任何要同时管理「随 T 增长的 KV」和「固定尺寸状态」的 K3 混合 serving。这是底层,上面所有组件都建立在它之上。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 何时不用:纯 softmax 模型(没有 KDA 状态)不需要 KDA_STATE 页;纯 KDA(没有 MLA)不需要 MLA_KV 页。PageKind 的设计让这两种情况退化成「只用一种页」,依然能用同一个池。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.8 可视化:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          plot_paged_cache.py — 统一页池 (serve/paged_cache.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 表达:MLA 与 KDA 共享同一个 free list 页池,但占页规律完全不同

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 测试:PagePool + PagedCache.append_mla(L),扫描 L=512…65536,统计 MLA 页数(log-log 斜率为 1 的直线);对照 KDA 一层递归状态 S(B,H,dk,dv) 恒定 1 页(水平参考线)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 产出:plot_paged_cache.png

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          plot_paged_cache.py 产出 plot_paged_cache.png(对比 MLA 页数随 seq_len 增长 vs KDA 页数固定)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          plot_paged_cache
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          plot_paged_cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          0x05 组件二:双粒度前缀缓存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          5.1 它要解决什么问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          前缀缓存(prompt/prefix cache)解决的问题是:很多请求共享同一段 prompt 前缀(比如系统提示词、few-shot 示例、长文档开头)。如果第一个请求算过这段前缀,第二个请求能不能直接复用,而不从头重算?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          对普通 KV:能。因为 KV 是「逐 token 的清单」,只要哈希比对前缀一致,就能把整段 KV 抄过来。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          对 KDA 呢?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          5.2 难在哪

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA 的状态 S 是一个递归算出来的整体,不是一张可以逐 token 索引的清单。它有两条硬约束:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          1. S 不是按 token 可取的:要「跳过硬算」一段前缀,唯一的办法是在某个边界把当时的中间状态快照下来(checkpoint)。但 checkpoint 只能在稀疏边界存——不是每个位置都适合存。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          2. checkpoint 必须「原子」存在:状态是逐层递推的。一个 K3 block 有 3 层 KDA + 1 层 MLA。要在边界 B 处恢复状态,每一层都必须在那存了 checkpoint。少一层,就无法正确恢复。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          这里就有了「组(group)」的概念。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          5.3 总体思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          双粒度解耦:把「能安全复用的前缀」定义成两个条件的交集:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          MLA 侧逐块匹配(细粒度:512-token hash 块)+ KDA 侧每个 group 都有 checkpoint(在某个稀疏边界)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          于是 lookup 分两阶段:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 阶段一:按 chained hash 逐块匹配 MLA 侧,能走多远走多远;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 阶段二:从最深匹配边界往回退,找到一个「每个 KDA group 都存了 checkpoint」的边界,才真正命中。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          命中永远是 hash block 的端点,不要求是 physical block 的整数倍。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          5.4 背后的原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (1)chained hash 而非每块独立 hash:每一块的 digest 认证「直到该端点的整个前缀」。两个请求只要在某端点 hash 相同,就保证其前面全部 token 完全一致——不存在「前缀撞车」的歧义。命中 = 内容完全一致,无需再逐 token 比一遍。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (2)为什么 KDA 只能复用「边界上的整块状态」:状态更新 S ← M·S + β·k·vᵀ 是串行递推。要恢复 S,要么从头一路递推到目标位置,要么从一个先前存好的 checkpoint 接上继续递推。中途任何位置都没有「现成的 S」可用——所以 checkpoint 只能在「我们主动存的那些边界」存在。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (3)ready 标志:为什么注册是异步的:先登记 digest(ready=False)、后填充内容(mark_ready 置 True)。ready=False 的块参与索引但不参与 lookup——防止命中「登记过但还没填好」的假前缀。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (4)KDA Prefix Cache 为什么常在请求结尾保存?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA state 是递推结果,只有处理完某个前缀位置后才得到该位置的完整状态。保存请求结尾快照最简单:快照自治;恢复后可继续递推;不必保存每个 token 的完整中间状态。如果要支持任意中间分支,就需要更多快照或从最近快照重放。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          5.5 关键:group 到底是用来做啥的?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          先澄清一个容易误解的地方:group 不是「一层 KDA」的别名,它也不由代码强制绑定到任何具体层。在 kimi3-master(本项目对照的参考实现)里,n_kda_groups 是一个抽象的"必须共存的分区数"——意思是"一个 checkpoint 必须同时在几个 group 里都存在,这个边界才算可用"。默认 n_kda_groups=1(整个模型当 1 个 group)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          参考实现里可以这样用:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            make_cache(n_kda_groups=3)                        # 3 个抽象 group
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            cache.persist_kda_checkpoint(512, groups=[0, 1])  # 只给 group 0、1 存 → 缺 group 2,暂不可用
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            cache.persist_kda_checkpoint(512, groups=[2])     # 补上 group 2 → 才可命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            也就是说:group 是"同生共死"的那一组对象的抽象容器。它可以是"一层的状态"、可以是"一个 block 里 3 层 KDA 的状态"、也可以是"任意一组你必须一起恢复的状态"。代码不管它具体指啥——只负责"每个 group 都存了 checkpoint 才算数"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            为什么需要"必须共存"这个约束:K3 的递归状态是逐层的(每层有自己的 S_l)。要恢复"整个 block"在边界 B 的状态以继续算,每一层在 B 的 checkpoint 都得在——少一层,算出的下一 token 就是错的。所以"一起存在才算数"是硬约束。group 就是把"哪几个东西必须一起存在"打包成一个抽象单元的机制。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            5.5.1 先看清 K3 的层排布(真实 layer_schedule())

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              def layer_schedule(self):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  body = self.n_layers - 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  period = 4
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  schedule = []
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  for i in range(body):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      schedule.append("mla" if (i + 1) % period == 0 else "kda")
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  schedule.append("mla")   # 尾部再挂一个全局 MLA
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  return schedule

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              实测(脚本输出):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 16 层示例排布:[kda,kda,kda,mla] × 4 → 12 KDA + 4 MLA(3:1);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 真实 K3 规模:93 层 = 69 KDA + 24 MLA(3:1,含尾部全局 MLA)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              所以"层"是明确的:每个 block 3 层 KDA + 1 层 MLA,每个 KDA 层自己持有状态 S(B,H,dk,dv)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              5.5.2 group 是"层"吗?—— 不是,它是"对状态的分组维度"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • group ≠ Transformer 层。group 是 prefix_cache 里对 KDA 状态如何打包成原子组的分组维度,用 n_kda_groups 配置。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 每一层不一定有一个 group。两种极端:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • n_kda_groups=1(默认):全部 KDA 状态当一个整体 blob,kda_checkpoints = {0: set}——原子判定只查这一组。这正是 SGLang 的做法;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • n_kda_groups = n_kda_layers:每个 KDA 层单独一组,kda_checkpoints = {0:set, 1:set, 2:set, ...}——原子判定要求每个 KDA 层在该边界都有快照。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 无论哪种粒度,原子性的语义不变:恢复边界必须所有组齐;只是"组"的粒度可由服务方选择。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              5.5.3 为什么"层数"和"组数"分开?(设计动机)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              把"层"和"组"解耦是刻意的:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              1. 真实 K3 是 69 个 KDA 层,若强制每层一组,原子判定要遍历 69 个集合,且任何一层缺快照都会让边界作废——恢复约束过强;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2. 但 KDA 状态在语义上是"逐层递推的整体",服务方常选择整组原子(n_kda_groups=1),既能正确恢复又不会因为"某一层丢了"而全盘失效;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              3. 中间粒度(如每 block 一组)也允许——这正是"分组维度"而不是"层数"被抽象成参数的原因。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              一句话:group 不是「层」的别名,而是「同生共死」的那一组对象的抽象容器——它把"哪几个东西必须一起存在"打包成编号,checkpoint 必须"每个 group 都有"才算数,少一个就整个边界作废。默认整个模型是 1 个 group;只有当你显式把"必须一起恢复的层集合"设成一个 group 时,才和"层"发生联系。它把「状态是一个整体」这个数学事实,翻译成了「checkpoint 必须原子存在」这个工程约束。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              5.5.4 图:group vs 层示意

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              plot_group_vs_layer
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              plot_group_vs_layer

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              5.6 checkpoint 的原子性与「all()」的含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              checkpoint 的原子性,用代码表达就是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                def checkpoint_available(self, boundary: int) -> bool:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    """边界被每个 group 都有 checkpoint 才算可用。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这是「原子性」的查询面:KDA 递推状态必须整组一起恢复,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    只要有一个 group 缺快照,这个边界就不可复用。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    return all(boundary in group for group in self.kda_checkpoints.values())

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                即:边界 B 被每个 group 都有 checkpoint,才算可用;只要有一个 group 缺,这个边界就不可复用。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                上面代码逐字拆解:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • self.kda_checkpoints 是一个 dict:{KDA group 编号 → 该 group 已存 checkpoint 的边界位置集合}。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • self.kda_checkpoints.values() 取出所有 group 的集合(n_kda_groups 个 set)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • boundary in group:判断某个边界位置 boundary 是否在这个 group 的 checkpoint 集合里。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • all(...):要求每个 group 的集合里都包含 boundary,任何一个不包含就返回 False。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                为啥要 all(原子性): KDA 的递归状态 S(B,H,dk,dv) 是逐层递推的整体——它按 group(KDA 混合架构里多个并行的状态组)一起递推,各层的 checkpoint 必须同时存在才能恢复。少任何一层(group)都无法正确恢复前缀状态。所以:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 注册时 persist_kda_checkpoint 往每个 group 都登记;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 查询时 checkpoint_available 要求所有 group 都有(少一个就算"半原子状态",不可复用)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                all 是"与"语义——它是这个原子性约束的查询面。如果只用 any(任一 group 有),就可能拿到缺层的 checkpoint,前缀恢复出来是错的。正是 all 保证了命中前缀的 KDA 状态完整可恢复。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                5.6.1 图:checkpoint 原子性示意

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                plot_checkpoint_atomicity
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                plot_checkpoint_atomicity

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                左图用真实 PrefixCache(n_kda_groups=3) 构造了一个故意不齐的 checkpoint 矩阵:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 512:三个 group 都有快照 → checkpoint_available=True(可用);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 1024:只有 group 0、1 有,缺 group 2 → False;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 1536:只有 group 0、2 有,缺 group 1 → False。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                绿色"可用"字样标出了 all() 通过的两个边界,红色"不可用"标出了缺一组的边界。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图是两场景的 lookup 结果:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 场景 A(2048 全组齐):阶段一 MLA 逐 hash 块匹配到 2048,阶段二 all() 校验通过 → 命中 2048;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 场景 B(2048 抽走 group 2):阶段一 MLA 依然能匹配到 2048(MLA 侧不受影响),但阶段二 all() 在 2048 失败 → 回退到 512。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                实测数值(CPU 可复现):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  boundary=  512  checkpoint_available(all groups) = True
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  boundary= 1024  checkpoint_available(all groups) = False
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  boundary= 1536  checkpoint_available(all groups) = False
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  boundary= 2048  checkpoint_available(all groups) = True
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  [场景A] lookup matched_tokens=2048 kda_checkpoint=2048
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  [场景B] lookup matched_tokens= 512 kda_checkpoint= 512
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  一句话结论:all() 锁的是恢复的原子性:KDA 状态必须"每个 group 都有 checkpoint"才能在某个边界恢复,缺一个组该边界就作废、lookup 会回退到更浅的可用边界(实测场景 B 从 2048 回退到 512)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  5.7 落地架构与数据结构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    HashBlock (@dataclass)         # 一个 hash 块的索引条目
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        digest            链式 hash,索引 key(也是 dict 的 key)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        end_token         本块覆盖到的 token(含,块尾端点,必为 512 的整数倍)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        physical_block    该端点落在页池的哪个物理块
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ready             内容是否已填充(异步登记的 False→True)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    LookupResult (@dataclass)      # 一次 lookup 的返回值
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        matched_tokens     MLA 侧匹配到的端点 token 数
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        physical_blocks    命中的物理块 id(已去重,供上层 pin/共享)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        kda_checkpoint     命中的 KDA checkpoint 边界(None 表示没命中)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        @property hit      matched_tokens > 0


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    PrefixCache (@dataclass)       # 双粒度缓存主体
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        hash_block_tokens=512
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        physical_block_tokens=6144 (=12 个 hash block)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        n_kda_groups                KDA group 数(默认 1 = 整个模型 1 个 group)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        index: dict[str,HashBlock]  digest → 块 的倒排索引
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        kda_checkpoints: dict[int,set[int]]  group → 边界集合
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        free_list / _next_block     物理块分配

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    关键方法:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • chained_hash(previous, tokens):上块 digest + 本块 token → sha256,链式认证整个前缀。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • register(tokens):把请求前缀分成 hash 块登记进索引,返回各块 digest。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • mark_ready(digest):异步登记后内容填充完,置 ready。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • persist_kda_checkpoint(boundary, groups):在某 hash 块边界为指定(或全部)group 存 checkpoint;非 512 整数倍直接 raise,防止错误对齐的 checkpoint 污染索引。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • evict_kda_checkpoint(boundary, groups):从指定 group 移除(discard 幂等),用于部分缺少时的状态补齐或逐出。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • checkpoint_available(boundary):all(group 有 boundary),原子性查询面。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • lookup(tokens):两段式。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • recompute_saved(result, total_tokens):报告「本次真正免于重算的 token 数」,上限取 min(matched, total)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    5.8 数据流 / 执行流(lookup 的两段式)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      lookup(tokens):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         阶段一 (MLA 逐块):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          previous = ""
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          for 每个 512-token 块:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              previous = chained_hash(previous, chunk)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              entry = index.get(previous)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              if entry is None or not entry.ready:  break   # 不连续 → 停
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              candidates.append((entry.end_token, entry.physical_block))
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              # ↑ 前缀命中必须是「连续」的,中断的后继即使 hash 在索引里也不算


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        阶段二 (KDA 原子性回退):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          for (end, block) in reversed(candidates):          # 从最深往回退
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              if checkpoint_available(end):                  # 每个 group 都有 checkpoint?
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  return LookupResult(end, 去重后的物理块, end)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          return LookupResult(0, [], None)                   # 一个都没命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      为什么「命中必为 hash block 端点,却不必是 physical block 倍数」:MLA 能逐 512 块匹配,所以命中在 512 的整数倍上;而 KDA checkpoint 只要求「在每个 group 都有」这个条件满足的边界——它落在某个 hash block 端点即可,不强制是 6144(physical block)的整数倍。这就是「双粒度」:MLA 的细粒度(512)与 KDA 的稀疏边界(checkpoint)在 lookup 时取「兼容的交点」。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      具体 lookup 完整代码如下:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def lookup(self, tokens: list[int]) -> LookupResult:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """两段式 lookup:MLA 一键逐块 + KDA 回退到有 checkpoint 的边界。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            阶段一(MLA):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                从 t=0 开始按 hash_block_tokens 连续计算 chained hash,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                每个 digest 去 index 查。只要块在且 ready,就继续;
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                一旦 miss 或未就绪就立刻停止——前缀命中必须是**连续**的。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                不连续的后继 token 不属于该前缀,即使它的 hash 恰好在索引里。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            阶段二(KDA 原子性约束):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                MLA 匹配得多深并不直接决定复用有多长——还必须「最深匹配边界
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                vs 每个 group 是否有 checkpoint」。从最深匹配边界往回退,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                找到 endpoint 处 checkpoint_available 而又能覆盖前面的。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这样命中的 matched_tokens 一定落在 hash block 端点上,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                不必是 physical block 的整数倍(6144 的倍率线)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                同时收集「该前缀实际用到的物理块」——阶段 1 产出的候选块
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                集去重,供上层执行「共享这些物理块」的动作。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            previous = ""
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            candidates: list[tuple[int, int]] = []  # (end_token, physical_block)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # 阶段 1:连续哈希块(MLA 细粒度匹配)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            for i in range(0, len(tokens) - self.hash_block_tokens + 1, self.hash_block_tokens):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                chunk = tokens[i : i + self.hash_block_tokens]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                previous = chained_hash(previous, chunk)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                entry = self.index.get(previous)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                if entry is None or not entry.ready:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    break
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                candidates.append((entry.end_token, entry.physical_block))


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # 阶段 2 :从最深边界回退,找每个 KDA group 都有 checkpoint 的边界
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            for end, _block in reversed(candidates):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                if self.checkpoint_available(end):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    # 去重收集命中物理块:多个 hash block 共享同一物理块时只看一次
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    seen: list[int] = []
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    for boundary, block in candidates:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        if boundary <= end and block not in seen:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            seen.append(block)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    return LookupResult(end, seen, end)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return LookupResult(0, [], None)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        5.9 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        「Q1:physical_block / 6144 是做什么的?」 它是页池共享单元。上层(页池)需要知道「这个前缀命中了哪些物理块,我要 pin 住、让它们能被共享」。6144 = 12 个 hash block 拼一个大物理块,是页池层 share/pin 的粒度。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        「Q2:一个 group 就够了,为什么要支持多个 group?」 因为"必须一起存在"的对象不一定是整层模型。真实 K3 是 3:1 混合,一个 block 里 3 层 KDA 天然构成「必须一起存在」的约束——但那是语义上的事,代码不强制。n_kda_groups 只是"把多少组东西当作必须共存的抽象分区":默认 1(整个模型一组);如果你想让"每个必须一起恢复的层集合"各自算一组,就设成那个数,并在 persist_kda_checkpoint(..., groups=[...]) 时逐个写上。注意:代码不检查 group 对应哪层,这层映射留给调用方。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        「Q3:chained hash 会不会有碰撞?」 sha256 的碰撞概率在实际 token 规模下可以忽略;真正的保证是「链式」——每块 digest 依赖全部前缀,所以「命中=内容一致」不需要额外比对 token,这是正确性关键。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        5.10 何时用 / 何时不用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 何时用:任何「请求共享前缀」且「需要复用 KDA 状态」的 serving。命中一次,KDA 免去整段递推。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 何时不用:没有共享前缀的独立请求(每次都 miss,缓存是纯开销);纯 MLA 模型(没有 KDA checkpoint 约束,退化成纯 hash 块前缀缓存)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        5.11 对比:SGLang 是如何处理 KDA prefix cache 的?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        工业界(SGLang K3 分支)怎么给 KDA 做前缀缓存?它跟我们的 prefix_cache.py 设计有什么关系?这是一个常被问到的问题,我们把整条证据链摆出来。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        SGLang 用的是**"每请求一整份状态 + 按 chunk 对齐的稀疏快照"**,与我们的"chained-hash 逐块 + 稀疏 checkpoint"是同一思路的两套实现。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        5.11.1 图:SGLang KDA 前缀缓存机制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        plot_sglang_kda_cache
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        plot_sglang_kda_cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        右图橙色阴影就是"MLA 命中但 KDA 用不上的前缀"(对齐损失),阶梯线是 KDA 真正可续算的边界。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        5.11.2 证据链:SGLang 的具体机制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ① 状态存放:每请求一个槽的 temporal 状态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          layer_cache = self.req_to_token_pool.mamba2_layer_cache(layer.layer_id)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          conv_states = layer_cache.conv[0]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ssm_states = layer_cache.temporal          # (num_slots, heads, dk, dv)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ...
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          cache_indices = self.forward_metadata.mamba_cache_indices

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA 状态存在 mamba_cache.temporal,每请求占一个 slot,num_slots = pool_size + 1(slot 0 保留)。一个 slot 同时装下所有层——等价于我们默认的 n_kda_groups=1。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ② radix 树节点存两样东西(mamba_value)TreeNode 同时持有:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • value:该前缀端点的 MLA KV 页索引列表(逐 token、细粒度);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • mamba_value:该端点的 KDA/SSM 状态快照(整块、粗粒度,可能是 slot 索引、clone 或 int8 checkpoint)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ③ 复用边界的 chunk 对齐

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            aligned_seqlen = (result.full_kv_hit_length // self.mamba_cache_chunk_size) \
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             * self.mamba_cache_chunk_size

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            mamba_cache_chunk_size = max(chunk_size, page_size)(典型 chunk=64 / page=256 → 256)。KDA 只能从 chunk 整数倍边界续算——MLA 命中得再深,也要对齐截断。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ④ 续算前提

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              has_initial_state = forward_batch.extend_prefix_lens > 0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              命中后 extend kernel 直接从已存状态起步,不再重算前缀段。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ⑤ 写入时机:decode 时在 mamba_track_interval 边界快照(_track_mamba_state_decode),extend 时在 chunk 边界抓中间态 h(_track_mamba_state_extend),保证每次到达 radix 端点时状态恰好落在该节点。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              5.11.3 上右图实测(chunk 对齐量化,CPU 可复现)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                mamba_cache_chunk_size=256
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                full_kv_hit= 512 -> aligned= 512 (wasted=  0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                full_kv_hit= 700 -> aligned= 512 (wasted=188)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                full_kv_hit=1024 -> aligned=1024 (wasted=  0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                full_kv_hit=1100 -> aligned=1024 (wasted= 76)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                full_kv_hit=1536 -> aligned=1536 (wasted=  0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                full_kv_hit=2048 -> aligned=2048 (wasted=  0)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                5.11.4 与我们的设计对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                我们的 prefix_cache.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                SGLang

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                前缀身份

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                chained-hash 逐块认证(512-token 块)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                radix 树按 token 前缀精确匹配

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                KDA 状态粒度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                可配 n_kda_groups(默认 1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                固定整块(≈n_kda_groups=1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                恢复边界约束

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                必须是 hash block 端点且每组有 checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                必须是 mamba_cache_chunk_size 整数倍

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                原子性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                checkpoint_available = all()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                单块快照天然原子(无需 all())

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                对齐损失

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                回退到更浅的可用边界

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                截断到 chunk 整数倍

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                一句话总结:SGLang 的 MLA 走逐 token 页缓存、KDA 走"每请求一槽 + chunk 对齐稀疏快照",两者共用一棵 radix 树,但 KDA 侧不做逐 token 索引;而我们的设计用 chained-hash 认证前缀身份 + 每 group 原子 checkpoint,更偏"内容寻址"风格。本质是同一套思路的两种工程落地:MLA 细粒度、KDA 粗粒度,两者一起决定"前缀能复用多长"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                5.12 可视化

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                plot_prefix_cache.py — 前缀缓存 (serve/prefix_cache.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 表达:前缀缓存的收益不来自「hash 索引」,而来自 KDA checkpoint 的原子性约束

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 测试:同一个 PrefixCache 注册 512-token 前缀 + persist_kda_checkpoint(512) 后,用不同前缀查询(miss)vs 完全一致查询(hit),对比 recompute_saved 的可复用 token 数

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 产出:plot_prefix_cache.png(柱状图,0 vs 512)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                plot_prefix_cache.py → plot_prefix_cache.png(耗时:no-cache vs hash vs kda 三级)。关键结论:如果 hit 带 checkpoint,0ms;否则 hash 命中仍是 MISCHANGE=$ timeline。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                plot_prefix_cache
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                plot_prefix_cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x06 组件三:投机解码 · 投影重放(decode.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                6.1 要解决什么问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                投机解码(speculative decoding):用「小/快的草稿模型」先一口气生成 k 个 token,再用「大/慢的真模型」一次性验证——对的就全部接受,错的就回退到第一个错的地方重来。它能大幅加速,同时保证输出与不投机时完全一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                投机解码有一个隐含前提:验证失败时要能「回滚」——回到「draft 还没开始」的状态,从正确位置重新生成。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                对普通 KV cache:能回滚。KV 是逐 token 的清单,验证失败就「删掉最后几个 KV 条目」即可回滚。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                短卷积状态比较容易回滚:线性注意力中的短卷积状态 conv_state 也保存的是一组独立的向量。对于推测解码,只需要把滑动窗口拓宽到:conv_kernel - 1 + num_spec。再把候选 Token 依次追加到窗口末尾。下一步根据 num_accepted_tokens - 1 做偏移读取即可。如果某些 draft Token 被拒绝,因为它们是独立保存的,所以不会污染前面已经确认的历史。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                对 KDA 呢? KDA 的状态 S 每 token 原地更新(S ← M·S + β·k·vᵀ),M 逐 token 相关——没有任何「删最后几个」的操作。draft 验证失败时,状态已经「前进」到错误位置之后,无法简单回滚。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                即,KDA(Kimi Delta Attention)的递归状态 S 每步就地在 cache 里更新:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  S_r = (I - beta_r k_r k_r^T) Diag(alpha_r) S_{r-1} + beta_r k_r v_r^T

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  所有 Token 都会原地混合进同一个矩阵:[num_heads, head_dim, head_dim]。一旦把候选 draft Token 更新进最终状态,之后如果发现这些 Token 被拒绝,之前的状态已经被它们污染,不能像独立 KV 那样简单删除某一条记录。因此,默认方案需要为每个请求额外分配:num_speculative_blocks 个物理块,把每个候选 Token 更新后的状态分别保存到不同槽位。验证完成后,根据接受的 Token 数量,选择对应的干净状态作为下一轮起点。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  这与 Transformer 的 KV cache 有本质区别:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KV cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KDA 状态 S

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  结构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  逐 token 独立条目

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  整体矩阵,每步覆盖更新

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  回滚到第 k 步

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  截断前 k 条即可

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  无法截断

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ,必须知道当时的完整 S

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  存储

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  O(T) 随序列增长

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  O(1) 固定大小,但每步覆盖

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  既然KDA 的状态无法像 KV cache 那样截断,必须有一种机制来恢复任意中间点的状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  6.2 难在哪

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Delta rule 的状态递推不可加、不可截断。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Vanilla 线性注意力的状态是 S = sum k_i v_i^T,天然可加,可以拆段计算再拼起来。但 KDA 的 delta rule 每步有一个逐 token 依赖的过渡矩阵(I - beta k k^T),它缩放的是整个既有状态:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    vanilla: S_{[i+1]} = S_{[i]} + 段内累加量        (可加,可前缀和)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA:     S_{[i+1]} = Stilde_{[i+1]} + M_{[i+1]} S_{[i]}  (仿射,逐段不同 M)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这意味着:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 不能按 token 索引状态:S_5 不是 S_3 + 某个增量,而是 S_3 经过两步仿射变换后的结果

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 不能提前计算任意中间点:必须按顺序递推

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 快照成本高:每步保存完整 S 要 H·dk·dv·itemsize 字节,draft 越长越昂贵

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    两难:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 若投机失败无法回滚 → 投机解码根本不成立(这是必须解决的);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 若每 draft token 都存一个状态快照(用于回滚)→ 额外状态写入很重:每个快照占H·dk·dv·itemsize 字节,draft 越长、状态越宽,成本越高。具体是否抵消投机收益,仍需结合 batch、dtype 和实现 benchmark。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    关键:解决「能回滚」的问题不能靠「存快照」,否则引入的成本抵消了投机本身的收益。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    投机解码三连挑战:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    1. 状态回滚:verify 拒绝部分 token → S 须回滚到拒绝点。KV 可截断,S 不能。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    2. 分支状态:beam/多候选需独立 S → KDACache.clone()。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    3. draft/verify 一致性:draft 推进了 S,verify 须从正确旧状态重算 → RawInputRing 重放轨迹。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    6.3 一个推测解码例子

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    假设目标模型已经处理到前缀 p。上一轮采样得到了一个确定 Token x0,但目标模型还没有把 x0 作为输入执行前向。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    草稿模型给出了三个候选 Token:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      d1, d2, d3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      因此本轮目标模型真正处理的输入是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        [x0, d1, d2, d3]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        目标模型的输出用途依次是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 处理 x0 的输出,用来验证 d1;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 处理 d1 的输出,用来验证 d2;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 处理 d2 的输出,用来验证 d3;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 最后一个位置的输出,可以用于全部候选都接受时的 bonus Token。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        验证 Kernel 为每个输入位置保存一个状态快照:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        状态列索引

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        本轮处理到的输入

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        保存的递推状态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        x0S_{p+1}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        x0, d1S_{p+2}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        2

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        x0, d1, d2S_{p+3}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        3

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        x0, d1, d2, d3S_{p+4}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        假设验证结果是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • d1 被接受;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • d2 被接受;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • d3 被拒绝;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 重新采样得到修正 Token r。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        本轮确认生成的 Token 是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          [d1, d2, r]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          但是,目标模型真正计算并确认写入状态的输入只有:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            [x0, d1, d2]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            也就是三个 Token,对应的有效状态是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              S_{p+3}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              r 虽然已经被采样出来,但目标模型还没有把 r 作为输入执行前向,因此不能说 r 的状态已经被缓存。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              下一轮应该从 S_{p+3} 开始,并把尚未输入目标模型的 r 作为下一轮的第一个确定输入 x0'。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              关键结论是:采样出一个 Token,不等于目标模型已经计算并缓存了这个 Token 的递归状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              6.4 总体思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              不缓存状态,只缓存「投影」(projection)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              关键观察:任何「已接受前缀之后」的状态,完全由这些 draft token 的投影输入决定——而投影输入远小于状态本身。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                不可行:cache 每个 draft token 的 S 快照   (每步 H·dk·dv 字节)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                可行:  cache 每个 draft token 的 (q,k,v,g,β)(每步 H·(3·dk+dv+1) 字节)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                投机期间只缓存这些小投影;验证时从「已接受的最长前缀」位置,用 kda_step精确重演一遍,得到正确的状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                6.5 背后的原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                为什么「投影决定状态」成立?因为 kda_step 是确定性的单步更新:给定当前状态和这一 token 的 (k,v,g,β),下一状态唯一确定。所以:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                只要我有「已提交状态」+ 「被接受的那几个 draft token 的投影」,我就能一步步精确重算出「应该的当前状态」——不需要存任何中间快照。拒绝的 token 不用算,只是「少重演几步」。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这就是「重演(replay)」而非「回滚(rollback)」:不需要显式 undo(KDA 下不存在 undo),只需带着投影从头走到「已接受长度」。这是「算法-系统协同设计」给系统设计者的第一课:把数学里不存在的操作,翻译成数学里天然存在的操作。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                量化对比(snapshot_cost_ratio):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  每步快照字节  = H · dk · dv
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  每步投影字节  = H · (3·dk + dv + 1)     # q/k/g 各 dk 宽 + v 的 dv + β 的 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  比值          = (H·dk·dv) / (H·(3dk+dv+1))   # draft_len 分子分母抵消

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  比值必须代入实际 H, dk, dv 计算;dtype 和 draft_len 会在比值中抵消,但不能脱离 shape 宣称固定倍数。以本文 H=2, dk=dv=8 为例,比值为128/66 ≈ 1.94。draft 越长,绝对字节差随 draft 线性增长。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  6.6 落地架构与数据结构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    DraftProjections (@dataclass)      # draft 窗口内逐 token 的投影
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        q,k,v,g,beta                    # 每个都是 (draft, B, H, D) 张量
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        __len__()   → draft 长度
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        nbytes()    → 已缓存投影总字节(与快照对比)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        slice(n)    → 只取前 n 个位置(用于「只重放被接受前缀」)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    SpeculativeKDAState (@dataclass)   # 投机前的已接受状态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        state          最新已接受的 KDA 状态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        projections    未确认的 draft 投影
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        accepted       已通过验证的步数
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        history        历次接受数(调优用)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        state_bytes()  → 完整状态字节(快照策略要持久化的量)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        cache_bytes()  → 投影缓存字节


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    verify_and_replay(committed, projections, n_accepted)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        state = committed.clone()      # 拷贝,避免污染共享的 committed 状态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        for i in range(n_accepted):    # 只重演被接受的步
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            out, state = kda_step(proj.q[i], proj.k[i], proj.v[i],
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  proj.g[i], proj.beta[i], state)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        return state, stacked_outputs   # 新状态 + 各步输出

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    具体代码如下:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """投机解码用于 KDA。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      设计动机(为什么要"重演"而不是"快照")
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ---------------------------------------
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      KDA 的递归状态 S 每步就地在 cache 里更新,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      无法像 KV cache 那样随意越程截断或按 token 指定位拷贝一份"旧状态"。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      若投机 draft 中某一位置被验证拒绝,状态已经前移,无法直接回滚。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      解法:不缓存完整状态(快照),投机期间只缓存 draft 的一小撮逐 step 投影
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      (q, k, v, g, beta),commit 时从"已接受的最长前缀"位置用 kda_step
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      精确重演一遍 —— 零快照、零状态深拷贝,只有一次短重放(O(n_accepted) 步)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      这与 SGLang 的 ReplaySSM(raw-input 重演)是**同一路线**,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      见 replayssm.py 的 RawInputRing(流式写入版,与本模块的批量构造互补)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      @dataclass
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      class DraftProjections:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          """draft 窗口内逐 step 的投影,每个都是 (draft, B, H, Dk/Dv/Beta) 张量。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          只缓存重放所需的输入(q/k/v/g/beta),不缓存每步中间状态,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          因此整个 draft 窗口附带的缓存远比持久化的状态快照小。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          q: Tensor
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          k: Tensor
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          v: Tensor
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          g: Tensor
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          beta: Tensor


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def __len__(self) -> int:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              return int(self.q.shape[0])


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def nbytes(self) -> int:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              return sum(t.numel() * t.element_size() for t in (self.q, self.k, self.v, self.g, self.beta))


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def slice(self, n: int) -> "DraftProjections":
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              return DraftProjections(*(t[:n] for t in (self.q, self.k, self.v, self.g, self.beta)))


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      @dataclass
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      class SpeculativeKDAState:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          """投机前的已接受状态 + 可选缓存投影,提交时用于精确重演。"""


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          state: Tensor
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          projections: DraftProjections | None = None
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          accepted: int = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          history: list[int] = field(default_factory=list)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def state_bytes(self) -> int:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              return self.state.numel() * self.state.element_size()


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def cache_bytes(self) -> int:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              return self.projections.nbytes() if self.projections is not None else 0


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      def verify_and_replay(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          committed: Tensor,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          projections: DraftProjections,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          n_accepted: int,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ) -> tuple[Tensor, Tensor]:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          """从已接受位置用 draft 投影精确重演,返回 (新状态, 各步输出)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          投机被拒绝时,已接受即短于目标数,只需在可接受的前缀上重放:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          每一步的 q/k/v/g 取 (B, H, Dk/Dv)、beta 取 (B, H),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          直接喂给 kda_step(与解码路径一致)。被拒的草稿位丢弃。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          state = committed.clone()           # 避免修改共享的 committed 状态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          outs: list[Tensor] = []
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          for i in range(n_accepted):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              out, state = kda_step(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  projections.q[i], projections.k[i], projections.v[i],
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  projections.g[i], projections.beta[i], state,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              )
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              outs.append(out)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          if outs:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              stacked = torch.stack(outs, dim=2)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          else:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              stacked = committed.new_zeros(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  committed.shape[0], committed.shape[1], 0, committed.shape[-1]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              )
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          return state, stacked


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      def snapshot_cost_ratio(heads: int, dk: int, dv: int, draft_len: int) -> float:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          """完整快照 vs 投影缓存的每步字节比(draft 长度在分子分母抵消)。"""
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          state_per_step = heads * dk * dv
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          proj_per_step = heads * (3 * dk + dv + 1)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          return (state_per_step * draft_len) / (proj_per_step * draft_len)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      6.6 数据流 / 执行流

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        投机窗口(draft_len 步):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          1. draft 模型一口气生成 k 个 token,同时对每步缓存 (q,k,v,g,β) 到 DraftProjections
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          2. 真模型验证:只重演「被接受」的前 n_accepted 步:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                state = committed.clone()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                for i in range(n_accepted):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    state = kda_step(proj[i], state)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                # 拒绝的 token 零成本:只是少重演几步
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          3. 把重演得到的 state 写回 cache,作为下一步的 committed

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        6.7 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        「验证也要跑 kda_step,那投机到底省了什么?」 省的是主模型的前向。投机时 draft 模型做 k 次便宜的前向,主模型只做一次验证前向(对 k 个 draft token 批量验证)。如果全对,一次主模型前向 = 生成 k 个 token。重演 kda_step 是很轻的操作(相对主模型前向),所以投影重放的额外开销可忽略。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        「为什么不直接存快照,反正有 4 倍差距?」 因为差距是每步的。draft 越长(比如 8 步),绝对差是 8×4 倍;而在线 serving 大 batch 时,这个「每 token 深拷贝状态」的成本占主导——投机省下的算力全被快照拷贝吃掉。投影方案让「省下的」真正省下来。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        6.8 何时用 / 何时不用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 何时用:状态宽(dk·dv 大)、draft 长、batch 大——快照存储成本占主导的场景,投影重放是唯一划算的。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 何时不用:状态很窄(dk·dv 接近投影大小)时,快照和投影成本相当,此时可以选快照;不投机(直接解码)时两者都不用。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        6.9 可视化

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        plot_decode_replay.py — 投机回滚策略成本 (serve/decode.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 表达:投机被拒时 KDA 状态回滚的两条路线成本比较

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 测试:调 snapshot_cost_ratio(H=16, dk=16, dv=16, draft),扫描 draft=1…32,画「投影缓存 vs 完整快照」的每步字节比。结论是比值恒定 > 1(投影永远更省,且与 draft 长度无关)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 产出:plot_decode_replay.png

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        plot_decode_replay
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        plot_decode_replay

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        0x07 组件四:投机解码 · RawInputRing 环形缓冲(replayssm.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        RawInputRing:SGLang ReplaySSM 的真实语义与实现。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        7.1 问题所在

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        当前项目中,DraftProjections 借鉴了 K3-master。DraftProjections 的教学演示存在问题。因为当前实现是批量构造,即 draft 全部跑完后,一次性切片包装。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          # draft 结束后,一次性把 5 步数据 permute 成 DraftProjections
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          draft = DraftProjections(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              q=q[:, :, N_COMMIT:].permute(2, 0, 1, 3),  # (5, B, H, D)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ...
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          )

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          为什么这样设计? 因为 decode.py 的 DraftProjections 定位是离线分析/教学演示的载体——假设你已经有了完整的 draft 数据,需要包装成 verify_and_replay 能消费的格式。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          批量构造并不适合实际在线场景,应该在 draft token 生成过程中逐步存储。因此,我们来看看SGLang 如何处理。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          7.2 SGLang ReplaySSM

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ReplaySSM 是 SGLang 的方案,我们来学习下。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          定义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          看 SGLang 的真实定义(server_args.py:2688-2696):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ReplaySSM spec-verify: fold-every-commit — a per-slot raw-input window replaces the recurrent verify's per-draft full-state snapshots. The verify stores each draft step's raw inputs into a per-slot window and the commit replays the accepted prefix into the fp32 checkpoint.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ReplaySSM-KDA: the accepted drafts live in the per-slot ring (written during verify); no intermediate_ssm is allocated. Replay the accepted prefix into temporal instead of scattering an intermediate state.

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          SGLang 的 ReplaySSM 不是"存快照",而是"存原始输入 + 重演"! 它和 decode.py 的投影重放是同一路线,只是实现细节不同(GDN 存 raw input 窗口,KDA 存 (v, k, gate, beta) 环)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          另外,业界还有 RecoverSSM 方式。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • ReplaySSM:验证后重新回放接受的部分;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • RecoverSSM:只提交接受部分的状态更新。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ReplaySSM(= 存 raw input + 重演)的优势

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ReplaySSM 不是"回滚到任意点更快",而是省 HBM 带宽。看 server_args.py:2670-2685 的两个独立开关:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          开关

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          场景

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          核心收益

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          enable_linear_replayssm纯 decode

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (非投机)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          每 L 步才把完整状态 flush 到 HBM,期间只在 ring 里累积 raw input。省的是每步写状态矩阵的带宽

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          enable_linear_replayssm_spec投机 verify

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          verify 期间不存每步的完整状态快照,只存 raw input 窗口;commit 时重演被接受前缀到 fp32 checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          带宽账(这是真正的卖点):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 传统 decode:每步把 H·dk·dv 的状态矩阵写回 HBM

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • ReplaySSM decode:每步只把 (v, k, gate, beta)(H·(3dk+dv+1))写进 ring,每 L 步才 flush 一次完整状态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          注释里写得很清楚:"Primarily a GDN (scalar-gate) decode-bandwidth optimization (~1.2-1.5x at batch >= 64)"。batch 大时状态矩阵的 HBM 往返是瓶颈,raw input 环能把带宽砍一个数量级。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA 的坑:注释也说了——KDA uses its selected Triton or Helion implementation, but its per-K gate ring is larger and ReplaySSM is typically slower than packed KDA decode。KDA 的 gate 是 per-channel 向量(H·dk),比 GDN 的标量 gate 大得多,所以 ring 反而更占带宽,通常更慢,要 benchmark 后再开。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          适用场景

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ReplaySSM 有效的场景非常具体:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          1. GDN 类标量 gate 模型 + 大 batch decode(>= 64):带宽收益 1.2-1.5x

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          2. 投机 verify 的内存优化:不想为每步 draft 存完整状态快照时

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          3. 线性链(topk ≤ 1):树状投机不支持

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          对 KDA 来说,SGLang 自己都建议默认别开——per-K gate ring 的带宽开销可能超过省下的状态写带宽。这也解释了为什么 decode.py 的投影重放对 KDA 是更自然的选择:两者都是"存 raw input + 重演",但投影重放的表述更直接,没有 ReplaySSM 这个名字带来的"快照回放"误导。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          关键结论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          关键结论:SGLang 的 ReplaySSM 与 decode.py 的投影重放是同一路线——都是存 raw input + commit 时重演。差异只在实现形式(流式窗口 vs 批量构造)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          因此,我们构建了 RawInputRing,即 replayssm 方案。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          7.3 总体思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          存 raw input(小),不存状态(大);commit 时重演,不依赖快照。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          核心洞察:回滚到 S_k 不需要"当时存下 S_k",只需要"从某个已知安全点出发,用 raw input 重新递推 k 步"。raw input (q, k, v, g, beta) 每步只占 H·(3dk+dv+1) 字节,远小于完整状态 H·dk·dv。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          两条实现路线(同宗同源,共享重演引擎):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          路线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          写入时机

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          适用场景

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          投影重放

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (decode.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          draft 结束后一次性批量构造 DraftProjections

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          离线分析、教学演示、draft 长度固定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          RawInputRing

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (replayssm.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          draft 每步实时流式 push(),满则覆盖最旧

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          在线投机、draft 长度可变、内存受限

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          7.4 背后的原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          7.4.1 第一性原理:RawInputRing 到底解决什么

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA 的状态更新可以抽象成:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            S_next = F(S_current, q, k, v, g, beta)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            其中 S_current 是一个已经被前面 Token 混合过的整体矩阵。投机验证失败时,我们想得到某个较早的 S_k。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            但 KDA 没有通用的 undo:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 状态不是“每个 Token 一格”的可截断列表;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 被拒 Token 的影响已经写进后续状态;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 仅凭当前污染后的状态,通常无法反推出被拒 Token 之前的状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            所以只有两条原则上可靠的路:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1. 保存每个中间状态:失败后直接取 S_k;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2. 保存一个已知安全状态和之后的输入轨迹:从安全状态重新执行F,重建 S_k。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            RawInputRing 选择第二条路。它本质上不是“回滚器”,而是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            为状态重建保留一段可重放的输入轨迹。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            在当前项目中,这段轨迹不是原始 token ID,而是已经完成模型投影、足以驱动kda_step 的 (q, k, v, g, beta)。其中:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • (k, v, g, beta) 决定下一状态;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • q 不参与状态更新,但重放时需要它产生对应输出,因此一起保存;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • RawInputRing 只负责流式保存和按时间顺序读出;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • verify_and_replay 才负责从 committed state 逐步重演。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            因此,RawInputRing 的作用可以压缩成一句话:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              用较小的输入轨迹,替代每一步昂贵的完整状态快照。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              7.4.1 什么场景下有效

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              raw-input 重演路线(SGLang ReplaySSM / decode.py / replayssm.py):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              场景

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              是否有效

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              原因

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              KDA 类 per-channel gate 模型

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ⚠️ 算法上可用,收益需 benchmark

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              gate 是向量 H·dk,但 raw-input ring 也更大;SGLang 注释指出 KDA ReplaySSM 通常更慢

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              任意接受模式(全拒/部分/全接受)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ✅ 通用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              重演长度 = n_accepted,精确到任意前缀

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              大 batch decode(>= 64)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ✅ 带宽收益明显

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              每步写 raw input 比写状态矩阵省 HBM 带宽

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              GDN 类标量 gate 模型

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ✅ SGLang 注释提到 1.2-1.5x 加速

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              gate 是标量,ring 更小

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              KDA + 假想快照路线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ⚠️ 可作为基线

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              快照访问快但写带宽和显存成本高;不能简单断言“不可用”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              假想快照路线(用于成本和正确性对照):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              场景

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              是否有效

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              原因

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              整轮全拒

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ⚠️ 理论高效

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              pop() 一次到位,零重演

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              部分接受

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ❌ 退化

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              仍需从安全点重演,且每步多付了快照存储

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              KDA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ⚠️ 成本高

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              gate 向量让快照成本上升,但并非算法上不可用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              任意中间点查询

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ⚠️ 取决于保存范围

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              环形缓冲覆盖后,超出窗口的中间点无法直接取得

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              假想快照路线就是存储全部的 KDA state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              7.4.2 带宽账

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              量化对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              以 H=2, dk=8, dv=8, fp64 为例:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              方案

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              每步缓存字节

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              draft=5 总字节

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              相对比值

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              假想快照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              H·dk·dv·8

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               = 1024

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              5 × 1024 = 5120

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              1.94x

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              raw input

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              H·(3dk+dv+1)·8

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               = 528

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              5 × 528 = 2640

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              1.00x

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • dk 是 key/query/state 的地址或记忆通道维度。代码中 q, k, g 的最后一维都是 Dk;KDA 状态为S.shape = (B, H, dk, dv)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • dv 是 value/output 的内容维度。代码中 v 的最后一维是 Dv,单步输出 out 的最后一维也为 Dv。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 状态矩阵可以按一个 head 写成:S ∈ R^(dk × dv)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              所以保存完整状态需要 dk·dv 个元素;而保存 raw input 只需要3dk+dv+1 个元素。两者的差别正是“存矩阵”与“存驱动下一步计算所需的投影”的差别。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              另外,这里的 128 和 66 是 fp64 元素数量,不是字节数;fp64 必须再乘sizeof(fp64)=8。相对比值不受 dtype 和 draft 长度影响:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ratio = (H·dk·dv) / (H·(3dk+dv+1))
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      = 128 / 66
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ≈ 1.94

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                dtype 只改变绝对字节数;draft 长度只把两种方案同时线性放大。当 dk·dv 相对 3dk+dv+1 更大时,raw-input 的相对优势才会更明显。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                raw input 解读

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                H·(3dk+dv+1) 是每个 Token、每个缓存时间步的元素数量,不是脱离 dtype 后的字节数。实际缓存字节数应为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  每步字节数 = H · (3dk + dv + 1) · itemsize

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  这里的每个符号都能在 RawInputRing 中找到对应变量:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  数量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  具体数据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  代码变量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  单个 head 的形状

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  为什么要存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  dk

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  query 向量 q

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  _q(dk,)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  重放时计算当前 Token 的输出 o = S^T q

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  dk

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  key 向量 k

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  _k(dk,)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  检索旧状态,并决定新信息写入状态的方向

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  dk

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  per-channel log gate g

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  _g(dk,)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  生成逐通道保留因子 exp(g),先衰减旧状态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  dv

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  value 向量 v

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  _v(dv,)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  提供当前 Token 要写入状态的目标内容

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  delta-rule 强度 beta

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  _beta

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  标量 ()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  控制本次写入幅度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  因此:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    3dk = dk(q) + dk(k) + dk(g)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    dv  = dv(v)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    1   = 1(beta)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    乘上 H 是因为每个 Token 有 H 个 head,每个 head 都各自保存一组q, k, g, v, beta。RawInputRing 的五个 list 正好对应上表:_q, _k, _g, _v, _beta。它们按相同的时间顺序追加和淘汰,所以第 i 个位置的五个张量必须视为一个不可拆分的投影组。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    7.5 落地架构与数据结构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    7.5.1 RawInputRing 类设计

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      class RawInputRing:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          """per-slot raw-input 环形窗口:流式缓存 draft 每步的 (q,k,v,g,beta)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          环形缓冲存的是每步的原始输入投影,**不是**状态快照。满则覆盖最旧
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          (draft 长度封顶)。commit 时调用方取 :meth:`window` 得到
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ``DraftProjections``,喂给 ``decode.verify_and_replay`` 重演到目标状态。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          .. note:: 为什么不做回滚?
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             回滚逻辑(取前 n_accepted 项、逐步重演)已经在 ``decode.verify_and_replay``
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             里实现并对拍验证过。本类只做"流式写入 + 窗口读出",保持单一职责。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          """


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def __init__(self, capacity: int) -> None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """capacity 必须为正整数,通常取 draft_len 上限。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              环形窗口的逻辑语义:``_q[0]`` 永远是当前窗口里**最旧**的一组投影,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ``_q[-1]`` 是最新。满员时 push 会先淘汰最旧再追加,保证窗口永远
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              保留最近 capacity 步。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              if capacity <= 0:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  raise ValueError(f"capacity must be positive, got {capacity}")
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self.capacity = capacity
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              # 5 个并列的环形缓冲,每个元素是 (B, H, D) 张量(beta 是 (B, H))。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              # 用 list 而非定长 tensor:写入次数不固定(draft 长度可变),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              # list 的 append/pop(0) 语义更直白,capacity 是小常数(draft_len 级)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._q: list[Tensor] = []
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._k: list[Tensor] = []
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._v: list[Tensor] = []
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._g: list[Tensor] = []
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._beta: list[Tensor] = []


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def __len__(self) -> int:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """当前窗口中的投影组数(<= capacity)。"""
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              return len(self._q)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def push(self, q: Tensor, k: Tensor, v: Tensor, g: Tensor, beta: Tensor) -> None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """每步 draft 推入一组投影。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Args:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  q, k, g: ``(B, H, Dk)``
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  v: ``(B, H, Dv)``
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  beta: ``(B, H)``


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              满员时先淘汰最旧(各 buffer 的 ``[0]``),再追加到队尾——等价于
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              "新投影覆盖最旧槽位",但保留列表有序性,``window()`` 读出的
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ``DraftProjections.q[i]`` 永远对应"窗口内第 i 旧的投影"。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              if len(self._q) == self.capacity:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self._q.pop(0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self._k.pop(0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self._v.pop(0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self._g.pop(0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  self._beta.pop(0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._q.append(q)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._k.append(k)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._v.append(v)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._g.append(g)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._beta.append(beta)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def window(self) -> DraftProjections:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """返回当前窗口为 ``DraftProjections``,布局 ``(draft, B, H, D)``。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              空窗口时抛 ``IndexError``——调用方应先检查 ``len(ring) > 0``。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ``verify_and_replay`` 对 n_accepted=0 有专门处理,但空窗口无法
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              构造有效 DraftProjections(没有样本决定形状),故选择显式报错。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              if not self._q:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  raise IndexError("RawInputRing empty: call len() before window()")
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              return DraftProjections(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  q=torch.stack(self._q, dim=0),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  k=torch.stack(self._k, dim=0),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  v=torch.stack(self._v, dim=0),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  g=torch.stack(self._g, dim=0),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  beta=torch.stack(self._beta, dim=0),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              )


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def reset(self) -> None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """清空窗口,恢复到刚构造的状态。"""
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._q.clear()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._k.clear()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._v.clear()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._g.clear()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              self._beta.clear()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      7.5.2 内部数据结构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        # 5 个并列的环形缓冲,每个元素是 (B, H, D) 张量(beta 是 (B, H))
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        self._q: list[Tensor]   # (B, H, dk)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        self._k: list[Tensor]   # (B, H, dk)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        self._v: list[Tensor]   # (B, H, dv)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        self._g: list[Tensor]   # (B, H, dk)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        self._beta: list[Tensor] # (B, H)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        逐项解释:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        1. g:衰减旧记忆。g 是逐 channel 的 log decay,alpha = exp(g)。alpha[d] 会乘到状态矩阵的第 d 行,因此不同 key channel可以有不同的记忆保留率。没有 _g,就无法重建每一步对旧状态的衰减。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        2. k:检索并定位写入位置。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          sk = S^T k 从旧状态中检索出当前 key 已经记住的 value 内容;外积 k ⊗ delta 再沿 key 方向把新信息写回状态。没有 _k,既不能计算检索结果,也不能确定写入状态的哪些行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        3. v:提供目标内容。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          v - sk 是当前 value 与状态已有预测之间的差值,即 delta rule 要补写的新信息。没有 _v,只能知道已有记忆,无法知道要写入什么。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4. beta:控制写入强度。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          delta = beta · (v - sk)。beta 越大,本 Token 对状态的修正越强;beta 越小,更新越保守。没有 _beta,重放得到的状态会与原递推不同。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        5. q:生成对应输出。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          q 不参与状态更新,因此如果目标只是重建最终 state,理论上可以不保存 q;但 verify_and_replay 同时返回每个接受 Token 的输出,需要用 out = S^T q 计算这些输出,所以项目将 _q 与其余投影一起保存。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        _g 和 _beta 不是附加日志,而是 KDA 状态转移的一部分。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        一个 head 的具体数字

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        以 dk=8, dv=8 为例,一个 head、一个 Token 的缓存是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          q:    8 个元素
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          k:    8 个元素
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          g:    8 个元素
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          v:    8 个元素
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          beta: 1 个元素
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ----------------
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          合计: 33 个元素 = 3·8 + 8 + 1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          若 H=2:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2 个 head × 33 = 66 个元素

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            若 dtype 是 fp64,每个元素 8 bytes:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              66 × 8 = 528 bytes/step
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              draft=5 时:5 × 528 = 2640 bytes

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              为什么用 list 而非定长 tensor?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • draft 长度可变,写入次数不固定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • append/pop(0) 语义直白,capacity 是小常数(draft_len 级)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • window() 时 torch.stack(list, dim=0) 一步转 DraftProjections

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              RawInputRing 是逐步调用的:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                for i in range(DRAFT_LEN):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ring.push(q[:, :, i], k[:, :, i], ...)  # 每步实时写入

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这正是 SGLang enable_linear_replayssm_spec 的在线语义——draft 每产出一步就立即缓存,不等全部跑完。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                如何重放

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                对某个 Token,kda_step 的重建过程等价于:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # state: (B, H, dk, dv)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # q, k, g: (B, H, dk)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # v:       (B, H, dv)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  # beta:    (B, H)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  state = g.exp().unsqueeze(-1) * state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  sk = torch.einsum("bhd,bhdv->bhv", k, state)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  delta = beta.unsqueeze(-1) * (v - sk)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  state = state + k.unsqueeze(-1) * delta.unsqueeze(-2)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  out = torch.einsum("bhd,bhdv->bhv", q, state)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  重放时,window() 将五个 list 分别 torch.stack(..., dim=0),得到 (draft, B, H, D) 的 DraftProjections;随后verify_and_replay 从 committed state 出发,只遍历被接受的前缀, 依次调用 kda_step(q[i], k[i], v[i], g[i], beta[i], state)。因此,RawInputRing 本身不“恢复”状态;它保存重建所需的五类数据,真正的状态重建发生在 verify_and_replay 的逐 Token 递推中。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  DraftProjections 和 RawInputRing 的区别

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  存储内容完全相同——都是 (q, k, v, g, beta) 五元组。区别只在写入接口:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  DraftProjections

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  RawInputRing

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  本质

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  一个 dataclass(5 个 tensor 的容器)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  一个环形缓冲管理器

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  写入方式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  构造时一次性传入所有数据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  逐 step push(),满则覆盖最旧

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  容量控制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  无(draft 多长就存多长)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  有 capacity 上限,超出覆盖最旧

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  使用场景

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  已知全部 draft 数据后批量包装

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  在线流式写入,内存受限

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  RawInputRing 不比 DraftProjections 存得多——存的是同一批数据,只是写入方式不同。但当前实现不会自动推进已安全提交的 checkpoint;若一次投机窗口最多可能接受draft_len 个 Token,capacity 必须覆盖这段完整前缀。capacity < draft_len只有在调用方另有安全 checkpoint、且能证明不会重放被覆盖前缀时才成立。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  7.5.3 RawInputRing vs 假想快照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  一句话:假想快照在"全拒且 capacity 足够"时理论最优,但 KDA 的状态矩阵太大、覆盖语义让中间点不可靠、SGLang 工程验证更慢——所以被淘汰。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  假想快照理论上可行,工程上代价不可接受。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  假想快照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  raw-input 重演

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  每步存储

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  H·dk·dv·itemsize

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   字节(完整状态矩阵)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  H·(3dk+dv+1)·itemsize

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   字节

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  draft=5, H=2, dk=dv=8, fp64

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  5 × 1024 = 5120 B

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  5 × 528 = 2640 B

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  draft=10, H=16, dk=dv=64

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  10 × 65536 = 640 KB

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  10 × 1040 = 10 KB

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  回滚到任意中间点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  直接取对应快照(若未被覆盖)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  从安全点重演 n 步

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  计算代价

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  零(若快照在)或重演(若被覆盖)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  固定 n 步重演

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  关键问题不是"能不能",而是"值不值":

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • KDA 的 per-channel gate 让状态矩阵膨胀:dk·dv 是乘积关系,而 raw input 的 3dk+dv+1 是加和关系。dk=dv=64, H=16 时比值约 10.7x,不是 2x

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • SGLang 明确说 KDA 上更慢:server_args.py 注释 "KDA ... its per-K gate ring is larger and ReplaySSM is typically slower than packed KDA decode"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 环形覆盖语义下,中间点可能已被顶掉:想取 S_5 但 capacity=3 时只剩 S_6,S_7,S_8,反而还得从 S_3 重演——快照白存了

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  7.5.4 与 decode.py 的协作

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  RawInputRing 必须和 decode.py 配合使用吗?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  不是必须,但目前设计是强耦合的。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  层面

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  是否必须

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  说明

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  数据格式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  window()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   返回 DraftProjections,这是 verify_and_replay 的唯一输入类型

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  重演引擎

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  否

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  你可以不用 verify_and_replay,自己写循环调 kda_step

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  依赖关系

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  replayssm.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   import 了 decode.py 的 DraftProjections

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  解耦的可能性:RawInputRing 内部的 _q/_k/_v/_g/_beta 是独立存储的,你可以:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    # 不用 window(),直接访问内部 buffer(不推荐,破坏封装)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    for i in range(len(ring)):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        q, k, v, g, beta = ring._q[i], ring._k[i], ...
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        out, state = kda_step(q, k, v, g, beta, state)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    但这绕过了 DraftProjections 的类型安全,目前没有这个需求。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    当前定位:RawInputRing 是 decode.py 投影重放路线的流式写入前端,两者是同一方案的不同封装,不是独立方案。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    RawInputRing
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    RawInputRing

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    关键设计:RawInputRing 不做回滚,只做"流式写入 + 窗口读出"。回滚逻辑复用 decode.verify_and_replay,保持单一职责。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    7.6 何时调用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    7.6.1 写入路径(draft 期间)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      from models.llm.kimi_k3.serve.replayssm import RawInputRing


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ring = RawInputRing(capacity=draft_max)  # capacity >= draft_len 上限
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      for step in range(draft_len):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          q, k, v, g, beta = model.project(token[step])  # 模型前向
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ring.push(q, k, v, g, beta)                     # 流式写入

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      7.6.2 读取路径(commit 时)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        from models.llm.kimi_k3.serve.decode import verify_and_replay


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        n_accepted = verify(draft_tokens)                   # 验证接受数
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        if len(ring) > 0:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            projections = ring.window()                     # 取出 raw input
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            new_state, outs = verify_and_replay(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                committed_state, projections, n_accepted    # 重演到目标状态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            )
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ring.reset()                                        # 清空窗口,准备下一轮

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        7.6.3 容量约束

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        capacity 必须 >= draft_len 的最大可能值。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        若 capacity < draft_len,早期投影会被覆盖,导致 window() 返回的 DraftProjections 不包含重演所需的前缀。demo 中刻意演示了这种溢出场景作为警示。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        7.7 关键对比:投影重放 vs RawInputRing —— 两条路线各在何时适用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        一句话:RawInputRing 是 DraftProjections 的流式写入封装,解决"在线投机时内存受限"的问题,两者是协作关系而非替代关系。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        不是升级,是互补——就像"流式写入"和"批量读取"的关系。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        DraftProjections

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        RawInputRing

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        定位

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        数据载体(DTO)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        写入管理器

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        职责

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        包装已有数据,传给 verify_and_replay

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        控制写入时机、容量、覆盖策略

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        生命周期

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        不可变(构造后只读)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        可变(push/reset 动态变化)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        内存控制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        无(数据多大就多大)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        有(capacity 上限)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        类比:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • DraftProjections = torch.Tensor(数据本身)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • RawInputRing = torch.utils.data.DataLoader(控制怎么喂数据)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        不是升级版的原因:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        1. RawInputRing 依赖 DraftProjections:window() 的产物就是 DraftProjections

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        2. DraftProjections 可以独立存在:demo 方案 A 直接构造,不经过 RawInputRing

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        3. 场景不同,无优劣:批量场景用 DraftProjections 更直接,流式场景用 RawInputRing 更自然

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        两者都是 raw-input 路线,共享 verify_and_replay,差异只在写入时机:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        投影重放(decode.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        RawInputRing(replayssm.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        写入方式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        批量构造 DraftProjections(draft 结束后一次性)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        流式 push()(draft 每步实时)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        内存峰值

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        draft_len × 66 Bcapacity × 66 B

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        (capacity 可 < draft_len)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        适用场景

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        离线分析、教学演示、draft 长度固定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        在线投机、draft 长度可变、内存受限

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        与 SGLang 对应

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        无直接对应

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        enable_linear_replayssm_spec

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        回滚引擎

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        verify_and_replayverify_and_replay

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        (共享)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        结果一致性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        与参考 S_k 逐位对齐

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        与参考 S_k 逐位对齐

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        假想快照路线(已被淘汰):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        假想快照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        每步缓存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        完整状态 S(H·dk·dv 字节)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        回滚方式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        pop 最旧快照 + 可能重演兜底

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        KDA 适用性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ❌ 不适用(per-channel gate 让快照成本失控)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        SGLang 对应

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ❌ 无(SGLang 从未用快照)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        7.8 示例

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        见 experiments/models/llm/kimi_k3/serve/demo_replay_vs_snapshot.py,场景:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 已 commit 3 个 token(S_3)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • draft 提出 5 个 token,验证后接受前 2 个(d3 起被拒)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 目标回滚到 S_5

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        输出:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ========================================================================
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          场景:已 commit 3 个 token(S_3),draft 5 个,验证后接受前 2 个(d3 起被拒),目标回滚到 S_5
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ========================================================================


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          [A] 投影重放:draft 结束后一次性批量构造 DraftProjections
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              缓存投影字节:2640 B  (5 步 x H*(3*dk+dv+1)=66 B/步)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              内存峰值:draft 结束时一次性占 2640 B
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              重演 2 步 -> S_5
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              与参考 S_5 的最大误差:0.00e+00


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          [B] RawInputRing:draft 每步实时流式 push,容量=3
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              (capacity < draft_len,演示环形覆盖语义)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              push 第 0 步后,窗口大小 = 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              push 第 1 步后,窗口大小 = 2
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              push 第 2 步后,窗口大小 = 3
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              push 第 3 步后,窗口大小 = 3(最旧被覆盖)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              push 第 4 步后,窗口大小 = 3(最旧被覆盖)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              警告:capacity=3 < draft_len=5,第 0,1 步投影已被覆盖,无法重演前 2 步!
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              真实部署中 capacity 必须 >= draft_len 上限,本例仅演示覆盖语义,下面用 capacity=5 重跑
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              capacity=5 时,窗口完整保留 5 步投影
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              缓存投影字节:2640 B  (与方案 A 相同)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              内存峰值:全程只占 5 步 x 66 B/步(流式写入的优势)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              重演 2 步 -> S_5
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              与参考 S_5 的最大误差:0.00e+00


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ========================================================================
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          汇总
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ========================================================================
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            最终状态一致性:A == B == 参考 S_5  (max err 0.00e+00)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            缓存内容:完全相同(raw input (q,k,v,g,beta),2640 B)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            写入时机:A 批量(draft 结束后);B 流式(draft 每步)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            内存峰值:A = draft_len x 66 B;B = capacity x 66 B(可 < draft_len)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            重演引擎:共享 verify_and_replay(SGLang ReplaySSM 的真实语义)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            假想快照路线(已被淘汰):每步存完整状态 H*dk*dv=128 B,是 raw input 的 1.94 倍
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            KDA 的 per-channel gate 让快照成本雪上加霜,SGLang 注释明确指出 KDA 上 ReplaySSM 通常更慢

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          7.9 可视化

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          见 experiments/models/llm/kimi_k3/serve/gradio_serve_demo.py Tab 4,四个子图:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          子图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          内容

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          左上

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          RawInputRing push/窗口溢出时序(capacity=4,演示覆盖语义)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          右上

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          window()

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           转 DraftProjections 的布局可视化(draft × H × D)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          左下

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          RawInputRing vs 投影重放:共享 verify_and_replay,误差均为 0

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          右下

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          带宽账:raw input vs 假想快照(draft 越长,快照劣势越明显)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          0x08 组件五:KDA 上下文并行(KCP)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA Context Parallelism
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA Context Parallelism

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          8.1 它要解决什么问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          上下文并行(context parallelism, CP):当序列极长(比如 1M token)时,单块 GPU 放不下整个序列,需要把序列切成多段,分到多块设备(rank)上并行计算。每段各算各的,最后把结果拼起来。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          对普通 KV 的上下文并行,做法很简单:各段先算好局部的 KV,一次 all-gather 拼起来,然后各段自由地重算后续。因为 vanilla 线性注意力的递推是加性的(S = Σ_t k_t v_tᵀ),每段可以从 S=0 出发算自己的「自生成状态」,整体入态 = 前面各段自状态的直接求和。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          对 KDA 呢? KDA 的状态递推不是加性的:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            S_t = M_t S_{t-1} + β_t k_t v_tᵀ ,   M_t = (I − β_t k_t k_tᵀ) Diag(α_t)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            M_t 是逐 token 相关的矩阵,先作用在入状态上,再加本次写入。所以局部段对结果的贡献,取决于「进入这一段时的状态」——不能只靠「从 S=0 出发的自生成状态」来恢复。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            8.2 难在哪

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            状态跨段「不可加」。直观地说:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • vanilla 线性注意力:段 A 和段 B 是「并行算好、直接相加」的关系——因为每段都是纯「累加」;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • KDA:段 B 的输入状态,依赖于段 A 末尾的状态;而段 A 末尾的状态,又取决于更前面的段。直接把它们加起来是错的。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            8.3 总体思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            把每段的效果分解成两个「本地可算」的量,再用一次「仿射链的前缀扫描」重组。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            每个段 [t0, tN) 可以看作一个仿射变换T(S) = M̄·S + S̃:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • M̄(段内累积过渡矩阵):把段内每个 token 的 M_t 依次复合——它负责「把上一段末尾传进来的状态,缩放成本段末尾的状态」;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • S̃(段从零状态自生成的状态):从 S=0 出发,由本段 token 生成的「自有状态」。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            于是段 i+1 的入态可以写成(K3 技术报告 Eq.17):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              S_{[i+1]} = S̃_{[i+1]} + M̄_{[i+1]} · S_{[i]}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              这两个量 M̄ 和 S̃只依赖本段的本地 token,在「上一段的入态可用之前」就能算好。而且 rank 级更新可结合——因此每个 rank 的入态可以用一个前缀扫描恢复。通信量只随模型维度(与序列长度无关),算力线性扩展——这就是百万 token 上下文训练可行的基础。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              8.4 背后的原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              为什么「分解成 M̄ 和 S̃」就能绕过「不可加」?因为把一个「逐 token 的、非线性的递推」变成了「段级别的、仿射的、可结合的链」。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              看图。把序列切成 4 段,分别放到 rank 0-3。三段式流程:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                阶段 1:每段本地算 (M̄, S̃) —— 各 rank 并行,互不等待
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         [段0]      [段1]      [段2]      [段3]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         (M̄0,S̃0)   (M̄1,S̃1)    (M̄2,S̃2)    (M̄3,S̃3)      ← 只依赖本地 token


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                阶段 2:一次固定大小 all-gather —— 交换的只有 (M̄, S̃),与序列长度无关
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         ┌────── all-gather (M̄, S̃) ──────┐
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         ▼       ▼     ▼     ▼
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         rank0 rank1 rank2 rank3       每个 rank 都拿到完整列表:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       [(M̄0,S̃0),(M̄1,S̃1),(M̄2,S̃2),(M̄3,S̃3)]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         (all-gather = "每个 rank 把自己的 (M̄,S̃) 广播给所有人,最终每人手上有全部"
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           为什么非要它?因为 rank i 的入态依赖所有更前面段的 (M̄,S̃),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           所以每个 rank 必须先拿到全部,才能独立做下一步前缀扫描)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                阶段 3:前缀扫描恢复各段入态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         incoming[0] = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         incoming[1] = M̄0·incoming[0] + S̃0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         incoming[2] = M̄1·incoming[1] + S̃1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         incoming[3] = M̄2·incoming[2] + S̃2
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         每个 rank 用 incoming[i] 作为本段 initial_state,重跑 chunkwise 得输出

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                补充说明:KCP 严格说是 4 个阶段。代码 docstring 里的"三阶段"是把阶段 1(分段)和阶段 2(本地算)合并了。按真实流水拆开:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1. 分段/调度:沿 T 均分,发到各 rank(kcp.py:150)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                2. 并行本地计算 (M̄, S̃):各 rank 互不等待(kcp.py:152-165)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                3. 一次 all-gather + 前缀扫描(串行瓶颈):交换的只有 (M̄, S̃),通信量与序列长度无关;扫描本身是 n_segments 步的串行递推(kcp.py:166)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4. 并行重算输出:各 rank 用 incoming[i] 独立跑 kda_chunkwise 产出真实输出(kcp.py:171-180)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                关键点:阶段 3 的"前缀扫描"是串行部分(仿射链不可并行,这正是 delta rule 与 vanilla 线性注意力的根本差异),但它的输入是常数大小的 (M̄, S̃),不随 T 增长,所以瓶颈可控。阶段 2 和 4 都是完全并行的。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                关键洞察:虽然每段的状态「不可直接相加」,但把每段写成 入态 → 出态 的仿射变换后,整条链就是「一个接着一个的仿射变换」——这正是前缀扫描能处理的形态(把「段级转移」当作「标量转移」,只是转移量从标量变成了矩阵)。这跟 vanilla「直接相加」的根本差别在于:vanilla 的转移矩阵是恒等(I),KDA 的转移矩阵逐段不同(M̄),所以必须扫描、不能直接求和。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.4.1 图:KCP 前缀扫描

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                plot_kcp
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                plot_kcp

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                左图:跨段状态重组两种方式对精确递推的误差(log 轴)——"直接相加"误差 9.78e-01(基本全错),"KCP 前缀扫描"误差 1.11e-16(机器精度,与整段递推逐位一致)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                右图:KCP 通信量与序列长度无关(常数),而 softmax attention 的 KV 交换量随长度线性/超线性增长。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.4.2 常见疑问:KCP 用的 kda_chunkwise 到底是什么并行?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                KCP 在阶段 1 和阶段 3 都调用了 kda_chunkwise。要理解 KCP,就得先懂这个 kernel 的并行结构。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                kda_chunkwise 是"块内并行、块间串行"(K3 技术报告 Eq.3-4)。它把序列切成 chunk_size=16 的块(chunk):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 每个 chunk 内部:token 级并行——块内所有 token 的相互作用一次算完(q_bar @ k_hatᵀ、A 矩阵、UT 三角求解都是矩阵乘法),这正是"chunk 内并行";

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • chunk 之间:串行递推——每个 chunk 的入态来自上一个 chunk 的尾态,一个 for i in range(n_chunks) 循环串行推进。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  序列 T = 64,chunk_size = 16 → 4 个 chunk


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    chunk0        chunk1        chunk2        chunk3
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   [0..15]       [16..31]      [32..47]      [48..63]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      │             │             │             │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      │  token 并行  │             │             │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      │  (矩阵乘)    │             │             │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ▼             ▼             ▼             ▼
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     S₀ ──►  S₁  ──►  S₂  ──►  S₃  ──►  S₄     (状态串行在 chunk 间传递)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          chunk内并行算完所有 token 输出,再把尾态 S 传给下一个 chunk

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  对比 kda_recurrent:recurrent 是纯逐 token 串行(一个 token 一个循环);chunkwise 把"一个 chunk 内"重排成并行矩阵乘,只保留"chunk 间"的串行状态传递。两者数学等价,chunkwise 是 GPU 友好的并行形式。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KCP 为什么用 chunkwise 算 (M̄,S̃)? 因为 local_transition_and_state 里:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • S̃ = 用 kda_chunkwise(k, v=真实值, S₀=0) 跑出"段自生成状态";

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • M̄ = 用 kda_chunkwise(k, v=0, S₀=I) 跑出"纯过渡矩阵"(v=0 时写入项消失,只剩过渡项)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  两个量都是"从零/恒等出发跑一段 chunkwise"得到的,所以共用同一个 kernel,数学上严格吻合 delta rule。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  8.5 落地架构与数据结构(parallel/kcp.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    local_transition_and_state(k, v, g, beta)     计算单段 (M̄, S̃)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        S̃:  用 kda_chunkwise(k, v=真实值, S0=0)   → 段自生成状态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        M̄:  用 kda_chunkwise(k, v=0, S0=I)         → 纯过渡矩阵(homogeneous 响应)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             # 为什么 v=0, S0=I 得到 M̄?v=0 时写入项 β·k·vᵀ 消失,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             # 只剩过渡项,从 S0=I 出发跑完段得到的就是累积转移矩阵


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    prefix_scan_states(transitions, zero_states)   前缀扫描
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        incoming[0]   = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        incoming[i+1] = transitions[i] @ incoming[i] + zero_states[i]


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    kcp_forward(q, k, v, g, beta, n_segments)      三段式总入口
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        # 阶段1: 每段算 (M̄, S̃)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        # 阶段2: prefix_scan 重组入态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        # 阶段3: 每段用 incoming[i] 重跑 chunkwise


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDAContextParallel                       封装 + 通信量
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        communication_volume(batch, heads, dk, dv, world, itemsize)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            = batch·heads·(dk² + dk·dv)·itemsize · world
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # 注意:公式里没有序列长度 T!这就是 KCP 的核心卖点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    具体代码如下:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """KDA Context Parallelism(KCP:Kimi Delta Attention 上下文并行,论文 §5.1.2 / Eq.17)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      设计动机(why)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      --------------
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      KDA 的状态更新是 **delta rule**:每个 token 不仅"写入"一条 k v 外积,还会通过
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      (I - beta_k k k^T) 这个 **逐 token 依赖的过渡矩阵** 去缩放左右两侧既有的状态。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          S_r = (I - beta_r k_r k_r^T) Diag(alpha_r) S_{r-1} + beta_r k_r v_r^T


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      因此,把序列切成多段分别计算时,一段的效果**不能**像 vanilla 线性注意力
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      (S = sum k v^T,天然可加)那样简单相加或拼出一个闭式前缀和:


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          vanilla : S_{[i+1]} = S_{[i]} + 段内累加量          (可加,可前缀和)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA     : S_{[i+1]} = Stilde_{[i+1]} + M_{[i+1]} S_{[i]}  (仿射,逐段不同 M → 需扫描重组)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      KCP 的解法是把每段内部的效果拆成**两个局部量**,再做一次仿射链的"前缀扫描":


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        * M_{[i]}    —— 段内累积过渡矩阵(homogeneous / 齐次响应):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          令 v = 0 且初态 S_0 = I,delta rule 完全退化为纯过渡
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          S -> (I - beta k k^T) Diag(alpha) S,所有 token 的过渡矩阵
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          逐段复合得到 M_{[i]};
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        * Stilde_{[i]} —— 段从零初态"自生成"的状态:S_0 = 0,直接跑 chunkwise。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      读出口按 S_{[i+1]} = Stilde_{[i+1]} + M_{[i+1]} S_{[i]} 前缀扫描重组各段的**入向
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      状态**(incoming),再用 kda_chunkwise(initial_state=incoming[i]) 得到段内输出。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      本实现 CPU 单进程:以 n_segments 分段模拟真实的 world 个 rank,不引入
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      torch.distributed。rank 间只交换 (M, Stilde),通信量(字节)与序列长度无关。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      (下接函数定义)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      8.5.1 local_transition_and_state(计算每段的 M̄ 和 S̃)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        def local_transition_and_state(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            k: Tensor, v: Tensor, g: Tensor, beta: Tensor,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            *, chunk_size: int = 16, dtype: torch.dtype | None = None,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ) -> tuple[Tensor, Tensor]:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """计算单段的两个局部量 (M_{[i]}, Stilde_{[i]})。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Returns:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                (m_cum, s_tilde):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                - m_cum    (B, H, Dk, Dk):段内累积过渡矩阵 M_{[i]}。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                - s_tilde  (B, H, Dk, Dv):段从零状态自生成的状态 Stilde_{[i]}。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            数值设定:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                用 eye 作 initial_state + zero_v 的调用,从 S_0 = I、v = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                出发,状态递推退化为纯过渡矩阵连乘,得到的最终状态正是 M_{[i]}。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                这样的好处是 M 与 S 在同一次 chunk 化实现里用**相同代码路径**算出,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                数学上严格吻合 delta rule 的复合结构。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            dtype = dtype or (torch.float64 if k.dtype == torch.float64 else torch.float32)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            b, h, _t, dk = k.shape


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # Stilde_{[i]}:段从 S=0 开始,自身激活(v 非零)产生的状态。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # q 用 k 占位 —— 我们只需要返回值中的 state,与序号无关,q 只影响输出 out(丢弃)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            _, s_tilde = kda_chunkwise(k, k, v, g, beta, chunk_size=chunk_size, dtype=dtype)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # M_{[i]}:homogeneous 响应。v=0 之后 KDA 的写入项 (beta k v^T) 消失,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            # 只剩过渡项,给定 S0=I,最终 state 就等于段内的累积过渡矩阵。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            eye = torch.eye(dk, dtype=dtype, device=k.device).expand(b, h, dk, dk).contiguous()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            zero_v = torch.zeros_like(k)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            _, m_cum = kda_chunkwise(k, k, zero_v, g, beta, chunk_size=chunk_size,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    initial_state=eye, dtype=dtype)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            return m_cum, s_tilde

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        要点:M 与 Stilde 用同一套 kda_chunkwise 代码路径算出来,只是换初态(S0=I vs S0=0)和 v(v=0 vs v 原值)——数学上严格吻合 delta rule 的复合结构。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        8.5.2 prefix_scan_states(前缀扫描重组)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          def prefix_scan_states(transitions: Tensor, zero_states: Tensor) -> Tensor:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """基于每段 (M, Stilde) 的前缀扫描,恢复各段的**入向**状态。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Args:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  transitions: (n, B, H, Dk, Dk) 每段的过渡矩阵 M。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  zero_states: (n, B, H, Dk, Dv) 每段零态激活产生的 Stilde。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Returns:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  incoming (n, B, H, Dk, Dv):incoming[i] 是段 i **带着**
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  进入执行的状态(incoming[0] = 0)。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              核心递推(对扫描 self-consistency):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  incoming[0]     = 0
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  incoming[i+1]   = transitions[i] @ incoming[i] + zero_states[i]


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              即:段 i+1 的入态 = 「段 i 过渡到它自身」+ 「段 i 从零状态自主生成的状态」。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              这正是 delta rule 与 vanilla 线性注意力的根本差异所在 —— 状态不直接可加,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              必须用一个逐段不同的仿射变换来传递。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              n = transitions.shape[0]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              incoming = torch.zeros_like(zero_states)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              state = torch.zeros_like(zero_states[0])
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              for i in range(n):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  incoming[i] = state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  state = transitions[i] @ state + zero_states[i]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              return incoming

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          8.5.3 kcp_forward(三阶段总入口)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            def kcp_forward(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                q: Tensor, k: Tensor, v: Tensor, g: Tensor, beta: Tensor,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                *, chunk_size: int = 16, n_segments: int = 4,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                dtype: torch.dtype | None = None,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ) -> tuple[Tensor, Tensor]:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                """把序列切成 n_segments 段,按 KCP 三段式顺序计算。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                三阶段:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1. 分片:把序列沿 T 均分成 n 段(要求 T % n_segments == 0)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  2. 并行计算各段的局部量 (M, Stilde)(真正的分布式中这段在 rank 之间)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3. 前缀扫描重组出各段入状态,再用 kda_chunkwise(initial_state=incoming[i])
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     逐段产出输出并把状态推到末尾。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                dtype = dtype or (torch.float64 if q.dtype == torch.float64 else torch.float32)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                b, h, t, dk = q.shape
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                dv = v.shape[-1]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                if t % n_segments != 0:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    raise ValueError(f"length {t} not divisible by n_segments {n_segments}")


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                step = t // n_segments
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                segs = [slice(i * step, (i + 1) * step) for i in range(n_segments)]


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                # --- 阶段 1:每段局部 (M̄, S̃)(分布式下这段在各自 rank 本地并行执行)---
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                m_all, s_all = [], []
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                for sl in segs:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    m_, st_ = local_transition_and_state(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        k[:, :, sl], v[:, :, sl], g[:, :, sl], beta[:, :, sl],
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        chunk_size=chunk_size, dtype=dtype,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    )
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    m_all.append(m_)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    s_all.append(st_)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Ms = torch.stack(m_all, dim=0)   # (n, b, h, dk, dk)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                Ss = torch.stack(s_all, dim=0)   # (n, b, h, dk, dv)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                incoming = prefix_scan_states(Ms, Ss)   # (n, b, h, dk, dv)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                # --- 阶段 2:逐段用 incoming 重新计算真实输出 ---
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                outs = []
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                state = incoming[0]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                for i in range(n_segments):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    out, state = kda_chunkwise(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        q[:, :, segs[i]], k[:, :, segs[i]], v[:, :, segs[i]],
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        g[:, :, segs[i]], beta[:, :, segs[i]],
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        chunk_size=chunk_size, initial_state=incoming[i], dtype=dtype,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    )
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    outs.append(out)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                return torch.cat(outs, dim=2), state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            8.5.4 通信量 & 并行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              class KDAContextParallel:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  """携带 chunk_size 的 KCP 封装器,供报告使用。"""


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  @staticmethod
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  def communication_volume(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      batch: int, heads: int, dk: int, dv: int, world: int, itemsize: int = 8
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ) -> int:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """每 rank 每 KDA 层交换 (M, Stilde) 的字节数 —— 与序列长度无关。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      M:    Dk x Dk 过渡矩阵
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Stilde: Dk x Dv 零状态生发
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      每个 rank 存外传这两块给其余 world-1 个 rank。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      返回整个集群一次 KDA 层的交换总量(字节)。动态大小时保持不变;
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      world 翻倍时总量翻倍(一条链路多收发一份)。
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      """
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      per_rank = batch * heads * (dk * dk + dk * dv) * itemsize
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      return per_rank * world

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              通信量(kcp.py:200-214):每 rank 每 KDA 层交换的是 (M, S̃ / Stilde) 两个定长张量,大小与序列长度无关——这是 KCP 对长上下文的核心卖点:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • M_{[i]}:(B, H, Dk, Dk) — 段内累积过渡矩阵(d×d)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • S̃_{[i]}:(B, H, Dk, Dv) — 段从零初态自生成的状态(d×d)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              每 rank 总字节 = B · H · (Dk² + Dk·Dv) · itemsize,与序列长度 T 无关(这就是 KCP 的核心卖点)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              并行 vs 串行(kcp.py:152-180):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              计算方式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              并行性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              M_{[i]}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              每段独立调用 kda_chunkwise(q=k, v=0, S₀=I)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              完全并行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              (段与段之间无依赖,分布式下各 rank 本地算自己的)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              S̃_{[i]}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              每段独立调用 kda_chunkwise(q=k, v, S₀=0)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              完全并行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              (同上)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              incoming[i]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              (前缀扫描)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              incoming[i+1] = M[i] @ incoming[i] + S̃[i]本质串行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              (递推依赖上一段结果;但只是 n 次 d×d 矩阵乘,开销远小于段内计算)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              S_out[i]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              (最终输出)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              每段用 kda_chunkwise(initial_state=incoming[i]) 重算

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              完全并行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              (拿到入态后段间又独立了)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              即**"两并行 + 一短串行 + 再并行"**:第一段并行求 (M, S̃),然后一次 O(n) 前缀扫描(n = rank 数,通常 ≤ 8),最后再并行计算输出。串行段的代价是 O(n · d³),与序列长度无关,可忽略。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              8.6 数据流 / 执行流

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                kcp_forward(n_segments=4, chunk_size=16):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1. 分片:把序列沿 T 均分成 4 段(要求 T % 4 == 0)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  2. 每段本地算 (M̄, S̃):local_transition_and_state()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3. 前缀扫描:prefix_scan_states() → 得到每段入态 incoming[i]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  4. 每段用 incoming[i] 作为 initial_state,重跑 kda_chunkwise() → 输出 + 推到末尾
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  5. 拼接各段输出,返回 (out, s_final)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.7 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                「现在大上下文直接整段塞上去不就行了,何必卷 KCP?」seq_len → ∞ 时,整段传输成本与 T 相关(随序列翻倍);KCP 的通信量与 T 无关(只随模型维度),是唯一能随上下文翻倍的方案。而且 KCP 依赖「状态廉价搬移」(统一页池的 pack_heads head-contiguous 布局),两个组件在这里汇合——这不是巧合,是设计使然。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                「为什么说通信量与序列长度无关?」 因为跨 rank 交换的只有 (M̄, S̃)——它们都是固定尺寸(dk×dk 和 dk×dv),不随段内 token 数变化。communication_volume 公式里没有 T,这正是要断言的属性。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.8 何时用 / 何时不用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 何时用:长序列(上下文 > 单设备容量)需要跨设备并行;此时「每段独立算 (M̄,S̃) + 一次固定 all-gather + 前缀扫描」是唯一通信量不随 T 增长的方案。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 何时不用:短序列(单设备放得下)——KCP 的通信开销反而是浪费;纯 MLA 模型没有 KDA 状态,用普通 KV 拼装即可。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.9 实测数值(CPU 可复现)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 直接相加误差(错误做法):9.782e-01

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • KCP 前缀扫描误差(正确做法):1.110e-16

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 通信量对比:KDA 恒定 2048 字节/rank/层,softmax 在 1M token 时达 1.07e9 字节

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                一句话结论:KCP 把"不可加的仿射状态链"拆成每段两个局部量(M 齐次响应 + Stilde 零态自生成),再用 S ← M S + Stilde 前缀扫描重组各段入状态,最后每段用 initial_state=incoming[i] 重算输出。误差到机器精度,通信量 O(1)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.10 验证

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tests/parallel/test_kcp.py(3 项):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • test_kcp_forward_matches_recurrent(并行分段与全局递推数值一致 ✅)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • test_communication_volume_scales_with_world(固定 rel 值线性)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • test_local_transition_state(M̄ 用 identity/S₀ 构造 + 覆盖)


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x09 组件六:Fleet 层调度(serve/fleet.py)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9.1 它要解决什么问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                前 5 个组件解决「单个实例内」的请求效率(缓存怎么用、状态怎么复用、怎么回滚、怎么并行)。Fleet 层把视角提升一层:真实线上不是一台机器,而是几十上百台组成的 fleet(集群组)。Fleet 层回答两个单实例不存在的问题:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                1. 缓存命不命中,不由单实例决定:一个请求可能被路由到任何一个集群。如果落在「没缓存这个前缀」的集群,就得整个重新 prefill。K3 报告的关键数字:1M 上下文下,典型编码请求的 prefix 达 400K token,而 prefill increment 只有 4K——命中一次避免重算 400K 前缀,比 miss 便宜几个数量级。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                2. 一个超长请求能拖垮整个 fleet:短请求 <2K token、超长请求可达 1M token,单请求长度横跨 3 个数量级。长请求突发一旦占满总容量,会把所有短请求的 TTFT 全线拖垮。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9.2 难在哪

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 亲和性 vs 故障的矛盾:要让命中率高,就得把 session「绑定」到持有其前缀缓存的集群(cache-aware affinity)。但绑定 = 绑死,主集群一旦故障,所有绑定它的 session 全部中断。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 长度方差大:3 个数量级的长度差,固定总容量下,长突发必然挤死短请求。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9.3 总体思路(两个策略)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                策略 1:cache-aware affinity scheduling + 一致哈希双绑定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                把请求路由到「持有其 prefix cache」的集群。但为了避免「绑死单集群」的故障风险,用一致哈希把每个 session 绑定到 primary + secondary 两个集群:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • primary 正常服务(持有该 session 的前缀缓存,命中率高);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • secondary 在 primary 失效时接管,重新 prefill;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • 各 session 的 secondary 由一致哈希均匀分布到整个 fleet——re-fill 的工作量被分散,而不是集中到故障点一处。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                策略 2:budget-based admission control(预算准入)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                为不同请求类分配独立资源预算,短类、长类各查各的配额,互不占用。突发长上下文只能消耗自己那份 capacity,不拖累其他类的 TTFT。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9.4 背后的原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                为什么一致哈希能「分散 re-fill 工作量」? 一致哈希的最小扰动性质(hopscotch):移除/新增一个集群时,只有 O(1/N) 的 session 需要改路由。因为每个集群在环上放多个虚拟节点(vnodes),session 落在哪个节点上是「均匀随机」的——去掉一个集群,只影响「原来指向它」的那部分 session,它们各自换到新的 primary/secondary,于是 re-prefill 的负载被均匀地摊到全 fleet,而不是某个集群被压垮。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                为什么预算隔离能保住短请求 TTFT? 因为短类和长类各占各的预算。长请求突发时,它只能在长类的预算内接;超出的被拒绝/降级。短类配额不受影响,所以短请求的 TTFT 不会因为「后面排了一堆长请求」而飙升。这是「predictability(可预期性)」——报告用这个词表达:长突发牺牲自己的延迟,换取全系统短请求的 SLO 可预期。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                9.5 落地架构与数据结构

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ConsistentHashRing             # 一致哈希环
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      _ring: [(pos, cluster_id)]   按位置升序
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      add_cluster(id, vnodes=8)   每个集群放 8 个虚拟节点
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      remove_cluster(id)          摘除该集群全部虚拟节点(最小扰动)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      route(session) -> (primary, secondary)   md5(session) 顺时针 → primary,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               再顺移取下一个不同集群 → secondary


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Request (@dataclass)           # 一条请求
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      session_id / request_class(short|long) / prefix / prompt_len / arrive_time


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ClusterInstance                # 一个 serving 集群
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      cache: PrefixCache         复用现有模块(真实命中判定)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      pool: PagePool             复用现有模块(页占用)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      register(tokens)           登记前缀 + persist KDA checkpoint
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      reused_tokens(...)         PrefixCache.lookup + recompute_saved(真实命中)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      serve_cost(prompt_len, reused)  命中只算增量,miss 整段


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  BudgetController               # 预算准入控制
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      budgets: {short, long}     各自独立配额
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      weights: {short:1, long:3} 长请求占 3 份容量
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      admit(class, usage)        该类再加一请求(占 weight 份)是否在预算内


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  FleetSimulator                 # 顶层事件驱动仿真
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      run(requests)              按到达时间排序 → 预算 → 路由 → 命检 → 定价 → 统计
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      fail_cluster(id)           令集群失效(摘环 + alive=False)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      results()                  hit_rate / total_cost / P95 TTFT / rejected / failover

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Fleet 调度模块纯 CPU、纯标准库依赖(md5 + bisect),与 prefix_cache.py 同级独立。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  一致哈希环:把 session 稳定映射到 (primary, secondary) 两个集群。虚拟节点保证各集群负载均匀,同时保证「移除/新增一个集群只扰动 O(1/N) 的 session」——这正是 failover 后 re-prefill 工作量被均匀分散的基础。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ClusterInstance 的关键点:命中判定不是拍一个概率参数,而是委托现有 PrefixCache 的 lookup / recompute_saved —— 因此这里的命中率与 serve 层真实模块一致(chained-hash 匹配 + KDA checkpoint 原子性),这是本仿真「可信」的来源:代价数字不是凭空编的,而是真实缓存行为折算出来的。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  代价模型:work / throughput。命中时只重算 prompt_len - reused 的增量;未命中则整段重新 prefill。当 reused 接近 prompt_len 时,miss/hit 的代价比是数量级。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  BudgetController:短请求 <2K 与超长 1M 混流,长度横跨 3 个数量级——若总容量固定且没有隔离,长请求突发会把短请求的 TTFT 全线拖垮。给每类独立预算后:长突发只能吃掉自己的配额,短请求配额不受影响。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  权重:每类请求占用不同份容量(短=1、长=3),预算数字是「容量单位」而非「请求条数」。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  时间模型(CPU 无法真跑 1M token,用公式折算):

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • prefill 代价 = serve_cost;TTFT = 集群当前累计负载 / throughput(队列近似)+ 本次 prefill 代价。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 路由:session 绑定的 primary 存活走 primary;失效则走预分配的 secondary 并累加一个 re-prefill 成本。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  run() 产出每请求明细;results() 汇总命中率 / 总代价 / 分请求类 P95 TTFT / 拒绝数 / failover / 负载标准差。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  9.6 数据流 / 执行流

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    FleetSimulator.run(requests):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      对每个请求(按 arrive_time 排序):
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        1. budget.admit(request_class, usage)   → 拒绝则 rejected[class]+1,跳过
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        2. primary, secondary = ring.route(session_id)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           若 primary 失效 → 走 secondary,failover_count+1,re_prefill_cost += prompt_len
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        3. reused = cluster.reused_tokens(prefix, prompt_len)   # 真实命中
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           cost = cluster.serve_cost(prompt_len, reused)        # 命中=增量,miss=整段
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4. 先查后登记:cluster.register(prefix)   # 前缀在"这次请求之后"才对未来请求可见
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           ttft = 集群累计负载/throughput + cost
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        5. 更新统计

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    为什么「先查后登记」? 这保证:首次请求必然 miss,第二次同前缀请求才命中——这正是「命中一次避免重算整个前缀」的语义来源。如果先登记再查,第一次请求就会命中「自己刚塞进去的前缀」,那是假命中。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    9.7 反方辩手

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    「budget 会把合法请求拒绝掉?」 是的,长类超预算会被拒。但这是设计的权衡:牺牲长类突发延迟,换取全系统短请求 TTFT(SLO)可预期——这正是报告「predictability」一词的意思。代价不是 bug,是特性。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    「一致哈希的 secondary 平时闲着不浪费吗?」 不浪费——它正是「primary 故障时的既定容器」。各 session 的 secondary 由一致哈希均匀分布,所以 re-fill 负载被均匀分散。这是「接受 secondary 闲置」换取「故障时负载分散」的权衡。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    「CPU 上没法真跑 1M token,代价数字可信吗?」 用 cost = work / throughput 折算时间,命中/未命中的数量级差异由 token 数决定(400K vs 4K),与推理设备无关——比值仍是数量级(实测 ~781×)。数字是「真实缓存行为折算出来的」,不是拍脑袋。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    9.8 何时用 / 何时不用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 何时用:多实例 serving,请求共享前缀(亲和路由能命中)、流量长短混排(预算隔离能保 SLO)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 何时不用:单实例(没有「路由到哪个集群」的问题);请求无共享前缀(亲和路由无处命中,退化成普通负载均衡)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    9.10 可视化

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    plot_fleet.py — 集群级调度 (serve/fleet.py,报告 §5.4.3 / V3 附录 D)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • fig_affinity():ConsistentHashRing 的 cache-aware 亲和路由 —— 200 个 session 各发两次同前缀请求(有路由)vs 400 个不同 session(无路由),对比命中率;再用 serve_cost 对比 miss/hit 的 prefill 代价倍数(对数轴)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • fig_budget():预算隔离 —— 20 个长请求(1M token)与 60 个短请求混流,short_budget=long_budget=8 vs 无预算(1e9),对比短/长请求 P95 TTFT 以及各类被拒数量(长请求被限流、短请求零拒绝)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 产出:plot_fleet_affinity.png、plot_fleet_budget.png

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    plot_fleet_affinity
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    plot_fleet_affinity
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    plot_fleet_budget
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    plot_fleet_budget

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    0x10 收官引擎:把它们咬合成一个「第二个请求到底省了什么」

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    10.1 它要解决什么问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    前 5 个组件各是独立子系统。收官引擎(serve/engine.py + experiments/serve/demo_engine.py)回答工程上一个很朴素的问题:第二个请求复用了同一个前缀时,到底省了什么? 它把「统一页池 + 前缀缓存 + KCP」串成一个可以对照的 before/after。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    10.2 总体思路与原理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • before(无前缀缓存):第二个请求从头 re-compute——MLA 侧重新 prefill 全部 512 token(再占一页),KDA 侧重新走完整递推(重算 checkpoint);

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • after(有前缀缓存):MLA 的 KV 页逐块命中直接复用,KDA 从 checkpoint 快照处恢复 O(1) 状态,免去全部重算。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    省下的正是 recompute_saved 报告的 token 数(本例 512 vs 0)。run_once(hash_present) 是可导入的纯函数(无 IO、无随机),实验脚本与集成测试共用。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    10.3 落地与实测

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    run_once 返回四项指标:reused_tokens(512 vs 0,本实验核心)、pages(首请求在统一页池占的页数,验证「一请求一份状态」)、comm_bytes(KCP 每层跨 8 rank 交换 (M̄,S̃) 的总字节,验证「与序列长度无关」)、pool_utilization(页池利用率)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    demo_engine.py  (serve/engine.py + parallel/kcp.py)是命令行可视化入口,产出 before/after 对比图 + 通信字节对比。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 表达:把前面各模块串成一次端到端引擎调用的三合一汇总图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 测试:run_once(hash_present=True/False) 对比第二个请求的 reused_tokens(前缀复用);MLA KV 字节随长度线性 vs KDAContextParallel.communication_volume 恒定;第三子图单独强调 KCP 通信量对序列长度是 O(1)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 产出:demo_engine.png

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    demo_engine
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    demo_engine

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    附录


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    附录 A:跨仓库核对 — group 语义与每层状态的归属

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    本附录回答一个反复出现的疑问:kda_checkpoints 到底是每层一份、每 token 一份,还是每个 group 一份?一个 PrefixCache 对应一个前缀吗? 结论来自三处独立实现的交叉核对:kimi3-master、kimi-k3-pytorch-main、SGLang K3 分支。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    A.1 kimi3-master(本项目镜像的来源)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    kda_checkpoints: dict[int, set[int]] 是"记账本",不是"储物架"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      # 原文注释:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      #: Number of independent KDA cache groups a checkpoint must exist in.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      n_kda_groups: int = 1
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      #: ``group -> set of token boundaries with a persisted KDA checkpoint``.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      kda_checkpoints: dict[int, set[int]]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • n_kda_groups 默认 1;kda_checkpoints 的 key = 抽象 group 编号,value = 一组 token 边界位置(512 对齐的整数)。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 一个 PrefixCache 存的是"大量 token 边界",不是"一个前缀"——value 是 set[int],可以装上千个边界。"一个 ClusterInstance 只有一个 PrefixCache → 只有一个前缀"是误读。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 真正的"每层一份状态"在 paged_cache.py:kda_pages: dict[int, int](layer -> page)与 store_kda(layer, state) / load_kda(layer, ...)。但 PrefixCache 与 PagedCache互相之间没有任何关联代码——一个管"哪个边界有没有 checkpoint",一个管"每层状态存到哪里"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      A.2 kimi-k3-pytorch-main(模块化参考)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      状态确实每层独立一份,但仓库里完全没有前缀缓存机制。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • HybridLayerCache = (attention_type, state),KDA 层配 KDAState,MLA 层配 MLACache;HybridBackboneCache 是每层一个 cache 的有序元组。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 没有跨请求复用:推理流程是单次 prefill + 逐 token decode。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • README 明确:"不包含 paged attention、continuous batching、quantized caches、distributed serving"。因此该仓库只提供状态对象与数学参考(KDAState、recurrent_kda/chunkwise_kda),前缀缓存机制需要自行设计。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • "group"在此仓库只是架构拓扑的命名((kda, kda, kda, gated_mla) 模式重复 num_hybrid_groups 次),不进入任何向量数学。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      A.3 SGLang K3 分支(生产实现)—— 前缀复用的事实真相

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      一条请求的 KDA 状态,是一个"把所有 KDA 层叠在一起"的大张量,"存放到某个 token 边界"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        # memory_pool.py:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        temporal_state = torch.zeros(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            size=(num_mamba_layers, size + 1) + temporal_state_shape, ...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 注意第一维就是 num_mamba_layers——一个 slot 装下"token 边界处所有 KDA 层的递归状态"。每层在自己维度,但整体作为一块分配与搬运。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        前缀树(radix)在"对齐的 token 边界"存整包状态,而不是按层存:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 在 len(prefix_indices)+extend_len 到达 mamba_cache_chunk_size 对齐点时,把当前状态写入 radix 缓存节点。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • radix 树每个节点持有 mamba_value(device 上的状态快照),命中前缀时 copy-on-write 把它装到新的活跃 slot 再继续解码。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 缓存侧状态 int8 压缩(按 per-head/k-channel 对称量化)存放在独立 checkpoint 池;命中一次反量化一次,"从没重入一次量化-反量化循环"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        "group"字面量在 SGLang K3 分支全部 grep 为零——SGLang 的做法是把"所有 KDA 层的整包状态"当成一个不可分割的缓存值。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        A.4 合成的结论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        疑问

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        答案

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        kda_checkpoints

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         是每层一份吗?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        不是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        。key=抽象 group 编号(默认 1),value=token 边界集合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        每个 PrefixCache 只有一个前缀?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        不是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        。value 是 set,可存无数 token 边界

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        每层的状态到底存哪?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        kimi3-master:paged_cache.py 的 kda_pages(未接线);kimi-k3-pytorch:每层 HybridLayerCache;SGLang:单 slot 内 dim=layers 的整包张量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        生产里"一个边界"是什么?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        一个 token 位置

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ,对应"所有 KDA 层那一份整包状态快照"(radix 节点)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        "group"字面量在生产中存在吗?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        在 SGLang 不存在;在 kimi3-master 是设计抽象(默认 1),对应"整包被当作一个对象"

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        核心洞见:所有实现最终都收敛到同一件事——cache 的原子性单位 = "某一 token 边界的整包多层状态"。kimi3 把这一体化思想用 group(抽象编号,默认 1)表达,SGLang 直接用一个"叠了所有层的 slot"。group 不是层的别名,而是——把"某一 token 处必须一起存在的东西"表达为一个原子单位的编号。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        附录B: 与 vLLM KV Cache Group 的对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        当前项目中的group,与 vLLM 的 KVCache Group有相似的“分组后共同管理/共同满足约束”的思想,但不是同一个抽象,也不存在一一对应关系。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        更准确地说:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 项目中的 group 是 KDA checkpoint 的逻辑原子性分区;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • vLLM 中的 KVCache Group 是 具体 cache layer/spec 的物理与调度管理分组。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        因此,项目的 group 更接近“多个缓存状态必须同时可恢复”的约束;vLLM 的KVCache Group 则是“哪些层共享一个 block table、如何共同分配和布局缓存”的实现对象。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        B.1. 项目中的 group 是什么

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        核心数据结构是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          kda_checkpoints: dict[int, set[int]]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          它表示:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            group_id -> 该 group 已保存 KDA checkpoint 的 token 边界集合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            n_kda_groups 只决定需要维护多少个逻辑 group。代码没有记录 group 对应哪些 Transformer 层,也没有记录 group 的 page size、block table 或物理内存布局。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            项目通过以下逻辑判断某个边界是否可恢复:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              def checkpoint_available(self, boundary: int) -> bool:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  return all(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      boundary in group
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      for group in self.kda_checkpoints.values()
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  )

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              也就是说,边界 B 只有在所有 group 都有 checkpoint 时才可用。缺少任意一个group,该边界就不能用于恢复 KDA 状态,lookup() 会退回到更浅的可用边界。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              因此,这里的 group 主要回答:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                在 token 边界 B,恢复所需的所有状态分区是否都已经准备好?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                它不直接回答:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  这些状态应该放在哪个物理 block?
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  哪些层共用一个 block table?
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  每个 block 需要多少显存?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  B.2. vLLM 中的 KVCache Group 是什么

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  vLLM 首先为每一层建立 KVCacheSpec,然后将适合共同管理的 cache layer 放进 KVCacheGroupSpec。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  一个 vLLM KVCache Group 通常包含:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 明确的 layer_names;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 这些层各自的 KVCacheSpec;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 共同使用的一张 block_table;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 由组内各层 page size 共同决定的 block 大小;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 与共享 BlockPool 配合的分配、回收和物理布局。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  例如,MLA 层和 Indexer 层可以放进同一个 UniformTypeKVCacheSpecs,使一个 block 同时包含多个 MLA page 和多个 Indexer page。该 group 的 block 不是抽象的“checkpoint 存在性标记”,而是真实的缓存存储与寻址单位。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  vLLM 的 group 划分还会受到以下因素影响:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 层的 cache spec 是否兼容;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • block size 是否相同;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • page size 是否适合放在同一个物理 block;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 不同层的生命周期是否一致;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • block table 和底层 kernel 的寻址、对齐要求。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  因此,即使两层的 cache spec 看起来相同,也可能因为物理布局或 page size 约束被拆成不同的 vLLM group。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  B.3. 逐项对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  维度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  当前项目 PrefixCache 的 group

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  vLLM KVCache Group

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  主要对象

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KDA checkpoint 集合

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  具体 cache layer 与 cache spec

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  主要目的

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  保证某边界的 KDA 状态可整体恢复

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  共同管理 cache block、block table 和物理布局

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  组成员是否显式记录

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  否,只记录整数 group ID

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  是,通过 layer_names 和 spec 记录

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  是否绑定 Transformer 层

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  不绑定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  直接绑定

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  是否描述 page/block 大小

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  不描述;physical_block 只是抽象 ID

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  描述并参与显存分配和布局

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  是否有 block table

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  没有

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  有,每个 group 对应一张 block table

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  lookup 约束

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  所有逻辑 group 在同一边界都有 checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  各 cache group 的命中结果需要协调到共同可执行长度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KDA 状态处理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  用 checkpoint 边界集合抽象表示

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  通过 Mamba/KDA cache group 管理状态 block

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  物理内存语义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  PrefixCache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   中没有真实内存布局

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  直接关联共享 BlockPool 和物理 block

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  当前默认粒度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  n_kda_groups=1

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ,整个 KDA 状态视为一个逻辑组

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  根据层、spec、block size 和布局规则划分多个组

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  B.4. 两者为什么容易被认为相同

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  两者都体现了一个共同思想:某些缓存对象不能完全独立处理,需要把它们作为一个整体协调。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  在当前项目中,这体现为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    所有 group 都有 checkpoint => 该边界可恢复

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    在 vLLM 中,这体现为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      相关 cache layer 放进同一个 KVCache Group
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              => 共享 block table,并以统一方式分配/访问

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      两者还都服务于 hybrid attention 的 prefix cache:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • MLA/Full Attention 可以按 token block 进行前缀匹配;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • KDA/Mamba/Linear Attention 需要在某些边界保存可恢复状态;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 最终可执行的 prefix hit 需要满足不同缓存部分的共同约束。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      因此,概念上可以说它们都在表达“缓存复用的协调单元”,但协调的对象不同。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      B.5. 最接近的对应关系

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      如果只从“必须共同满足条件”这个角度看,项目中的多个 group 可以类比为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        多个需要共同命中的缓存状态分区

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        而不是 vLLM 中的某一个 KVCache Group。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        更接近的关系是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          项目的 group 集合
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ≈ 一组需要共同满足 checkpoint 条件的逻辑缓存分区


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          vLLM 的 KVCache Group
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ≈ 一组明确映射到层和 cache spec、共享物理管理结构的缓存对象

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          如果未来项目将每个 KDA 状态分区显式映射到具体层,并为每个分区实现独立的 cache spec、block table、物理 block 分配和回收,那么这些逻辑 group 才可能进一步演化为类似 vLLM KVCache Group 的对象。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          当前代码尚未完成这一步,因此不能把:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            n_kda_groups

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            直接解释为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              vLLM 中的 KVCache Group 数量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              B.6. 关键差异:checkpoint 原子性 vs. 物理 cache 管理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              6.1 项目 group 解决的是恢复正确性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              项目的核心不变量是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                KDA 在边界 B 的完整状态必须可恢复

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                所以使用 all() 检查所有 group 是否都有 checkpoint。group 的边界是“缺少任意一份状态就不能恢复”的逻辑边界。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                6.2 vLLM group 解决的是存储和调度一致性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                vLLM 的核心问题是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  不同 cache layer 如何共享 block table、BlockPool 和物理布局

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  因此 vLLM group 的划分会考虑 page size、block size、内存碎片、kernel 寻址 和生命周期等工程因素。它不是简单地保存一个“该边界是否存在”的集合。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  6.3 两者可以同时存在

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  在一个完整的 hybrid serving 实现中,二者可能同时出现:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1. vLLM KVCache Group 负责实际的 layer/block/table/显存管理;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  2. 更高层的 checkpoint 原子性逻辑负责判断多个 group 的状态是否能共同恢复;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3. prefix-cache coordinator 再将 MLA 命中长度与 KDA checkpoint 边界对齐。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  因此,二者不是互斥的替代关系,而可能是不同层次的抽象。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  B.7. 最终判断

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  判断问题

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  结论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  项目 group 是否就是 vLLM KVCache Group?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  不是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  是否存在设计思想上的对应?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  存在

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ,都用于协调一组不能完全独立处理的缓存对象

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  项目 group 是否对应具体 Transformer 层?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  当前代码没有表达

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  项目 n_kda_groups 是否等于 vLLM group 数?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  不能直接等同

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  当前项目默认 group 的含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  全部 KDA checkpoint 被视为一个逻辑原子整体

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  vLLM group 的核心含义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  一组显式 cache layer/spec 共享 block table 和物理缓存管理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  一句话总结:当前项目的 group 是“checkpoint 是否齐全”的逻辑分组;vLLM 的 KVCache Group 是“哪些 cache layer 共享 block 管理”的物理/调度分组。两者有抽象层面的关联,但当前项目中的 group 不能直接视为 vLLM 的KVCache Group。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  TransFormer-封面
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  TransFormer-封面

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  AI Infra进阶:3万字深入理解线性注意力机制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  阅读原文

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  跳转微信打开

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  •  

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  【轻量化复刻大模型 / KIMI K3】KDA 对 AI Infra 的挑战与各家应对

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  原创 罗西的思考 2026-11-05 20:45 北京

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  【轻量化复刻大模型 / KIMI K3】KDA 对 AI Infra 的挑战与各家应对

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x00 概要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x01. 先建立正确的心智模型

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 1.1 混合注意力的完整执行链

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 1.2 三种状态对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 1.3 KDA 的顺序性:可分段但必须保序

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x02. KDA 的优势与结构性限制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 2.1 优势

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 2.2 代价:固定状态不是完整档案

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x03. 为什么 Prefix Cache 与 KV Cache 不再等价

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 3.1 普通 Prefix Cache 为什么简单

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 3.2 KDA 为什么打破这个等价关系

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x04. KDA 给推理系统带来的新挑战

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 4.1 缓存对象从一种变成多种

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 4.2 状态恢复必须满足边界一致性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 4.3 活动态不能直接共享

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 4.4 PD/EPD 分离不再只搬 KV

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x05. SGLang 的应对思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 5.1 KDA‑aware Radix Tree

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 5.2 Sparse Checkpoint:为什么不是简单等间隔

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 5.3 Compressed Checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 5.4 COW、Snapshot 与 Donate

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 5.5 Unified Memory

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 5.6 Mooncake 的职责边界

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x06. SGLang 源码导航

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 6.1 源码地图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 6.2 模型层:`KimiK3DeltaAttention` 不是只做矩阵乘

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 6.3 统一入口:`RadixLinearAttention.forward`

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 6.4 `KDAKernelDispatcher`:不同阶段用不同 kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 6.5 SGLang 的 state 不是只有 recurrent state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 6.6 Checkpoint Pool 的真实实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 6.7 活动状态、Donate 与边界

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 6.8 checkpoint 何时产生

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 6.9 Unified Memory 的源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 6.10 SGLang 恢复流程总览

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x07. vLLM 的应对思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 7.1 State block 是什么

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 7.2 逻辑前缀与物理 state 解耦

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 7.3 Fine‑grained Partial Hit

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 7.4 Interval‑based 与 Marconi‑style Retention

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x08. vLLM 源码导航

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 8.1 源码地图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 8.2 KDA 执行和 state cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 8.3 metadata 如何找到 state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 8.4 Fine‑grained Partial Hit 的源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 8.5 Retention 的源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 8.6 vLLM 恢复流程总览

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x09. 深入讨论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 9.1 为什么 SWA 的 checkpoint 方法不能直接用于 KDA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 9.2 Checkpoint 密度的两难

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 9.3 跨实例复用与 PD/EPD 分离

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 9.4 概念与源码对应表

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 9.5 复现源码时的最小阅读顺序

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0x10. 最终结论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  0x00 概要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KDA 的固定状态设计让标准 serving 栈的若干组件失效,因此,各大推理引擎都对其进行适配:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  基础设施层

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  标准假设

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KDA 挑战

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  应对(参考实现)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  前缀缓存 Prefix Cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  缓存 KV 前缀

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  需缓存"状态 S"(无逐 token 条目)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  SGLang radix cache 纳入 temporal checkpoint(copy-on-write);kimi3-master prefix_cache.py 两级 hash

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KV 池 Memory Pool

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  统一 KV 页

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  混合模型(KDA+MLA)异构缓存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  SGLang MambaPool(conv + temporal)vs MLA KV 池;kimi3-master paged_cache.py::PageKind

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  上下文并行 CP

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KV 广播

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  状态跨段不可加

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KCP 前缀扫描

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  varlen 批量

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  cu_seqlens

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  每序列独立状态推进

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  cu_seqlens + 段偏移

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  投机解码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KV 截断回滚

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  状态需回滚/分支/重放

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  SGLang ReplaySSM(轨迹重放);kimi3-master ReplaySSM

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  CUDA Graph

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  静态 KV 布局

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  递推状态无法标准捕获

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ReplaySSM 折叠机制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  本文前半篇用概念性语言解释 KDA 为什么改变了推理缓存的正确性条件,以及推理框架如何在不破坏正确性的前提下节省显存和重算;后半篇给出源码导航,对应到 SGLang 与 vLLM 的具体文件与关键函数。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  注:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 项目https://github.com/RossiLH/Model-Viz 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。后续可能会跟踪新模型。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 全 CPU 复刻,不涉及 GPU,也不涉及大规模训练(这是另外一个庞杂深邃的领域)和硬件。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 模型的组件尽量是原始大模型的缩小版,如果组件没有开源版本,则用近似组件替代。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 会解释每个组件在解决一个什么问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。重点不是记名词,而是理解一条主线。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 每个主要组件都有可直接运行的 Gradio demo——无需 GPU。另有若干可视化脚本(plot_*.py),可生成静态图。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 为了保证每个文章可以尽量独立成文,所以有些内容会在不同文章中都存在,可能在系列层面上存在冗余,还请大家理解。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  0x01. 先建立正确的心智模型

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1.1 混合注意力的完整执行链

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Kimi K3 的混合注意力可以粗略画成:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    输入 token
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ├─ MLA ──> token-addressable KV/latent history
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        └─ KDA ──> convolution state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  └── recurrent state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        └── KDA 输出
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        └──────────> 混合输出

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    K3  特色

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    MLA 仍保留可按 token 或 block 访问的历史;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA 不保存每个历史 token 的完整地址,而是逐步更新一个固定大小的状态:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      S_t = M_t S_{t-1} + b_t
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • S_{t-1}:前一时刻长期记忆;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • M_t:当前 token 决定旧内容保留、衰减或变换多少;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • b_t:当前 token 写入的内容;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • S_t:处理完当前 token 后的长期状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      KDA 还常使用短卷积,因此要保存最近若干 token 的 convolution state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      区别

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      因此,传统 Transformer 的 KV Cache 可以看成 "按 token 编号的历史档案":

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        token 0 -> K,V
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        token 1 -> K,V
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        token 2 -> K,V
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ...

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        新 Query 到来时,系统可以读取任意历史 token。前缀缓存通常可以理解为:token 前缀相同,就能复用对应的 KV block。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        而 KDA 则把历史持续写入一个固定大小的 recurrent state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        所以,KDA 不是简单地把 KV Cache 换成另一种张量,而是把 "模型状态" 从一种扩展成了多种语义不同的对象。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        1.2 三种状态对比

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        状态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        记住什么

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        是否随新 token 更新

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        典型恢复方式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        是否可按 token 任意截断

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        MLA KV

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        历史 token 的可寻址表示

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        追加

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        读取 KV block

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        基本可以

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        KDA recurrent state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        整个前缀压缩后的长期摘要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        恢复 checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        不可以随意截断

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        KDA convolution state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        最近局部窗口

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        是

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        恢复局部窗口快照

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        需在合法边界保存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Recurrent state 决定长期记忆,convolution state 决定下一步局部卷积输出。两者都影响后续 token,因此不能只恢复 MLA KV。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        1.3 KDA 的顺序性:可分段但必须保序

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        对于KDA,我们把 token 段 C 对状态的整体影响记为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          F_C(S) = M_C S + b_C

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          两段连续执行的合并是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            F_{C_2}(F_{C_1}(S)) = M_{C_2} M_{C_1} S + M_{C_2} b_{C_1} + b_{C_2}

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            中间的 M_{C_2} b_{C_1} 很重要:第一段写入的信息,还要接受第二段的衰减或擦除。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            这解释了两件事:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1. 可以把一段 token 浓缩为一个 (M, b),所以能 chunkwise 并行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2. 不能把任意两个 token 段交换顺序,因为后一段会作用于前一段的写入。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            它满足结合律,所以可以先算小段、再合并;通常不满足交换律,所以 token 顺序不能随意调换。这个 "可分段但必须保序" 的性质,正是 KDA 能并行又能编码时序的原因。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Checkpoint 保存的就是某个前缀边界的结果,例如:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              token boundary 4096
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ├─ MLA KV prefix
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ├─ KDA recurrent state S_4096
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  └─ KDA convolution state C_4096

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              0x02. KDA 的优势与结构性限制

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2.1 优势

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              KDA 把长历史压进固定大小 state,主要收益是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • decode 不必反复扫描完整历史;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 历史读取带宽不再随上下文长度线性增长;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 状态可按 chunk 计算并通过仿射复合合并;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 衰减可以表达慢遗忘;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • delta 更新可以沿当前 key 定向覆写;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 适合作为长程 mixing 分支。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2.2 代价:固定状态不是完整档案

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              状态是压缩摘要,不是完整档案。一个固定 state 必须让任意长历史竞争有限容量:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                很多 token
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ↓ 压缩
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                一个固定状态矩阵
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                相似 key 可能碰撞
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                旧信息可能被衰减
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                未来 query 不能重新寻找原 token

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                两个相似 key 可能写入相近方向并互相干扰;一旦旧信息被衰减或覆盖,未来 query 无法像 Full Attention 那样重新找到原 token。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                因此 KDA 的 state 更像 "持续更新的寄存器文件",而 Full/MLA KV 更像 "可按地址读取的缓存"。Kimi K3 同时使用两者,正是为了让 KDA 负责高效 mixing、MLA 负责精确检索。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                KDA 的优势不是 "在所有任务上替代 Full Attention",而是用固定状态承担大多数长程 mixing,再由 MLA 等 token‑addressable 分支补足精确检索。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                0x03. 为什么 Prefix Cache 与 KV Cache 不再等价

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                3.1 普通 Prefix Cache 为什么简单

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                普通 Transformer 的 KV Cache 近似是一个追加式数组:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  prefix tokens: [A, B, C, D]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KV cache:  [K_A,V_A] [K_B,V_B] [K_C,V_C] [K_D,V_D]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  后续生成 E 时,只会追加 [K_E,V_E],不会修改 A、B、C、D 的 KV。因此:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    token 前缀相同 ≈ 对应 KV 相同 ≈ 可以直接复用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这就是 "Prefix Cache 与 KV Cache 几乎等价" 的来源。在普通 Transformer 中,前缀的 KV 是 "写完即稳定" 的:后续 token 不会修改前面 token 的 K/V。只要 token 前缀一致,缓存内容就一致。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    3.2 KDA 为什么打破这个等价关系

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA 的 state 不是每个 token 的独立记录,而是整个前缀递推后的结果:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      S_n = F_n(F_{n-1}(… F_2(F_1(S_0))))

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      其中每个 F_t 都代表一个 token 的状态更新。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      假设两个请求共享:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        请求 1: A B C D E
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        请求 2: A B C D X

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        它们在 A B C D 处的 KDA state 可以共享,但在 E 或 X 之后必须分开。共享的是一个稳定的前缀快照,不是可以被两个请求同时原地修改的活动状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        更重要的是,若系统只知道 token 前缀命中到 D,却没有保存 S_D,就不能仅凭 D 的 token 恢复 KDA。系统必须从更早的 checkpoint 重新执行:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          checkpoint at B
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ↓ replay C, D
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ↓ obtain S_D
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ↓ continue E or X

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          因此,对于 KIMI K3 来说,恢复位置 n 必须同时知道:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          1. MLA 在位置 n 以前的完整 KV;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          2. KDA 在位置 n 的 recurrent state;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          3. 卷积分支在位置 n 的 convolution state;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4. 所有状态确实来自同一条 token 前缀和同一套模型执行路径。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          单独命中 token 前缀,只能说明 "文本相同",不能证明 "递推状态已保存并且可恢复"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          常见疑问:为何 token 前缀命中并不意味着 KDA 缓存可以恢复?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          Radix Tree 或 prefix hash 可能只证明 token 0 … token N 相同,但恢复还需要:S_N 已保存、C_N 已保存或可重建、MLA KV_N 可用。若 state 只在 0、4096、8192 保存,而 token 匹配到 6000,系统不能凭文本直接得到 S_6000,只能退到 4096 并 replay 4096‑6000。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          0x04. KDA 给推理系统带来的新挑战

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4.1 缓存对象从一种变成多种

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          系统不再只管理 KV block,而要管理:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          状态

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          语义

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          是否可按 token 任意截断

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          典型管理方式

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          MLA KV

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          可寻址历史

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          基本可以

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          token/block cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA recurrent state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          前缀递推摘要

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          不可以随意截断

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          checkpoint/state block

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          KDA convolution state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          局部卷积上下文

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          需在合法边界保存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          small rolling state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          挑战不只是 "多了一种 cache",而是这些对象的语义、更新方式、可共享性都不同。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          一个可扩展的缓存条目至少应包含:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            CacheEntry {
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                model_version
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                prefix_range
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                tokenization_fingerprint
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                state_kind: mla_kv | kda_recurrent | kda_conv
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                physical_location
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                dtype / layout
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                writable
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                parent_checkpoint
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            }

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            其中最关键的是 prefix_range 和 state_kind。没有边界,就无法判断恢复是否连续;没有类型,就无法区分 "可寻址历史" 和 "顺序摘要"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            因此,核心是把缓存键从 "token prefix" 升级为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              (model/version, tokenizer, prefix boundary,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               MLA KV, KDA recurrent state, convolution state)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              实际系统还要处理:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 活动 state 与共享 checkpoint 分离;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • state 压缩和恢复;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • checkpoint 淘汰;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 本地与远端缓存协调;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 不同并行 rank 的对象对齐。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              4.2 状态恢复必须满足边界一致性

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              一个合法恢复点不是 "最长 token 前缀" 这么简单,而是一个所有相关状态都可用的共同边界。若 MLA KV 恢复到 4096 token,而 KDA state 只恢复到 3968 token,后续计算就不再等价于连续执行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              混合模型的输出是多个分支共同决定的。假设:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                MLA 恢复到 N=6000
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                KDA 恢复到 N=4096

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                那么两个分支看到的历史长度不同,后续混合结果自然不是连续执行在 N=6000 的结果。因此恢复对象必须像一张 "同一时间点的系统快照",而不是几个只按长度看起来相近的缓存片段。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                常见疑问:为何 KDA 状态不能像 KV 一样任意截断?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                截断 KV 意味着以后不再读取某些 token;剩余 KV 仍然是有效记录。截断 KDA state 则不同。state 的每个元素都可能是很多历史 token 混合后的结果。你不能从一个大 state 中随便删掉前 10% 的 "历史",因为它没有独立 token 地址。正确做法只有两种:使用已保存的更早 checkpoint,再 replay;或者使用已经在目标边界保存的完整 state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4.3 活动态不能直接共享

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                MLA KV 通常写入后不变,可以被多个请求引用。KDA state 会随着 decode 继续更新,如果多个请求直接指向同一份可写 state,一个请求的更新就会污染其他请求。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                因此必须把 "共享的稳定 checkpoint" 和 "请求自己的活动副本" 分开。共享 checkpoint 只读,活动 state 私有可写。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                4.4 PD/EPD 分离不再只搬 KV

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                传统 Prefill‑Decode 分离主要传输 KV blocks。KDA 需要传输或重建 recurrent state、convolution state,结合多模态后还要考虑 Encoder 产生的视觉 embedding。于是接口抽象从:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KV Cache transfer

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  扩展为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    model state transfer

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    通信层、调度层和缓存层都必须知道状态类型、版本、边界和生命周期。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    0x05. SGLang 的应对思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    SGLang 在 Radix Tree 的前缀匹配能力上增加 KDA‑aware checkpoint。Radix Tree 仍负责回答 "哪些 token 前缀匹配",但只有带有对应 KDA 状态的节点,才是可直接恢复的执行点。这相当于把缓存节点从 prefix -> KV blocks 扩展成:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      prefix boundary -> MLA KV + KDA recurrent state (+ convolution state)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      5.1 KDA‑aware Radix Tree

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      SGLang 原有 Radix Tree 擅长匹配请求之间的 token 前缀。KDA‑aware 之后,每个候选节点还要知道是否有可恢复 state:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Radix Tree
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        root
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        └─ system prompt
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            └─ tools
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ├─ user branch A
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                └─ user branch B

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        每个节点可能带:token prefix、MLA KV blocks、KDA checkpoint、checkpoint boundary。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        匹配流程变成:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        1. 找最长 token prefix

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        2. 沿匹配路径向前找最近合法 KDA checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        3. 取同一边界的 MLA KV + KDA state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        4. 把命中后的尾部重新计算

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        因此最长 token 命中点和最终恢复点可能不同。它把缓存正确性从字符串匹配提升为模型状态匹配。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        常见疑问:SGLang 的 KDA‑aware Checkpoint 是什么?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        普通 Radix Tree 节点回答 "前缀匹配到哪里";KDA‑aware 节点还回答 "这里有没有对应可恢复 state"。只有 token 匹配和状态匹配同时成立,节点才是有效恢复点。命中流程是:匹配 token 路径 → 回退到最近合法 checkpoint → 联合恢复 MLA/KDA → replay 剩余 token。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        5.2 Sparse Checkpoint:为什么不是简单等间隔

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        如果每个 token 都保存完整 KDA state,空间会快速膨胀。SGLang 因而采用稀疏 checkpoint:只在部分边界保存状态,而且不是简单地全局等间隔采样。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        策略包含三类位置:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Prefill:优先 chunk 边界;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Decode:按固定间隔生成 checkpoint;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Radix 分叉:多条请求共享 / 分叉的位置优先保留。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        原因是三类位置的复用概率不同:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Prefill chunk 边界本来就是执行边界,保存它不需要额外制造同步点;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • Decode 每个 token 都可能成为未来前缀,但每 token 保存太贵,所以抽样;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • 分叉点已经被多个请求证明有复用价值。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        之后还要限制单条路径的 checkpoint 数量,并用 LRU 回收长期未访问的状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        因此,它本质上是在缓存预算和重算成本之间做优化,而不是简单追求最大命中率。不平均地保存所有位置,而是利用执行结构和访问模式,把 checkpoint 当成有限预算下的 "缓存投资"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        常见疑问:SGLang 的稀疏 Checkpoint 如何解决空间 / 命中率矛盾?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        不保存每个 token 的 state,而是选择少量高价值边界保存。这样减少驻留开销,再用命中后的局部重算弥补较粗恢复粒度。Prefill chunk 边界天然适合保存;Decode 通过间隔控制数量;Radix 分叉点通常有更高复用概率;LRU 回收冷 checkpoint;路径预算防止单条长路径吞噬显存。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        5.3 Compressed Checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        并非所有 checkpoint 都同样有价值。SGLang 将状态分成:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        运行时活动池:当前请求正在更新,保持原始精度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        缓存池:Radix Tree 上等待复用,可将 temporal recurrent state 压缩为 INT8

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        局部窗口状态体积较小,通常保持原始精度。命中压缩 checkpoint 时:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          INT8 checkpoint
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ↓ dequantize
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          新的活动 state slot
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ↓ 以原始精度继续 decode

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          这不是让 KDA 永久在 INT8 上递推,而是只压缩 "停放在缓存里的快照",避免连续量化 / 反量化造成误差累积。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          SGLang 将正在执行的活动状态与 Radix Tree 中的缓存状态分离;不活跃 checkpoint 可放入独立缓存池,并把主要占空间的 KDA temporal state 压缩为 INT8,而较小的局部窗口状态保持原始精度。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          命中压缩 checkpoint 时,先解压到新的活动 state 槽位,再以原始精度继续 token 更新。这样量化误差主要发生在缓存驻留和恢复处,不会在连续 decode 中反复累积。它仍然是有损恢复,需要在质量和容量之间权衡。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          常见疑问:Compressed Checkpoint 做什么?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          它降低低热度 checkpoint 的存储成本,把有限显存留给高复用状态。主要的 temporal recurrent state 使用 INT8,较小的局部窗口状态保持原始精度。命中时先解压到活动槽,再恢复正常精度执行。这样节省驻留空间,但必须接受量化恢复误差,并为不同通道保存合适的量化参数。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          需要注意:INT8 checkpoint 是可选优化,不是所有 SGLang 部署都默认启用。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          5.4 COW、Snapshot 与 Donate

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          三者共同解决 "共享缓存必须稳定、执行状态必须可变" 的矛盾。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Radix Tree shared checkpoint
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ├─ request A: copy-on-write -> private active state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                └─ request B: copy-on-write -> private active state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Snapshot:把请求当前状态冻结,挂到 Radix Tree,成为未来可复用快照;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Copy‑on‑write:命中共享快照时先复制或建立私有副本,后续更新不污染共享快照;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Donate:快照完成后直接转移 state slot 的所有权,只改索引,不再复制整块数据。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            假设两个请求都命中 S_4096:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              共享 checkpoint S_4096
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ├─ A: private S_A
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  └─ B: private S_B

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Snapshot 负责制造稳定的共享版本;COW 负责首次写入时保护共享版本;Donate 负责把已经完成的可写 state 直接转交缓存树,避免复制。Donate 的价值在于把 "复制一大块 state" 变成 "转交一个内存槽位"。核心原则:共享版本只读,活动版本可写。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              常见疑问:COW、Snapshot、Donate 如何隔离状态?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Snapshot 固定共享的历史,活动副本负责继续递推;COW 在首次写入时复制;Donate 在旧请求结束后转交可复用的活动存储。这样共享 checkpoint 不被修改,执行又无需每步全量复制。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              5.5 Unified Memory

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Unified Memory 把 MLA KV block 和 KDA state block 放进同一个物理显存池,但保留各自的逻辑结构和分配单位。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                显存池
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                MLA KV blocks ----->                 <----- KDA state blocks
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   共享空闲区域/动态边界

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                MLA KV 和 KDA state 仍然有不同的逻辑类型、大小和生命周期;统一的是底层容量管理。这样可以避免预先把显存永久切成两个比例失衡的池。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                系统可以按实时负载动态调整两者占用,避免某一类缓存独占固定容量。统一的是物理容量管理,不是把两类状态混成同一种对象。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                好处是容量可以随负载倾斜;代价是底层分配器需要处理不同大小对象、空洞回填和碎片问题。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                常见疑问:Unified Memory 是什么?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                它不是把 MLA KV 和 KDA state 变成同一种数据,而是让它们从同一个物理显存预算中分配。KV manager 和 State manager 在逻辑上仍然是两个,但共享物理容量池。工作负载偏向 MLA 时可以多留 KV;偏向 KDA 时可以多留 state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                5.6 Mooncake 的职责边界

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                职责边界可以画成:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  SGLang
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ├─ 判断什么是合法恢复点
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ├─ 生成/恢复 KDA checkpoint
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      └─ 管理本地请求状态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Mooncake / HiCache
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ├─ 保存已确认合法的缓存对象
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ├─ 跨实例传输
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      └─ 管理更大范围的共享缓存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Mooncake 不需要重新理解 KDA 的递推数学;它只需要可靠地存储和搬运带有边界、类型和版本信息的对象。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  0x06. SGLang 源码导航

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  本章不是概念性总结,而是源码导航。所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  源码中的 KDA 支持不是一个单独的 KDACache 类,而是分散在四层:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    模型层:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        产生 KDA 的 q/k/v/g/beta


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Kernel/backend 层:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        prefill、decode、conv、recurrent update


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    状态池层:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        recurrent state、convolution state、checkpoint、活动副本


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    调度/缓存层:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        prefix hit、state index、checkpoint 边界、跨实例传输

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    最容易误解的一点是:SGLang 的 "checkpoint pool" 不是普通 KV pool。它保存的是可恢复的 KDA 执行状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    6.1 源码地图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    文件

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    关键函数 / 类

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    作用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    sglang/srt/models/kimi_k3.pyKimiK3DeltaAttention.forward_qkvbg

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    、forward_qkvbg_fused、forward

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    K3 模型侧生成 KDA 输入、接入 attention backend

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    sglang/srt/layers/radix_linear_attention.pyRadixLinearAttention.forward

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    、unified_linear_attention_with_output

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    将线性注意力结果接入 forward batch 与 cache location

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    sglang/srt/layers/attention/linear/kda_backend.pyKDAKernelDispatcher.decode

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    、extend、target_verify

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    按 decode/prefill/spec‑verify 选择 KDA kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    sglang/srt/mem_cache/mamba_checkpoint_pool.pyInt8CheckpointStore

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    、MambaCheckpointPool.store_from_active、load_to_active

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    缓存状态、INT8 压缩、恢复到活动池

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    sglang/srt/mem_cache/memory_pool.pyHybridReqToTokenPool.__init__

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    、donate_mamba_ping_pong_slot、clear

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    活动态分配、checkpoint pool 接入、Donate 与释放

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    sglang/srt/managers/schedule_batch.py_mamba_radix_cache_v2_req_prepare_for_extend

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    、mamba_lazy_prealloc_at_boundary

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    选择 checkpoint 边界、准备 ping‑pong state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    sglang/srt/mem_cache/unified_memory_pool.pyUnifiedKVPool

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    、MambaSubPoolSpec

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    MLA/MHA 与 Mamba state 共享物理 byte buffer

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    6.2 模型层:KimiK3DeltaAttention 不是只做矩阵乘

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    文件:sglang-main/python/sglang/srt/models/kimi_k3.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    关键位置:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • forward_qkvbg:第 1679 行起;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • forward_qkvbg_fused:第 1773 行起;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • forward:第 1821 行起。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    核心逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      hidden_states
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      投影出 mixed_qkv、gates、beta、f/a 等 KDA 输入
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      KDA/MLA attention
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      AttnRes、output gate、o_proj

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      文件顶部第 1‑7 行直接声明了 K3‑specific features,包括 Attention Residual、Latent MoE、MLA output gate 和 full‑rank KDA gate。这说明 Infra 不能只按 "一个普通 GDN 层" 处理 K3。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      6.3 统一入口:RadixLinearAttention.forward

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      文件:sglang-main/python/sglang/srt/layers/radix_linear_attention.py:38-121

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      函数:RadixLinearAttention.forward(...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      简化逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        如果是 extend/prefill 且启用了 piecewise CUDA graph:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            走 unified_linear_attention_with_output
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        否则:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            交给 get_attn_backend().forward(...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        源码第 86‑121 行展示了这个分支。第 142‑156 行的 unified_linear_attention_with_output 临时缩窄 forward_batch.out_cache_loc,调用 backend,再把输出写回。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        工程含义:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • KDA 结果必须写入请求对应的 cache location;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • cache location 属于 batch 元数据,不是 kernel 内部的临时变量;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • CUDA graph/piecewise 路径也必须保持同一状态写入语义。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        6.4 KDAKernelDispatcher:不同阶段用不同 kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        文件:sglang-main/python/sglang/srt/layers/attention/linear/kda_backend.py:39-202

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        类:KDAKernelDispatcher

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        关键函数:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • __init__:第 42‑202 行,选择 decode/prefill/verify backend;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • packed_decode:第 204‑235 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • decode:第 237‑264 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • target_verify:第 266‑307 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        • extend:第 309‑332 行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        简化调用图:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          decode:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Triton / Helion / CuTe DSL / FlashInfer
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          prefill:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Triton / FlashKDA / CuTe DSL / NVIDIA KDA / PTX
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          speculative verify:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Triton / FlashInfer / nv_cutedsl 路径

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          源码第 64‑190 行明确列出这些 backend 和 fallback 条件。第 237‑264 行的 decode 传入 ssm_states、cache_indices;第 309‑332 行的 extend 传入同样的状态索引。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          这证明:KDA state 是 kernel 的显式输入,而不是 "模型自己在 Python 对象里隐式保存" 的东西。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          6.5 SGLang 的 state 不是只有 recurrent state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          kda_backend.py 第 6‑18 行导入:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • causal_conv1d_fn

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • causal_conv1d_update

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • TritonKDAKernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • build_verify_intermediate_state_indices

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          所以一次 KDA 执行同时涉及:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            卷积窗口状态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            recurrent SSM/KDA 状态
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            speculative verify 中间状态索引

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            常见疑问:recurrent state 和 convolution state 是什么?SGLang 有对应吗?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Recurrent state 是 KDA 长期递推矩阵,携带压缩后的长历史;convolution state 是短卷积需要的最近窗口,携带局部连续性。两者可以采用不同存储策略:temporal state 可压缩,局部窗口通常保留原精度。SGLang 的 KDA‑aware checkpoint 主要围绕 recurrent state 展开,但合法恢复不能只恢复它;对应局部窗口状态也要恢复或按明确规则重建。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            6.6 Checkpoint Pool 的真实实现

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            6.6.1 设计分界:共享 checkpoint 只读,活动 state 私有可写

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            文件:sglang-main/python/sglang/srt/mem_cache/mamba_checkpoint_pool.py:15-45

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            模块说明明确区分:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              cached states:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  radix-owned
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  idle
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  compressed


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              active MambaPool:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  running requests
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  full precision
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  kernel-facing

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              这正是 Copy‑on‑write 的根本:共享 checkpoint 只读,活动 state 私有可写。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              6.6.2 Int8CheckpointStore

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              文件:sglang-main/python/sglang/srt/mem_cache/mamba_checkpoint_pool.py:60-184

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              关键函数:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • __init__:第 79‑113 行,分配 qdata 和 scale;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • quantize:第 117‑134 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • dequantize:第 136‑138 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • store:第 142‑149 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • load:第 151‑153 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • copy_to_pool:第 155‑164 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • store_from_pool:第 166‑174 行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              数据布局:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                qdata:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    [layers, slots, heads, d_v, d_k] int8
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                scale:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    [layers, slots, heads, 1, d_k]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                第 127 行沿 d_v 做 max‑abs,第 128‑133 行完成对称量化。第 164 行把 checkpoint 解量化后直接写入 active pool,这就是 cache hit 时的 COW 恢复。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                重要工程结论:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  checkpoint 命中:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      int8 → 一次 dequantize → active state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  继续 decode:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      active state 保持原始精度更新

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  不是每个 token 都在 INT8 state 上循环量化。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  6.6.3 MambaCheckpointPool

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  文件:sglang-main/python/sglang/srt/mem_cache/mamba_checkpoint_pool.py:186-280

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  关键函数:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • __init__:第 187‑225 行,创建 temporal int8 store、conv buffers、slot allocator;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • store_from_active:第 245‑251 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • load_to_active:第 253‑259 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • estimate_mem_usage_bytes:第 262 行起。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  store_from_active 的语义:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    active_mamba_pool.temporal → checkpoint temporal
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    active_mamba_pool.conv     → checkpoint conv

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    load_to_active 的语义:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      checkpoint temporal → active temporal
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      checkpoint conv     → active conv

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      SGLang 确实有 convolution state 的对应存储,不是只缓存 recurrent state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      6.6.4 可选初始化

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      文件:sglang-main/python/sglang/srt/mem_cache/mamba_checkpoint_pool.py:300-369

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      关键逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        如果没有 Mamba 配置:不创建
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        如果没有开启 enable_int8_mamba_checkpoint:不创建
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        否则:估算空间、检查可用显存、创建独立 checkpoint pool

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        这说明 INT8 checkpoint 是可选优化,不应写成所有 SGLang 部署都默认启用。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        6.7 活动状态、Donate 与边界

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        6.7.1 HybridReqToTokenPool.__init__

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        文件:sglang-main/python/sglang/srt/mem_cache/memory_pool.py:1271-1289

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        关键逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.mamba_allocator = MambaSlotAllocator(...)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.mamba_map = {...}
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          self.mamba_ckpt_pool = maybe_init_int8_mamba_checkpoint_pool(...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          活动 state 和 checkpoint state 使用不同池:活动请求走 mamba_allocator / active pool,Radix cached checkpoint 走 mamba_ckpt_pool。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          6.7.2 donate_mamba_ping_pong_slot

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          文件:sglang-main/python/sglang/srt/mem_cache/memory_pool.py:1488-1509

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          函数:donate_mamba_ping_pong_slot(req, new_slot)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          简化逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            找到要保留的 ping-pong slot
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            把旧 slot 作为可缓存 state 返回
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            把请求切换到 new_slot 继续执行

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            第 1491‑1495 行的 docstring 已明确写出 "donate tracked-state slot to radix cache"。这不是复制数据,而是把 ownership/slot 交给 radix cache 使用。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            6.7.3 clear

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            文件:sglang-main/python/sglang/srt/mem_cache/memory_pool.py:1565-1577

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            第 1569‑1574 行特别处理 mamba_ckpt_pool.clear()。原因是清空 Radix Tree 后,checkpoint slot 也必须释放,否则会出现 "树没了、slot 还被占用" 的泄漏。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            6.8 checkpoint 何时产生

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            6.8.1 _mamba_radix_cache_v2_req_prepare_for_extend

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            文件:sglang-main/python/sglang/srt/managers/schedule_batch.py:2672-2735

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            函数:_mamba_radix_cache_v2_req_prepare_for_extend(req)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            关键逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            1. 读取 mamba_cache_chunk_size();

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            2. 根据 mamba_checkpoint_grid(self.tree_cache.page_size) 得到 checkpoint 网格;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            3. 判断 extend_range.length >= checkpoint_grid;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            4. 计算要追踪的 seqlen;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            5. 把 state 放到 ping‑pong track buffer。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            第 2677‑2680 行说明 checkpoint 网格来自 tree page;第 2699‑2730 行计算对齐边界。它解释了为什么 KDA checkpoint 不是任意 token 都自然存在:调度器会主动选择合法追踪边界。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            6.8.2 mamba_lazy_prealloc_at_boundary

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            文件:sglang-main/python/sglang/srt/managers/schedule_batch.py:3002-3031

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            函数:mamba_lazy_prealloc_at_boundary(mamba_track_interval)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            第 3015‑3017 行检查请求是否落在 tracking interval;第 3026‑3031 行按需申请第二个 ping‑pong slot。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            这就是 lazy ping‑pong:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              平时:一个活动 slot
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              到 checkpoint 边界:临时申请第二个 slot,新状态写入另一侧,旧状态可安全 donate

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              6.9 Unified Memory 的源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              文件:sglang-main/python/sglang/srt/mem_cache/unified_memory_pool.py

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              关键位置:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • MambaSubPoolSpec:第 181‑210 行;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • UnifiedKVPool:第 217 行起;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • 构造函数:第 222‑280 行。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              MambaSubPoolSpec 第 185‑205 行明确描述:conv_state_shapes、temporal_state_shape、conv_dtype、temporal_dtype。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              UnifiedKVPool 第 217‑220 行说明两个 sub‑pool 共享一个 uint8 byte buffer;第 232‑243 行限制当前实现为一个向上增长、一个向下增长的两个池。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              简化布局:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                同一 byte buffer


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                MHA/MLA pool  --->  空闲区  <---  Mamba pool

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                注意:这是物理容量统一,不是逻辑对象统一。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                6.10 SGLang 恢复流程总览

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  请求 prefix 命中
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Radix 选择/准备 KDA tracking boundary
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  MambaCheckpointPool.load_to_active(...)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ├─ temporal int8 dequantize
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      └─ conv native-dtype copy
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  请求使用私有 active slot
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  到边界时 donate/snapshot
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  checkpoint pool + radix cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  关键证据文件:mamba_checkpoint_pool.py:245-259、memory_pool.py:1488-1509、schedule_batch.py:2672-2735。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  0x07. vLLM 的应对思路

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  vLLM 将不同状态纳入同一调度框架,但不强行用同一种存储方式:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    同一 Scheduler
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ├─ MLA/full-attention: Paged KV blocks
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        └─ KDA:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ├─ recurrent-state blocks/checkpoints
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            └─ convolution-state blocks/checkpoints

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    因此 "统一" 主要指请求调度和生命周期协调;底层仍承认 KV 与 KDA state 的语义差异。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    7.1 State block 是什么

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    State block 是物理内存管理单位,不等于一个 token,也不等于一个完整请求:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      State block B
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ┌─────────────────────────────┐
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      │ 一段连续执行产生的 KDA state   │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      │ recurrent state             │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      │ convolution state           │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      │ 边界/版本/布局等元数据         │
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      └─────────────────────────────┘

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      它服务于分配、回收、引用计数、换入换出和远端传输。一个大 block 中可以登记多个逻辑 Prefix Entry。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      在 vLLM 语境中:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • recurrent state:KDA 扫描到某个位置后得到的长期状态矩阵,携带长上下文摘要;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • convolution state:短卷积所需的最近若干 token 的局部缓存,携带局部连续性。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      前者决定长期记忆,后者决定下一步局部卷积输出。两者都影响后续 token,因此不能只恢复 MLA KV。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      常见疑问:vLLM 的 state block 是什么?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      它是 state 的物理容器,类似 KV block 的 "内存页" 角色,但里面装的是 KDA 状态快照,不是逐 token K/V。它通常附带 state tensor、覆盖/关联的前缀范围、快照边界、dtype/layout、引用计数、是否可写。一个 state block 可以有多个逻辑恢复点,因此物理块大小不必等于 Prefix Matching 粒度。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      7.2 逻辑前缀与物理 state 解耦

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      如果 Prefix Matching 的边界必须等于 State block 的边界,匹配粒度会被物理分块限制。vLLM 因此把两件事分开:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 逻辑层:记录任意已完成的 token 前缀;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 物理层:用较大的 state block 存储状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      二者通过偏移、边界元数据和 state 版本关联。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      假设物理 State block 按 4096 token 管理,但实际请求共享到 4480 token:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        物理存储:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            State block B: [0 ————————————————— 8192]
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        逻辑前缀:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Prefix Entry at 4096
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            Prefix Entry at 4480

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        如果强制 block‑aligned,只能命中 4096;如果逻辑匹配可以落在 block 内部,就能把 4480 作为更长的合法前缀。这里没有把 state 截断成 "半块",而是在大容器中保存或索引更细的有效边界。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        常见疑问:逻辑前缀匹配与物理状态位置解耦是什么意思?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        把 "地图上的地址" 和 "仓库里的箱子" 分开。逻辑层可以说 "命中 token 4480",而物理层可能把 0‑8192 token 放在同一个 state block B。只要 B 内登记了 state after 4480,逻辑层就能把 4480 当恢复点。否则,物理 block 的存在不能自动证明 4480 有可恢复 state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        7.3 Fine‑grained Partial Hit

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        假设一个 State block 能容纳 128 token 的状态,但请求前缀只命中到 96 token。朴素做法是:因为 128 token 的 block 尚未完整,96 token 不能恢复,只能从更早位置重算。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Fine‑grained Partial Hit 的做法是:仍然使用这个 128‑token 物理 block,但在其中记录多个更细的 Prefix Entry:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          State block B:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            entry at 32  -> state after token 32
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            entry at 64  -> state after token 64
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            entry at 96  -> state after token 96
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            entry at 128 -> state after token 128

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          于是,96 token 可以成为合法恢复点,即使它位于一个尚未填满的物理 State block 中。这里 "partial hit" 不是只恢复半个状态矩阵,而是恢复该 block 内预先记录的某个有效状态快照。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          完整过程:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            请求 P:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                已执行 0 … 4480
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                产生 state S_4480


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            物理上:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                S_4480 位于大 State block B 内


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            新请求:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                命中 token 0 … 4480
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                找到 Prefix Entry(4480)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                取出/恢复 S_4480
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                复制到新请求私有活动槽
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                继续生成

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            "Partial" 指逻辑命中位置可能只占物理 block 的一部分,不是允许系统从一个没有对应快照的中间位置硬推断 state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            它允许在一个大 State block 内登记多个细粒度 Prefix Entry。新请求命中 4480 时,不必退回到 block 起点 4096,也不必复制另一份完整物理 block。它直接定位对应 state,再复制成私有活动 state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            关键边界:partial hit 允许 "逻辑边界细于物理容器",但不允许 "从不存在的快照推断 state"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            常见疑问:Fine‑grained Partial Hit 如何工作?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            大 state block 内额外记录更细粒度、链式的 Prefix Entry。比如一个 block 覆盖 4096 token,而实际共享前缀到 4480 token;逻辑匹配可以落在 block 内部的 4480 边界,并关联该位置已经生成的 KDA state,而不必把 Prefix Matching 粗化为 4096 的物理边界。它不是把一个未完成的 state "截半",而是把多个逻辑恢复点放进较大的物理容器:物理上合并存储,逻辑上细粒度命中。恢复时仍需把对应 state 复制到请求私有空间,再继续递推。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            7.4 Interval‑based 与 Marconi‑style Retention

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            有限缓存预算下,不能保存所有位置的 checkpoint。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Interval‑based Retention:按固定或结构化间隔保留,例如每隔若干 token 保存;稳定、可预测、实现简单。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • Marconi‑style Selective Retention:根据运行时访问频率、前缀热度和复用价值选择保留位置;更灵活,但需要在线统计和淘汰策略。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            前者像规划化修路指标,后者像根据交通流量设置热门出口。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Interval-based:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              0 ———— K ———— 2K ———— 3K ————
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              固定、可预测、适合结构化前缀


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Marconi-style:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              第一次看到前缀:只记访问
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              第二次命中:才保存 state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              热点继续保留,冷点淘汰

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Interval‑based 还可以额外保留 Prompt 末尾状态,因为多轮对话常会完整复用上一轮 prompt。Marconi‑style 则避免一次性长 prompt 立刻占据大量 state 缓存。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              常见疑问:Interval‑based Retention 与 Marconi‑style Retention 有何区别?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Interval‑based 是预先规定路标:每 K token 一个 checkpoint,Prompt 末尾额外保留。它稳定、容易预测,适合多轮对话等边界清晰的场景。Marconi‑style 是先观察再投资:第一次出现只记录访问、不保存大 state;再次命中证明它是热点,才创建 checkpoint。它能避免一次性 prompt 浪费缓存,但需要在线统计和更复杂的淘汰逻辑。两者可以并用:结构化边界用 interval,动态热点用 selective retention。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              0x08. vLLM 源码导航

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              8.1 源码地图

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              文件

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              关键函数 / 类

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              作用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              vllm/models/kimi_k3/nvidia/kda.pyKimiK3DeltaAttention.forward

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              、_forward、_store_cache_checkpoints_kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              KDA conv/recurrent 执行、checkpoint 写入

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              vllm/models/kimi_k3/nvidia/kda_metadata.py_get_aligned_state_indices_kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              、KimiK3KDAMetadataBuilder.build

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              把 block table 转成 state index,构造 checkpoint metadata

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              vllm/v1/core/single_type_kv_cache_manager.pyMambaManager.find_longest_cache_hit

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Mamba/KDA 的 prefix lookup 与细粒度命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              vllm/v1/core/kv_cache_coordinator.pyKVCacheCoordinator.__init__

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              、_cache_hit_alignment_tokens

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              多 attention group 对齐、启用 partial hit

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              vllm/v1/core/kv_cache_utils.pyresolve_block_hashes

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               调用点

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              保留细粒度 hash 以支持 partial hit

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              8.2 KDA 执行和 state cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              8.2.1 KimiK3DeltaAttention.get_kv_cache_spec

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              文件:vllm-main/vllm/models/kimi_k3/nvidia/kda.py:593-599

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              函数:get_kv_cache_spec(vllm_config)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              关键逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                spec = super().get_kv_cache_spec(...)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                return replace(
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    spec,
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    num_prefill_checkpoint_blocks=
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        int(self.kda_prefill_backend == "flashkda"),
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                )

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                KDA 的 cache spec 不只是普通 attention KV spec,还包含 prefill checkpoint block 数量。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.2.2 forward 与 _forward

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                文件:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • vllm-main/vllm/models/kimi_k3/nvidia/kda.py:601-638

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                • vllm-main/vllm/models/kimi_k3/nvidia/kda.py:640-710

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                KimiK3DeltaAttention.forward 第 601‑638 行:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  投影 hidden_states
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  拆出 mixed_qkv、gates、beta
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  调用 _forward
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  o_proj

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KimiK3DeltaAttention._forward 第 640‑710 行:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  1. 从 forward context 取得 KDA metadata;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  2. 读取 state_indices、checkpoint;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  3. 从 self.kv_cache 取得 conv_state 和 recurrent_state;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  4. 纯 decode 条件满足时调用 fused KDA decode。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  第 681‑685 行直接解包:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    conv_state, recurrent_state, *recoverssm_records = self.kv_cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    第 694‑710 行把 conv_state、recurrent_state、state_indices 传入 fused kernel。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    vLLM 源码直接证明:KDA cache 至少有 convolution state 和 recurrent state 两个独立 tensor 语义。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    8.2.3 prefill 中的 convolution 与 recurrent state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    文件:vllm-main/vllm/models/kimi_k3/nvidia/kda.py:820-860

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    关键逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 第 831‑846 行定义 _prefill_conv;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 第 848‑850 行分别对 q/k/v 做 causal convolution;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    • 第 858‑860 行用 gather_initial_states 取得初始 recurrent state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    简化:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      prefill input
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ├─ q -> causal conv -> q
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ├─ k -> causal conv -> k
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ├─ v -> causal conv -> v
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          └─ gather initial recurrent state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      8.2.4 _store_cache_checkpoints_kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      文件:vllm-main/vllm/models/kimi_k3/nvidia/kda.py:236-297

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      函数:_store_cache_checkpoints_kernel(...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      关键逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 第 262‑266 行读取 state index 和 checkpoint offset;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 第 267‑285 行把对应卷积历史写入 conv_state;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 第 287‑295 行把 recurrent checkpoint 写入 recurrent_state。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      vLLM 的 checkpoint 写入不是抽象描述,而是 kernel 级别同时处理:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        conv checkpoint -> convolution state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        recurrent checkpoint -> recurrent state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        8.3 metadata 如何找到 state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        8.3.1 _get_aligned_state_indices_kernel

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        文件:vllm-main/vllm/models/kimi_k3/nvidia/kda_metadata.py:55-101

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        函数:_get_aligned_state_indices_kernel(...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        第 85 行根据 seq_lens 和 CACHE_BLOCK_SIZE 计算第一个 state slot;第 89‑100 行从 block table 读取 state indices。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        它做的是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          请求长度
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          对应 KDA state block 的起始位置
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          state index tensor

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          8.3.2 _mamba_get_block_table_tensor

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          文件:vllm-main/vllm/models/kimi_k3/nvidia/kda_metadata.py:104-140

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          函数:_mamba_get_block_table_tensor(...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          若 mamba_cache_mode 是 "all" 或 "none",第 110 行直接返回 block table;否则第 114‑140 行创建 state indices,并通过 Triton kernel 对齐到 KDA state slot。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          这就是 "逻辑前缀" 和 "物理 state block" 之间的适配层。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          8.3.3 KimiK3DAMetadataBuilder.build

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          文件:vllm-main/vllm/models/kimi_k3/nvidia/kda_metadata.py:560-717

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          关键逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          1. 第 570‑575 行:只有 prefill、启用 prefill checkpoint block、并且 cache mode 为 align 时,才准备 checkpoint metadata;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          2. 第 588‑600 行:按 sequence length、block size 计算 checkpoint split 和 checkpoint column;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          3. 第 602‑624 行:把 offsets 和 state indices 组织成 KDACheckpointMetadata;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          4. 第 716 行:把 checkpoint metadata 放进最终 KimiK3DAMetadata。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          这段源码说明一个重要边界:checkpoint 不是所有运行模式都自动生成;它受 prefill backend、cache mode 和对齐条件共同控制。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          8.4 Fine‑grained Partial Hit 的源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          8.4.1 MambaManager

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          文件:vllm-main/vllm/v1/core/single_type_kv_cache_manager.py:1268-1345

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          类:MambaManager

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          第 1268‑1295 行:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • supports_fine_grained_hash_lookup = True

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 保存 mamba_cache_mode

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          • 在 align 模式下维护 checkpoint block 和 partial‑tail 相关状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          8.4.2 find_longest_cache_hit

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          同文件第 1297 行起:MambaManager.find_longest_cache_hit(...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          第 1315‑1321 行调用 resolve_block_hashes,并传入:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            supports_fine_grained_hash_lookup=True
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            alignment_tokens=alignment_tokens

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            第 1327‑1345 行在 alignment_tokens < block_size 时,把一个大 block 拆成多个更小 hash unit 来寻找命中。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            这就是 "物理 block 大、逻辑 prefix 小" 的源码基础。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            8.4.3 Coordinator 如何启用 partial hit

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            文件:vllm-main/vllm/v1/core/kv_cache_coordinator.py:622-662

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            关键逻辑:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 第 622‑637 行检查是否存在 MambaSpec 且 mamba_cache_mode == "align";

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 第 638‑651 行检查其他 cache manager 是否兼容;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            • 第 655‑662 行让 _cache_hit_alignment_tokens 在 partial hit 时使用 hash_block_size,否则使用 scheduler_block_size。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            换句话说:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              普通命中中:只能落在 scheduler block
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              KDA partial hit:可以落在更细的 hash block

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              8.5 Retention 的源码证据

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              文件:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • vllm-main/vllm/v1/core/kv_cache_coordinator.py:32-62

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              • vllm-main/vllm/v1/core/kv_cache_coordinator.py:152-158

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              函数:_validate_prefix_cache_retention_interval(...)

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              第 40‑45 行说明 retention 只对 SlidingWindow 和 Mamba/linear‑attention group 生效;第 56‑60 行要求 interval 非负且是 scheduler block 的倍数。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              Coordinator 第 152‑158 行保存 retention_interval。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              由此可知:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                retention_interval = None:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  不做稀疏化/保持默认密度
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                retention_interval = 0:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  对适用 group 采用特殊的最小保留策略
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                正数:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  按 scheduler block 对齐的周期保留

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                源码能够确认 interval‑based retention;Marconi‑style selective retention 若要继续考据,应在具体分支中定位其独立策略实现,不能仅凭 coordinator 的 interval 参数称二者是同一个函数。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                8.6 vLLM 恢复流程总览

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  prefix hash lookup
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  MambaManager.find_longest_cache_hit(...)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  fine-grained alignment / state block lookup
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KimiK3DAMetadataBuilder.build(...)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  state_indices + checkpoint offsets
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  KimiK3DeltaAttention._forward(...)
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ├─ conv_state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      └─ recurrent_state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  kernel decode/prefill/update

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  关键证据文件:single_type_kv_cache_manager.py:1297-1345、kv_cache_coordinator.py:622-662、kda_metadata.py:570-624、kda.py:640-710。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  0x09. 深入讨论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  9.1 为什么 SWA 的 checkpoint 方法不能直接用于 KDA

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  SWA (Sliding Window Attention) 只需要最近窗口内的 token。窗口向前移动时,旧 token 自然离开;如果保存每隔 128 token 的窗口边界,恢复时最多重算一个窗口之间的短区间。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    窗口 [t-W, …, t]

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    窗口向前移动后,旧 token 被明确丢弃。保存一个窗口边界就足以说明附近的局部状态。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA 的 recurrent state 则是全历史压缩后的结果。位置 n 的 state 不是只由最近窗口决定,而是由从开头到 n 的所有转移和写入共同决定:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      S_n = M_n … M_1 S_0 + Σ_{i=1}^{n} M_n … M_{i+1} b_i

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      少一个 checkpoint,就不能从任意附近的 token 直接推导出完整 state;必须从更早 checkpoint 重新顺序执行所有中间更新。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      而且 KDA state 往往比 SWA 的窗口边界大得多。固定间隔越密,显存成本越高;间隔越稀,命中后重算越长。这就是 KDA 比 SWA 更难做 Prefix Cache 的根本原因。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      常见疑问:为什么 KDA 不能用 SWA 的固定间隔 checkpoint?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      SWA 的状态只代表一个有限窗口;KDA state 代表整个前缀的递推摘要。SWA 从最近窗口边界继续,最多补一小段窗口计算;KDA 从 checkpoint 到命中点之间的每个 token 都可能改变 state,必须按序 replay。再者,KDA state 本身体积大,固定高频保存的成本远超 SWA 的轻量边界信息。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      9.2 Checkpoint 密度的两难

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      设 checkpoint 间隔为 K:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 存储成本大致随 1/K 增加;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      • 命中后的平均重算长度大致随 K 增加。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      这不是精确性能公式,但能说明趋势:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        checkpoint 密集 -> state 占用高、恢复精细、重算少
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        checkpoint 稀疏 -> state 占用低、恢复粗糙、重算多

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        假设只每 10k token 保存一次:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          checkpoint: 0 ——————— 10k ——————— 20k
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          共享前缀:  0 ——————————————————— 15k

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          两个请求实际共享到 15k,但最近合法恢复点只有 10k。系统不能从 "命中的 15k token 文本" 直接恢复,只能:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            恢复 S_10k
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            replay 10k … 15k
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            再继续新请求

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            本来只需计算 5k 尾部,现在要重算 5k;若命中边界更不巧,浪费会更大。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            因此真正目标不是最大化 "token prefix hit rate",而是最大化:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              缓存收益 − state 驻留成本 − 恢复重算成本 − 管理复杂度

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              这不是单纯的命中率问题,而是 state 驻留成本 + replay 成本 + 请求等待时间 的联合优化。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              常见疑问:如何理解 checkpoint 密度的两难?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              密集 checkpoint 用显存换恢复速度,稀疏 checkpoint 用重算时间换显存。最佳策略取决于前缀复用概率、state 大小、请求长度和显存预算,不存在脱离负载的固定最优间隔。系统 prompt、多轮对话和 Agent 工具定义通常值得高优先级保存;一次性的随机长 prompt 则不一定值得保存。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              常见疑问:将 checkpoint 间隔拉大有什么问题?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              间隔变大后,前缀可能在 token 层面命中很多,但在 state 层面只能恢复到更早位置。于是命中收益被 replay 吞掉。例如共享 905k token,但最近 checkpoint 在 900k,仍需重算 5k;若只在 800k 保存,就需重算 105k。token 命中率看起来很高,实际 TTFT 未必改善。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              9.3 跨实例复用与 PD/EPD 分离

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              跨实例复用

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              传统系统只需寻找最长匹配 token prefix,再迁移 KV blocks。KDA 要求同时满足:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              1. MLA KV 在该边界可用;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              2. KDA recurrent state 在该边界可用;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              3. convolution state 在需要时可用或能被安全重建;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              4. 所有状态来自同一模型版本、同一 tokenization 和同一前缀。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                最长 token prefix
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                找到共同合法边界
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                联合迁移:
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    MLA KV
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA recurrent state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    KDA convolution state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                恢复到目标实例

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                不同来源的缓存不能简单拼接。一个来源的 MLA KV 加另一个来源的 KDA state,即使长度相同,也不保证计算一致。不能把实例 A 的 MLA KV 与实例 B 的 KDA state 按长度拼在一起,因为它们可能来自不同 tokenization、模型版本、并行布局或前缀边界。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                所以跨实例缓存查找从最长前缀搜索变成了 "最长可联合恢复前缀" 搜索。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                常见疑问:跨实例复用为何不能只寻找最长 token prefix?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                因为还要找到该前缀对应的 KDA state checkpoint,并确认它和 MLA KV 在同一位置、同一版本、同一布局下有效。不同实例的缓存不能按长度简单拼接。跨实例不仅要问 "文本相同到哪里",还要问:哪个边界有 KDA checkpoint?MLA KV 和 KDA state 是否同边界?远端对象是否来自同一模型 / 并行配置?恢复后的 state 能否安全转为本地活动副本?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                PD 分离

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                传统 PD 分离传输:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Prefill → KV blocks → Decode

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  Prefill 端产生的不是一组 KV block,而是一组带边界和版本信息的模型状态。Decode 端需要知道:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 状态类型;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 对应 token 范围;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • tensor layout 和 dtype;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • checkpoint 是否可写;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 后续是否需要 COW;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  • 状态是否适用于当前并行切分。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Prefill
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ├─ MLA latent history
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ├─ KDA recurrent state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ├─ KDA convolution state
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        └─ boundary/version/layout metadata
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    Decode

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    这要求通信协议从 "搬运缓存页" 升级为 "搬运可恢复模型状态"。若为每种模型单独写通信协议,基础设施会被模型结构大量污染;统一的模型状态协议能把 "对象类型" 和 "恢复元数据" 作为一等公民。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    常见疑问:PD 分离为何要从 KV Cache 传输演进为模型状态传输?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    因为 Decode 需要的输入不再只有 KV,而是 MLA KV + recurrent state + convolution state。每类状态可能有不同布局、精度、所有权和恢复规则。Prefill 到 Decode 的输入现在包含三者及元数据。把它们分别塞进 KV 协议会让通信层被模型细节绑死,因此更自然的抽象是统一传输 "可恢复模型状态"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    多模态 EPD

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    多模态推理还要把 Encoder 输出的视觉 embedding 纳入数据平面:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Encoder embeddings
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Prefill 生成 MLA/KDA states
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          ↓
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Decode 使用活动副本

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      视觉 embedding 可能在多个请求间复用,也可能只服务当前请求;它不是 KDA state,也不能简单当成 KV block。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      数据平面要支持:视觉 embedding、MLA token history、KDA recurrent snapshot、KDA convolution snapshot,并分别维护生命周期和所有权。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      统一数据平面需要同时处理不同生命周期、不同大小、不同可共享性的对象,而不是把所有内容都伪装成 KV。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      常见疑问:多模态 EPD 的额外挑战是什么?

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      除了 Prefill 生成的注意力状态,还要流动 Encoder 的视觉 embedding。它们大小、生命周期和复用方式不同,系统需要统一数据平面,同时保留类型和所有权信息。EPD 比 PD 多了 Encoder 输出,统一数据平面必须保留类型、所有权、版本和恢复边界,不能只依赖一个 token prefix hash。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      9.4 概念与源码对应表

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      概念

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      SGLang 源码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      vLLM 源码

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      recurrent state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      MambaCheckpointPool.temporalself.kv_cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       中的 recurrent_state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      convolution state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      MambaCheckpointPool.convself.kv_cache

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       中的 conv_state

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      活动副本

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      MambaPool

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      /allocator slot

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      request 对应 state slot

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      MambaCheckpointPool

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       slot

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      state block + metadata/checkpoint slot

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      COW

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      load_to_active

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      恢复到请求自己的 state slot

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Donate

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      donate_mamba_ping_pong_slot

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      state block/slot 生命周期管理

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      细粒度命中

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Radix/KDA tracking boundary

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      supports_fine_grained_hash_lookup

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      稀疏 checkpoint

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      schedule boundary + tracking interval

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      retention interval / state retention

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      物理统一内存

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      UnifiedMemoryPool

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      Hybrid cache manager / common block pool

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      kernel 状态索引

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      backend cache indices

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      state_indices

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       metadata

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      9.5 复现源码时的最小阅读顺序

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      如果要自己实现一个教育版 KDA Infra,建议按这个顺序阅读:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      1. SGLang mamba_checkpoint_pool.py:117-174:先理解量化、加载和写回;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      2. SGLang memory_pool.py:1271-1289,1488-1509:理解活动 slot 与 Donate;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      3. vLLM kda.py:640-710:理解 conv/recurrent state 如何进入 kernel;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      4. vLLM kda_metadata.py:570-624:理解 checkpoint offsets/state indices;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      5. vLLM single_type_kv_cache_manager.py:1297-1345:理解细粒度命中;

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      6. SGLang unified_memory_pool.py:181-280:理解物理容量共享。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      0x10. 最终结论

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      从源码看,KDA‑aware Infra 的最小正确抽象不是 prefix → KV blocks,而是:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        prefix boundary
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        → token/hash identity
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        → MLA KV blocks
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        → recurrent state slot
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        → convolution state slot
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        → writable/readonly ownership
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        → dtype/layout/version metadata

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        KDA 对 AI Infra 的核心影响可以概括为:

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        Prefix Cache 不再只是 "找到相同 token,然后搬 KV";它变成 "找到共同前缀边界,并恢复一组语义一致、生命周期不同的模型状态"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ”

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        SGLang 更强调在 Radix Tree 上增加 KDA‑aware checkpoint、稀疏 / 压缩保存和共享状态隔离,实现重点是 "Radix + Mamba checkpoint pool + ping‑pong/COW + UnifiedKVPool";

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        vLLM 更强调 state block、逻辑边界与物理存储解耦,以及细粒度 partial hit 和状态保留策略,实现重点是 "Hybrid cache manager + MambaManager fine‑grained hash alignment + KDA metadata/kernel pipeline"。

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        两者方向不同,但共同结论一致:面向 KDA 的推理系统必须从 KV‑centric cache 演变为 state‑centric cache。只有在同一个前缀边界上,完整的模型状态都可定位、可恢复、可安全写入,Prefix Cache 才真正成立。


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        TransFormer-封面
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        TransFormer-封面

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        0xFF 参考

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        阅读原文

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        跳转微信打开

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        •  
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        ❌