【轻量化复刻大模型 / 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 注意说明
- 项目github.com/RossiLH/Mod... 和系列博客是我的一个尝试,也是我学习的过程。不确定是否满足读者的需求,我自己会反思改进,也希望大家提出宝贵意见。
- 涉及 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 联合前向)
ini
主模型: 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(推断侧)
css
特征融合: 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. 子知识点拆解 / 架构
ini
Multi-Token Prediction
├── 3.1 MTPLayer 结构(mtp_layer.py:61, 95-135)
│ ├── h_norm / e_norm(各自 RMSNorm,:95-96)
│ ├── proj(无 bias,2d→d,:97)
│ ├── block(复用 Kimi3Block,:105;layer_kind 决定 KDA/MLA)
│ └── norm(输出归一化,:135)
├── 3.2 Kimi3ForCausalLM 集成(model.py:300, 349, 362-413)
│ ├── self.mtp = MTPLayer(...)(:300)
│ ├── forward 里 loss = lm + λ·mtp(:349)
│ └── _mtp_logits / _mtp_loss(:362 / :393,含 labels[:,2:] 对齐)
├── 3.3 MTPConfig(config.py:118-147 + 校验 :222-228)
├── 3.4 参数计数(计算见 doc,官方 config.py:609-612)
│ └── per_mtp = attn_each + moe_total + 2d + 2d²
├── 3.5 EAGLE-3 系列(eagle3.py)
│ ├── FeatureFusion [0 0 I](:73-100)
│ ├── DraftConfig(:138-143)
│ ├── Eagle3Draft(:146-191,draft 自回归 :174-191)
│ ├── eagle3_feature_stack(:104-134,摊平不选择------V3 修复)
│ ├── lk_loss / acceptance_rate(:58-70)
│ └── speedup_from_acceptance(:194-198)
└── 3.6 投机解码 verify 与端到端循环(speculative.py)
├── verify_tokens(:73-158) 纯函数接受判据
├── SpecDecodeStats(:163-216) 实测接受率 / tokens-per-forward
├── snapshot_caches / restore_caches(:221-261) 按类型快照/回滚
├── RecomputeBackend(:264) 无 cache 全序列重跑(oracle)
├── CacheRollbackBackend(:301) 增量打分
└── SpeculativeDecoder(:329-475) 端到端循环(decode_recompute/:372、decode_rollback/:413)
3.1 MTP 层结构(本项目 mtp/mtp_layer.py)
| 子模块 | 代码位置 |
|---|---|
| 融合归一化 h_norm + e_norm + 无 bias 投影 | mtp_layer.py:95-97, 128-131 |
骨架块(复用 Kimi3Block,KDA 或 MLA) |
mtp_layer.py:105-107 |
| 顶层 RMSNorm → MTP 隐藏态 | mtp_layer.py:135 |
| 缓存初始化(探 KDA/MLA 类型) | mtp_layer.py:137-139 |
3.2 主模型集成(model.py)
| 组件 | 代码 |
|---|---|
| 构造可选 MTP 头 | model.py:302(self.mtp = MTPLayer(config) if config.model.mtp.enabled else None) |
| forward 叠加 MTP 损失 | model.py:349-352(loss = loss + cfg.model.mtp.loss_weight * mtp_loss) |
MTP logits(x[t+2]) |
model.py:364-393(_mtp_logits) |
MTP 损失(labels[:,2:] 对齐) |
model.py:395-415(_mtp_loss) |
解码缓存(include_mtp) |
model.py:417-448 |
3.3 配置 MTPConfig(config.py:118-147)
| 字段 | 默认值 | 说明 |
|---|---|---|
| enabled | False(本项目) | kimi3-master 默认 True;本项目默认关闭保持兼容(可开启) |
| digit | 1 | K3 恰好 1 层(kimi3-master与 kimi-k 都硬约束) |
| layer_kind | "mla" | "mla" 或 "kda" |
| loss_weight | 0.3 | kimi-master 0.3;kimi-k-pytorch 默认 0.1 |
| normalize_inputs | True | h/e 各自 RMSNorm(对齐kimi3-master[0 0 I] 一致) |
校验(config.py:222-228):n_layers==1、layer_kind in (mla,kda)、loss_weight>=0。
3.4 参数计数
对齐 kimi3-masterconfig.py:609-612:
ini
attn_each = kda_each if layer_kind=="kda" else mla_each
per_mtp = attn_each + moe_total + 2*dim + 2*dim*dim
pc.mtp = per_mtp * n_layers
本项目 mtp_param_count = 2d² + 3d(mtp_layer.py:145-156),test_mtp.py 用精确公式校验。完整骨架块参数随 Kimi3Block 规模计入总参数。
3.5 EAGLE-3 组件(mtp/eagle3.py)
K3 把预训练得到的 MTP 层微调为 EAGLE-3 风格的 draft model:目标模型保持冻结,只更新 draft layer 及其特征融合投影。按照 EAGLE-3 的训练时测试协议,训练时将 draft 展开 7 步;除第一步外,最新位置的目标模型特征不可用,draft 会使用自己在前几步的输出,从而复现推理时的递归起草过程。
| 组件 | 说明 |
|---|---|
acceptance_rate(p,q) |
Σ_x min(p,q),加速 ∝ 该量 |
lk_loss(p,q) |
-log(Σ min),温度1、无 CE |
FeatureFusion |
无 bias W_E3,初值 [0 0 I] |
eagle3_feature_stack |
摊平状态为完整出口列表(V3 修复,不再替 fuse() 做选择) |
DraftConfig |
unroll_steps=7、feature_blocks=(0,3,-1) |
Eagle3Draft |
用传入 MTP 层 + lm_head;draft() 自回归 :174-191 |
speedup_from_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 代码
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 头(§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 是训练目标
ini
# Kimi3ForCausalLM.forward() 中的 MTP 集成
if self.mtp is not None and t > 2:
mtp_loss = self.mtp_loss(h, tokens, labels, doc_ids)
loss = lm_loss + 0.3 * mtp_loss # 联合损失
MTP 的作用不仅是 "多预测一个 token", 更重要的是:
- 梯度反传进骨干: MTP 的梯度流回主干 Transformer, 相当于一种正则化
- 让骨干学到更好的表示 : 预测
x[t+2]需要更深的上下文理解,迫使骨干编码更丰富的信息
4.1.2 推理阶段: EAGLE‑3 是加速手段
ini
# 投机解码循环
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)
scss
主模型预测 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 微调
perl
骨干冻结,只训练:
- 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):
yaml
mtp:
enabled: true
n_layers: 1 # 恰好 1 层, K3 强制校验
layer_kind: mla # 内部用 GatedMLA 注意力
loss_weight: 0.3 # MTP 损失权重
4.3.1 架构细节
MTPLayer:
scss
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 层 + 特征融合投影的组合:
ruby
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]
css
W_E3` 初始化 = `[0 0 I]
初始融合输出 ≡ 高层特征 (= MTP 预训练时的输入) → 从 "只信高层" 逐步学到 "吸收低 / 中层特征" → 初始化不引入瞬间扰动,平滑过渡。
python
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))
使用举例如下
ini
C = 64
f = Eagle3FeatureFusion(C, 3)
lo, mid, hi = (torch.randn(2, 3, C) for _ in range(3))
out = f([lo, mid, hi])
4.4.3 创新 2: LK 损失 (直接优化接受率)
传统做法: KL 散度当代理 → 不能保证最大化接受率 (容量受限时 KL 最优 ≠ 接受率最优)
K3 做法: L_LK = -log Σ_x min(p(x), q(x))
p= 目标模型分布,q= 草稿模型分布- 直接优化决定加速比的量:
acceptance_rate = Σ_x min(p(x), q(x))
训练时展开 7 步 (unroll_steps=7):除第一步外,草稿消费自己前一步输出 --- 正是推理期 drafting 过程的镜像。
4.5 EAGLE-3 如何复用 MTP
4.5.1 整体关系图

整体关系图
4.5.2 复用点 1:整个 MTPLayer 直接作为 Eagle3Draft 的"骨架块"
代码 :eagle3.py:154-180
python
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
ini
# MTPLayer 的内部结构
self.h_norm = RMSNorm(dim, eps) # 主干 hidden 归一化
self.e_norm = RMSNorm(dim, eps) # 未来 token embed 归一化
self.proj = nn.Linear(2*dim, dim, bias=False) # 拼接投影
self.block = Kimi3Block(config, layer_idx=cfg.n_layers, use_kda=...) # 骨架块
self.norm = RMSNorm(dim, eps) # 输出归一化
EAGLE-3 完全继承这 5 个组件及其预训练权重:
h_norm/e_norm:继续用于"主干 hidden 归一化"和"下一 token embed 归一化"proj:继续把2C拼接投影回Cblock(Kimi3Block):继续作为 attention + MoE 的骨架norm:继续作为输出归一化
0 个组件被替换------这就是"复用"的精确含义。
4.5.4 复用点 3:forward 接口签名完全一致
代码 :mtp_layer.py:110-135
php
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 中):
ini
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):
php
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):
python
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() 的循环里:
ini
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 推理数据流(投机解码)
fused(hidden):固定的上下文特征,整个 draft 循环中不变(只在循环外由 backbone + fusion 算一次)next_embeds:每步都变,是"上一步起草的 token 的嵌入"

推理数据流
4.5.8 关键复用量化
| 组件 | MTP 预训练 | EAGLE-3 微调 | 是否复用 |
|---|---|---|---|
MTPLayer.h_norm |
✓ | ✓ | 完全复用 |
MTPLayer.e_norm |
✓ | ✓ | 完全复用 |
MTPLayer.proj |
✓ | ✓ | 完全复用 |
MTPLayer.block (Kimi3Block) |
✓ | ✓ | 完全复用 |
MTPLayer.norm |
✓ | ✓ | 完全复用 |
lm_head |
✓ | ✓ | 完全复用(共享主模型) |
Eagle3FeatureFusion |
✗ | ✓ | 新增(唯一) |
| LK loss | ✗ | ✓ | 新增 |
复用率 :MTP 的 5/5 个组件全部复用,EAGLE-3 只新增 1 个 fusion 层。
4.5.9 一句话总结
EAGLE-3 不是"基于 MTP 的灵感重新设计",而是直接把预训练的 MTPLayer 当作草稿模型本体 ,只在前面加一个特征融合层把 AttnRes 的 3 层块表示融合成 MTP 层能消费的输入------预训练的 MTP 权重原封不动地被复用,训练时只微调 MTP 层 + 新加的 fusion,目标模型始终冻结。
4.6 MTP 与 EAGLE‑3 的差异究竟在哪里?
4.6.1 架构差异:极小 (只多一个线性层)
MTP 层内部:
scss
h_norm → e_norm → cat → proj(2d→d) → Kimi3Block → norm
EAGLE‑3 层内部:
scss
W_E3(3d→d) → 同一个 MTP 层 → lm_head
EAGLE‑3 直接复用 MTP 层的 self.layer, 不新建任何 Transformer 块。唯一新增的是 Eagle3FeatureFusion: 一个 (3*dim, dim) 无 bias 线性层,初值 [0 0 I]。初始化时这个层等于恒等映射,EAGLE‑3 退化为 MTP 本身。
具体如下:
| 维度 | MTPLayer(预训练期) | Eagle3Draft(推理 / 微调期) |
|---|---|---|
| 输入来源 | hidden[:, :-1] (骨干最终隐藏态) + emb(x[:, 1:]) (下一 token 嵌入) |
fused (特征融合后的低 / 中 / 高层混合特征) + next_embeds (上一步草稿 token 的嵌入) |
| 融合方式 | h_norm(h) + e_norm(e) → cat → proj(2d→d) |
Eagle3FeatureFusion: W_E3·[feat_low; feat_mid; feat_high], 初值 [0 0 I] |
| 骨架块 | Kimi3Block (MLA + MoE), layer_idx=n_layers 保证稀疏 MoE |
复用同一个 MTP 层 的 self.layer, 不新建 |
| 输出头 | 隐藏态 → 外部 lm_head (共享主干词表头) |
self.lm_head(h) (同样是共享主干词表头) |
| 训练目标 | cross_entropy(mtp_logits[:, :-1], labels[:, 2:]), 权重 loss_weight=0.3 |
lk_loss = -log Σ min(p, q) (直接最大化接受率) |
| 训练方式 | 骨干 + MTP 层联合训练(MTP 梯度反传进骨干) | 骨干冻结, 只训 draft 层 + 特征融合投影 |
| 推理行为 | 不直接用于推理 | draft() 自回归起草:第一步后草稿消费自己前一步的输出 |
| 特征深度 | 只用骨干最终层隐藏态 | 取 AttnRes 第 1/4 / 末个块的输出 (低 / 中 / 高层三层特征) |
| 初始化 | 标准 PyTorch 初始化 | W_E3 = [0 0 I]: 初始时融合输出 ≡ 高层特征 (= MTP 预训练输入), 平滑过渡 |
| 新增参数 | 无 (相对于主干) | Eagle3FeatureFusion: W_E3 为 (3*dim, dim) 无 bias 线性层 |
结论:架构几乎相同,差异 ≈ 1 个线性投影层。
4.6.2 训练模式差异:中等
| MTP | EAGLE‑3 | |
|---|---|---|
| 骨干 | 联合训练, 梯度反传进骨干 | 冻结, 不动骨干 |
| 损失函数 | cross_entropy (标准 CE) |
lk_loss = -log Σ min(p,q) (直接优化接受率) |
| 训练数据 | 正常预训练语料 | 目标模型的输出分布 (草稿展开多步自回归) |
| 训练目标 | 让骨干学到更好的表示 | 让草稿分布逼近目标分布 (但用 LK 而非 KL) |
结论: 训练方式完全不同,但这是 "同一套权重的两种用法", 不是两套独立架构。
4.6.3 思维差异:根本 (这是最核心的差异)
- MTP 的思维 : 我是训练工具。我的存在是为了让骨干 Transformer 学到更好的表示 --- 预测
x[t+2]迫使模型编码更深的上下文,梯度反传回骨干相当于正则化。我预测得准不准不重要,重要的是我的梯度让骨干变强了。 - EAGLE‑3 的思维 : 我是推理工具。骨干已经训练好了 (冻结), 我的任务是快速生成 "足够像目标模型" 的候选 token, 让目标模型批量验证而非逐个生成。我不需要完美,我需要接受率高--- 每多一个被接受的 token, 就省一次目标模型前向。
用一句话说:MTP 是 "用多预测一个 token 来让骨干学得更好"。EAGLE‑3 是 "用骨干的多层特征来让自己猜得足够准以加速推理"。同一个层,两种哲学。
4.6.4 差异量级总结
- 架构差异:极小 (1 个线性层,初始化时退化为 MTP)
- 训练差异:中等 (冻结 vs 联合,CE vs LK,但权重共享)
- 思维差异:根本 (训练增强 vs 推理加速,完全不同的目标函数)
所以差异究竟在哪里 --- 差异在思维。架构上它们几乎是同一个东西,这正是 K3 设计的精妙之处:一个 MTP 层,预训练时当正则化器用,推理时当草稿模型用,一鱼两吃。

TransFormer-封面
0xFF 参考
本文使用 markdown.com.cn 排版