【轻量化复刻大模型 / KIMI K3】Multi-Token Prediction(MTP / EAGLE-3)
0x00 概要
本文是 MTP 第二篇。
注:
- 这个项目和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。
- 涉及 KIMI K3,DeepSeek V4,PI0.5,PI0.7 等模型。
- 会解释每个组件在解决一个什么真问题、这个问题难在哪、为什么只能这么解、解法的原理是什么,以及组件之间如何咬合成一个整体。
- KIMI K3 的参考代码为:github.com/TimRots/kim... 为主要参考。另外三个项目被用来核对和补充。
- 所有文件行号基于本地源码快照;源码后续变化时,行号可能移动,但函数名和调用关系仍可作为定位入口。
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。
为什么"预测 xt+2"而非 "xt+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 架构与类依赖关系
ini
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 数据流(张量形状逐步)
scss
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 执行流(时序/调用链)
scss
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 代码
python
# -*- 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 子知识点:偏移对齐(ht + emb(xt+1) → logitst=xt+2)
5.2.1 要解决的问题
MTP 的输入是"当前隐藏态 + 未来 token 嵌入",输出要预测"更未来的 token"。如果偏移对错,模型会去学错误的目标(比如重复主模型的 xt+1),整个 MTP 头形同虚设。
5.2.2 技术难点
- 输入侧双 shift :
hidden[:, :-1]与emb(x[:, 1:])要严格错开一位,让"当前位置"恰好看到 xt+1。 - 输出侧再 shift :logits 与 labels 也要对齐(
logits[:, :-1] ↔ labels[:, 2:]),三维形状要逐一核对。 - Teacher-forcing 泄漏:直接给模型真实 xt+1,可能让模型学会"复制"而非"预测"。
5.2.3 解决方案总体思路
利用 teacher-forcing 的"已知 xt+1"作为前提:MTP 前向输入 hidden[:, :-1](丢弃最后位置)+ next_emb = emb(x[:,1:])。两层 shift 后,输出第 t 个位置对应"输入第 t 个 backbone 隐藏态 + 第 t+1 个 token 嵌入",因此它已经知道 xt+1 ,预测目标 xt+2。对齐:logits[:, :-1] ↔ labels[:, 2:]。
5.2.4 思路背后的原理
- 直觉:告诉助手"我读到了上一本(xt)和下一本(xt+1)是什么",让他猜下下本(xt+2)。
- 准专业 :维度------MTP logits
(B,T-1,V),labels2(B,T-2),前者截掉末尾一位对齐。若错误用x[t]的嵌入(无 shift),退化成"预测 xt+1",与主模型重复。 - 专家:这本质是"多步展开 vs teacher-forced 一步"的权衡。多步展开会累积误差且无法并行;teacher-forced 借用真实 token 作为条件,使每个位置的监督互不干扰,是训练期的高效形态(计算形态通识)。
5.2.5 架构与类依赖
无独立类;逻辑在 Kimi3ForCausalLM._mtp_logits(model.py)内完成 shift 与拼接。
5.2.6 数据流
scss
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 执行流
ini
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 代码
python
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(对 xt+1 极敏感),确认对齐语义无误;输出形状 (B=2, T-1=7, V=64)(实测)。
5.2.11 反方辩手 / 边界条件
- a) 最强反对:teacher-forcing 泄漏------xt+1 的正确性直接炒作结果,无需真的"下一步"全模型。
- b) 失败点:模型可能只学"复制 xt+1 到 xt+2"而非语义预测。
- c) 胜出:若 xt+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 架构与类依赖
ini
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 数据流
scss
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 执行流
ini
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 代码
python
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 = 0W_mid = 0W_high = I(单位阵)→eagle3.py:91
因此初始前向:
scss
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 中增加模型每层生成的中间状态。
ini
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)
ini
# ============ 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)
scss
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)
ini
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 技术难点
- 代理失效 :常规的 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在这里概率很低 → 损失暴涨,模型会把这个位置的概率压到接近 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 训练受限容量草稿模型:
- 草稿容量不足,没办法同时建模 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 数据流
scss
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 执行流
scss
训练: 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 代码
python
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 技术难点
- 草稿没有目标特征:从第 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 架构与类依赖
scss
Eagle3Draft (eagle3.py:146)
├─ fusion Eagle3FeatureFusion
├─ layer MTPLayer(复用)
├─ lm_head 目标共享词表头
└─ draft() (eagle3.py:174-191) # 自回归
依赖:被 SpeculativeDecoder._run_round 调用(speculative.py:363)
5.5.6 数据流
css
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 执行流
ini
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 代码
python
# -*- 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 技术难点
- 接受/拒绝判据:如何在"保留草稿"与"纠正错误"之间无损地权衡(必须保证最终分布 = 目标分布,即 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
ini
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 模型解码,不会改变模型输出行为,是论文标准。
速度与吞吐量
- 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 解码场景,追求简单、低开销;
注意:即便你外层开启 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 架构与类依赖关系
scss
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 数据流(张量形状逐步)
erlang
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 增量打分机制解析
- 增量 只发生在草稿窗内的
draft_len次小步前向(这是真正省算力的地方)。 - 重跑 只为取 EAGLE-3 多层特征,是为了让
decode_rollback与decode_recompute严格对齐、便于数值校验而保留的设计,不是技术做不到。
增量打分如何实现
关键路径在 speculative.py:448-455:
ini
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 每轮仍在做:
ini
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 快照来避免重跑,但那是性能优化层,不属于本文件的"回滚正确性证明"目标。
函数细节
ini
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 代码
验证结果
less
@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 快照 / 恢复
python
# ---------------------------------------------------------------------------
# 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
端到端投机解码循环
ini
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 |
| 理论 Etokens/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)
ini
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(自研扩展) |
口径一致性结论:三方预测 xt+2 语义一致;loss_weight 默认 0.3 vs 0.1 差异已在配置层显式化。verify 环节kimi3-master缺失,本项目补齐。
"
附录B. 实测数据 (来自项目实验)
B1: 联合损失 vs 纯 LM
css
纯 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] 初始化的优势
csharp
[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
ini
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 可视化脚本
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(ht→xt+1)与 MTP(ht⊕emb(xt+1)→xt+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 参考
本文使用 markdown.com.cn 排版
本文使用 markdown.com.cn 排版