【轻量化复刻大模型 / KIMI K3】Multi-Token Prediction(MTP / EAGLE-3) 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 MTP DeepSeek‑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-master config.py:609-612 :
attn_each = kda_each if layer_kind=="kda" else mla_eachper_mtp = attn_each + moe_total + 2 *dim + 2 *dim*dimpc.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_acceptance E[tokens] = (1-r^(L+1))/(1-r)
3.6 投机解码 verify 组件( mtp/speculative.py ) 组件
说明
VerifyResult 一轮 verify 结果(接受 token/长度/bonus/每位置比值)
verify_tokens lossless 接受判据 (纯函数,不碰模型)
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", 更重要的是:
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: 推理期投机解码 目标模型前向 → 得到隐藏态 + AttnRes 特征
EAGLE‑3 draft 起草:特征融合 → 自回归生成 K 个候选 token
目标模型 verify: 逐位置接受 / 拒绝
接受前缀 + 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 关键设计 双输入融合 : 骨干隐藏态 h[t] + 下一 token 嵌入 emb(x[t+1]) , 各自 RMSNorm 后拼接投影
分开归一再拼接 : 若整体 RMSNorm, 两个来源的尺度会互相干扰;先各自归一化到单位 RMS, 拼接时两边贡献均衡
复用完整骨架块 : 内部是完整的 Kimi3Block (MLA 注意力 + StableLatentMoE) , 不是轻量 MLP
共享词表头 : MTP 输出再过主模型的 lm_head , 不单独建头
偏移语义 : 位置 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))
训练时展开 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 个组件及其预训练权重:
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 预训练 EAGLE-3 微调 (backbone 冻结,只训 MTP 层 + fusion):
EAGLE-3 微调 4.5.7 推理数据流(投机解码) 推理数据流 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(2 d→d) → Kimi3Block → normEAGLE‑3 层内部:
W_E3 (3 d→d) → 同一个 MTP 层 → lm_headEAGLE‑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 技术难点 不破坏主干 :不能为了多预测一步而改动 backbone 本身(否则推理成本上升)。
标签偏移对齐 :多预测一步意味着目标的"相位"要整体后移,极易对错。
额外的网络开销 :加一个头就需要额外一层的前向/反向,训练吞吐会下降。
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 ,2 d) ▼ proj (2 d→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 技术难点 输入侧双 shift : hidden[:, :-1] 与 emb(x[:, 1:]) 要严格错开一位,让"当前位置"恰好看到 x[t+1]。
输出侧再 shift :logits 与 labels 也要对齐( logits[:, :-1] ↔ labels[:, 2:] ),三维形状要逐一核对。
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 技术难点 选哪些层 :93 层骨干可选出口很多,选多了冗余、选少了缺信息。
融合初值 :草稿是从预训练 MTP 层微调来的,MTP 层只见过 high 这个输入分布。若 W_E3 随机初始化,EAGLE-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] ,初始化令:
因此初始前向:
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) 提供:
生成来源 :主干 Kimi3ForCausalLM 前向期间, AttentionResiduals 每完成一个块就把输出折叠进 AttnResState.blocks , sources() 摊平成 [embedding, block_1, ..., block_N] 。
选择 : Eagle3Draft.fuse() ( eagle3.py:175 ) 按 (0, 3, -1) 从该列表挑三块—— 第 1 块、第 4 块、最后一块 AttnRes 输出,分别对应低/中/高层语义。
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 对比基线与实测数据 5.3.11 反方辩手 / 边界条件 a) 反对:低/中层特征到底有没有用未知,可能就是噪音,白加参数。
b) 若失败:低中层特征与高层冗余或与预测不相关。
c) 胜出:draft 需要在"已见上下文"处更细粒度;失败:浅层特征与目标无关。
d) 更稳健:学到的 W_E3 若趋于 [0 0 I] ,则模型自己选择只用高层=自动关闭低层。
5.4 子知识点:LK 损失(EAGLE-3 训练目标) 5.4.1 要解决的问题 投机解码的加速比 ∝ 逐 token 接受率 Σ_x min(p,q) 。草稿模型的训练目标应该 直接最大化这个接受率 ,而不是用一个"看起来相关但实际脱节"的代理。
5.4.2 技术难点 代理失效 :常规的 KL 最小化对容量受限的草稿模型, 不保证 最大化接受率——它可能让草稿越来越"保守"而不是越来越像 p 的峰值。
梯度稀疏 : log Σ min 这类目标在高置信处梯度可能很稀,收敛慢。
5.4.3 解决方案总体思路 直接优化 L_LK = -log Σ_x min(p(x), q(x)) ,温度 1、无 CE 辅助项。它正是接受率的负对数——优化目标与推理加速的度量 直接对齐 ,而非代理。
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全部高概率区域,最优解就是 切掉所有拿不准的候选 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 训练受限容量草稿模型:
草稿容量不足,没办法同时建模 p 所有峰值;
最小正向 KL 的最优策略: 放弃一部分 p 的峰值,直接把这些 token 概率归零 ;
草稿只保留一小部分最稳妥 token,分布变得保守;
虽然 q 在自己保留的 token 上和 p 很接近,但 漏掉了大量 p 的峰值候选 ;
采样出来的草稿序列,命中 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、随分布疏离单调上升。
5.5 子知识点:EAGLE-3 draft 推理(草稿自回归) 5.5.1 要解决的问题 目标模型 93 层每 token 一前向太贵。投机解码想用"每步只花一层"的草稿模型先快速猜 L 个 token,再用一次目标前向核对——省下昂贵的目标前向次数。草稿自回归就是"连续猜 L 个"的实现。
5.5.2 技术难点 草稿没有目标特征 :从第 2 步起,草稿不再有"目标侧特征"可用(最新位置的目标特征要等目标前向才有),只能吃自己上一步的输出——这是递归起草。
融合输入只来自一步 : draft() 每步把 state 缩到最后一位 state[:, -1:] ,模拟推理时"只有当前位置可用"。
与 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 复杂。
失败条件:草稿未训练好、接受率低,加速比趋近 1。
完成度:已实现并运行通过(draft 全链路测试)。
5.6 子知识点:投机解码 verify 与端到端循环 5.6.1 要解决的问题 草稿 draft() 只是"猜了一串 token", 没有任何机制判断这些 token 是否值得接受 。没有 verify,投机解码就是空谈——你无法知道该照单全收、部分收、还是全拒。真实加速比也因此无法实测。
5.6.2 技术难点 接受/拒绝判据 :如何在"保留草稿"与"纠正错误"之间无损地权衡(必须保证最终分布 = 目标分布,即 lossless)。
目标并行打分 :目标模型要能 一次前向 对 L+1 个草稿位置打分,而不是 L+1 次前向。
KDA 状态回滚 :KDA 的递推状态 S 被拒绝后无法像 KV cache 那样随意截断——这是 serve/decode.py 那套投影重演机制存在的原因,但两者此前没接起来。
残差重采样 :拒绝时要从残差分布重采 1 个 token,保证无损。
5.6.3 greedy vs lossless 投机采样分为两大阶段:
小模型(draft model)生成一串候选 draft token;
大目标模型(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。
输出一致性 速度与吞吐量 greedy verify :实现简单,每一步只拿 argmax,很多框架实现不用取出完整概率分布;截断发生更早,平均接受 token 数量更少。
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 解码,投机 verify 用 greedy 模式依然会带来输出不一致。
” lossless verify
通俗一句话总结 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),下挂两条打分后端:
5.6.5 思路背后的原理 直觉 :主模型逐本核对顾问的猜测——猜对收下,猜错自己读一本并退回上一本对的地方。
准专业(lossless 判据) :草稿在位置 i 提出 c_i(分布 q_i),目标分布 p_i。采 u~U(0,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_rollback —— 快照-回滚路径(增量打分) 每轮前向次数 :目标 1 次全序列( :443 取 hidden)+ L 次增量打分( :453 )+ na+1 次重放( :467 , :469 )+ 草稿 L 次小步。
decode_rollback 两条路径并排对照 两条路径并排对照 关键差异表 维度
decode_recompute decode_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 并没有完全摆脱全序列重跑。 :443 hidden = 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 增量打分机制解析 增量打分如何实现
关键路径在 speculative.py:448-455 :
step_caches_snap = snapshot_caches(caches) # ① 打分前快照 for j in range ( 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 注释):
EAGLE-3 特征融合需要全序列 hidden draft() 的输入是 fuse(features) ,其中 features 是低/中/高三层 AttnRes 出口堆叠。这些特征 不能 从增量 cache 直接读出——KDA 的 state 是压缩递推态,不含逐位置 hidden;MLA 的 kv_latent 是压缩 K/V,也不是 hidden。要拿到 (B, T, d) 的 hidden,必须跑一次完整 forward。
与 RecomputeBackend 严格对齐 注释明说:"与 Recompute 路径完全一致(保证两种后端特征相同)"。本文件的 首要目的 是用逐 token 一致来证明 rollback 正确性,不是追求性能。所以故意让两条路径的 draft 输入完全同源。
职责拆分 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:262 fusion.py:44-47 mtp_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-89 model.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-133 head.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.py MTPConfig + Kimi3Config (含 MTP 配置与校验 n_layers==1 )
src/models/llm/kimi_k3/model.py Kimi3ForCausalLM (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 可视化脚本 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_e1_joint_loss.png :干 LM vs 联合目标 lm_loss 曲线;教学尺度下联合未显著占优。
plot_e1_joint_loss plot_e2_init_curve.png :三条初值误差曲线( [0 0 I] 恒 0、随机/全零收敛)。
plot_e2_init_curve plot_e3_speedup.png :4 条理论加速比曲线 + 星标(r=0.8,L=7→4.16)。
plot_e3_speedup plot_e5_measured_speedup.png (V3 新增):理论曲线 + 红色实测星标 (lossless 实际接受率/加速点),展示"理论上限 vs 实际"。
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-封面 0xFF 参考