深入探讨 vLLM 的推测解码训练支持，与 Speculators v0.3.0

主要亮点

推测解码是一种优化推理性能的方法；然而，为每个 LLM 训练一个独特的草稿模型可能很困难且耗时，同时用于为 vLLM 生成模型的生产级训练工具稀缺。
Speculators v0.3.0 提供对 Eagle3 草稿模型的端到端训练支持，可与 vLLM 无缝运行。
训练支持包括使用 vLLM 进行离线数据生成，以及针对 MoE 和非 MoE 验证器的单层和多层草稿模型的训练功能。

大规模推理

在过去十年中，LLM 在规模和能力上都迅速扩展，随之而来的是对推理性能日益增长的需求。由于 LLM 顺序生成令牌——每个令牌都需要通过数十亿个参数进行完整的正向传递——生成的成本迅速增长。随着模型尺寸的不断增加，这种顺序计算成为一个显著的瓶颈，使得今天的 LLM 功能强大却常常速度缓慢。

缓解这一挑战的一个有前景的优化方法是推测解码，它通过允许较小的草稿模型提出令牌，然后由较大的模型快速验证来加速生成。

本博客将探讨推测解码作为一种优化技术，介绍 Speculators 库，并深入研究它及其最近的 v0.3.0 版本。Speculators 为研究人员、工程师和机器学习从业者提供了端到端生成推测解码模型的工具，并与 vLLM 无缝集成。

什么是推测解码？

推测解码允许 LLM 在单个正向传递中生成多个令牌。它通过将一个小的“草稿”模型与完整大小的“验证器”模型（即您尝试服务的原始 LLM）结合使用来实现。草稿模型运行成本低且速度快（通常只有一个 Transformer 块），它承担了繁重的工作并自回归地预测多个令牌。验证器模型并行处理这些令牌。对于每个令牌，验证器确定它是否同意草稿的预测。如果验证器拒绝一个令牌，序列的其余部分将被丢弃，否则这些令牌将被包含在验证器模型的响应中。

这种方法的优点是

最终响应与单独使用验证器模型时来自相同的分布，这确保了使用推测解码不会降低模型性能。
验证器模型能够并行生成多个令牌。
由于草稿模型很小，运行它的开销通常很小。

总而言之，这可以将模型延迟降低 1.5-3 倍，从而显著加快生成速度。

在 vLLM 中使用推测解码模型

vLLM 和 Speculators 使运行推测解码模型像使用 vllm serve 服务任何其他模型一样简单。特别是，推测解码在低吞吐量场景中表现最佳，其中 GPU 未完全饱和，可以利用验证器模型的并行令牌生成。草稿模型与验证器模型紧密对齐也很重要，这就是为什么我们为每个验证器训练特定的草稿模型。然而，训练特定于 LLM 的草稿模型可能很困难且耗时。幸运的是，Speculators 库简化了这一训练过程，并使用户能够生成与 vLLM 无缝集成的草稿模型。

创建新的草稿模型

当前推测解码算法的 SOTA 是 Eagle3 (Zhang et al., 2025)。

Eagle3 草稿模型将验证器模型的三个层中的隐藏状态作为输入，捕获验证器的潜在特征。结合令牌 ID，这些隐藏状态通过较小的草稿模型，该模型自回归地生成草稿令牌。

这意味着训练 Eagle3 草稿模型需要一个包含以下组件的样本序列数据集

验证器模型隐藏状态（来自三个中间层）
令牌 ID
损失掩码（仅用于训练模型响应，忽略用户提示）
验证器模型输出概率（草稿模型的训练目标）

数据生成

直接从 vLLM 提取这些值并非易事。幸运的是，Speculators v0.3.0 通过隐藏状态生成器支持离线训练数据生成，该生成器从标准 LLM 文本数据集中生成隐藏状态张量。然后将这些隐藏状态张量保存到磁盘以供后续训练过程使用。

数据生成主要包括三个部分：预处理、隐藏状态生成和保存。

data_generation_overview

预处理接收原始数据集，

重新格式化并规范化对话轮次
应用模型的聊天模板
对对话进行分词
根据助手响应范围计算损失掩码
将其与令牌 ID 一起保存到磁盘
收集令牌频率统计信息，并将其保存到磁盘以供以后使用

损失掩码确保训练只关注机器生成的令牌。对于通常只在最后响应中插入思考令牌的推理模型，Speculators 提供了一个额外的标志来随机删除对话轮次，以确保模型在各种对话长度上进行训练。

隐藏状态生成器通过自定义工作器扩展利用 vLLM 插件系统。它修补模型的正向传递，以在预填充阶段拦截和捕获中间隐藏状态。生成器使用 vLLM 的多进程执行器进行高效的批处理推理，并支持张量并行性以用于更大的模型。此过程在下图中进行说明。

hidden_state_generator

在保存阶段，每个处理过的样本都作为单独的 .pt 文件保存到磁盘，包含

input_ids: 分词后的输入序列
hidden_states: 每个捕获层的张量列表
loss_mask: 指示可训练令牌的二进制掩码

生成器使用带有 ThreadPoolExecutor 的异步 I/O 来并行化磁盘写入，同时继续生成隐藏状态，从而最大化吞吐量。

除了数据文件，还有两个附加文件保存到磁盘

data_config.json，其中包含有关数据生成的元数据
token_freq.pt，其中包含有关令牌频率的信息

存储在 token_freq.pt 中的频率数据用于构建额外的目标到草稿 (t2d) 和草稿到目标 (d2t) 文件。这些文件充当验证器完整词汇表和草稿模型的较小词汇表之间的映射。这种简化的“草稿”词汇表通过仅包含最常出现的令牌来提高草稿模型的效率。

可以使用以下脚本启用离线数据生成

data_generation_offline.py：预处理数据，保存令牌频率分布，并生成隐藏状态
build_vocab_mapping.py：构建 t2d 和 d2t 张量

训练

Speculators v0.3.0 支持训练 Eagle3 草稿模型。训练以先前步骤中生成的样本和词汇映射文件以及模型配置信息作为输入，并初始化一个新的 Eagle3DraftModel 实例。然后使用 Eagle3 作者引入的“训练时测试”技术训练此模型。训练时测试在训练期间模拟多步草稿采样过程，以确保模型不仅学习预测第一个令牌，还学习预测后续令牌。

flex_attention

来自 Eagle3 (Zhang et al., 2025) 论文的图。

上图显示了训练时测试过程以及每个步骤的注意力掩码。对于每个前缀，草稿模型生成下一个令牌（蓝色）。然后，对于每个前缀加上第一个生成步骤，模型生成第二个令牌（黄色），依此类推。

训练时测试具有挑战性，因为注意力掩码是稀疏的，这使得典型的注意力实现难以以计算和内存高效的方式处理。这就是 Speculators 使用 FlexAttention (He et al., 2024) 进行注意力计算的原因。FlexAttention 将注意力掩码分成块，并且只在非空区域计算注意力。结合 torch.compile，这加快了计算速度，同时大幅减少了反向传递所需的激活 VRAM。

任何训练实现另一个重要特征是批处理。LLM 训练的批处理样本因序列长度通常不同而变得更加复杂。解决这个问题有两种方法，第一种是使用截断和填充的某种组合使序列长度相同。这对于长度统一的数据集效果很好，但对于需要大量填充的数据集可能会导致计算浪费。相反，Speculators v0.3.0 使用第二种方法，即将序列沿“序列”维度连接起来，然后配置注意力掩码以将它们视为单独的序列。这与 FlexAttention 实现很好地集成，并带来更好的性能，特别是当与智能批采样算法结合使用时，该算法有效地将样本打包到接近最大序列长度的批次中。

这些组件共同使得 Speculators Eagle3 模型训练快速且内存高效，所有这些都可以通过单个 train.py 脚本实现。

在 vLLM 中运行 Speculators 模型

训练完成后，库会生成一个完整的模型工件，其中包含一个扩展的 config.json 文件，其中包括 speculators_config。然后，可以使用简单的 vllm serve 命令在 vLLM 中无缝运行模型

vllm serve RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3

运行此命令时，vLLM 将读取存储在 speculators_config 中的推测解码设置（例如，验证器模型的名称）。此信息用于将草稿模型和验证器模型加载到同一服务器中并设置推测解码。speculators_config 提供了一种标准化的配置格式，实现了自包含模型，该模型知道它应该如何运行，同时使推测解码模型的部署像运行任何其他 LLM 一样简单。有关 speculators_config 的更多详细信息，请参阅下面的示例。

虽然简化的单命令部署非常适合入门，但当您需要更多控制时，vLLM 还提供了长格式语法。这对于以下情况很有用

使用与配置中不同的验证器模型
调整推测解码参数，例如推测令牌的数量

长格式命令服务基础（验证器）模型，并通过 --speculative-config 标志指定推测器。这种灵活性对于实验和优化至关重要。例如，您可能希望换用验证器的量化版本以进一步提高性能

vllm serve RedHatAI/Qwen3-8B-FP8-dynamic \
  --tensor-parallel-size 1 \
  --gpu-memory-utilization 0.9 \
  --speculative-config '{"model": "RedHatAI/Qwen3-8B-speculator.eagle3", "num_speculative_tokens": 5, "method": "eagle3"}'

在此示例中，我们使用 FP8 量化的 Qwen3-8B 作为验证器（而不是 speculators_config 中引用的默认 BF16 版本），并将推测令牌的数量从默认的 3 增加到 5，以获得更高的吞吐量。

vLLM 集成：生产就绪的推测解码

Speculators 和 vLLM 之间的紧密集成将推测解码从一种研究技术转变为一项生产就绪的功能。vLLM 对 Eagle3 的支持实现了在不同模型架构和配置之间的无缝部署

vLLM 服务和 Speculators 训练:

Llama (3.1, 3.2, 3.3): 8B 到 70B 参数
Qwen3: 8B, 14B, 32B 参数
Qwen3 MoE: 235B-A22B 参数 (专家混合)
GPT-OSS: 20B, 120B 参数

仅 vLLM 服务:

多模态：Llama 4 视觉语言模型

未来计划

Speculators 将专注于以下下一组功能

在线数据生成（在训练时生成隐藏状态，没有中间缓存到磁盘）
视觉语言模型的数据生成支持
重新生成验证器响应（用验证器生成的响应替换数据集“助手”响应，以获得更好对齐的训练数据）

参与进来！

对推测解码感兴趣？查看 Speculators 存储库并通过查看 Good First Issues 帮助发展该存储库！

有关其他资源、文档和 slack 频道，请查看

Speculators 文档: https://docs.vllm.com.cn/projects/speculators/en/latest/
vLLM slack 频道: #speculators, #feat-spec-decode
数据生成和训练脚本: https://github.com/vllm-project/speculators/blob/main/scripts/README.md
端到端示例: https://github.com/vllm-project/Speculators/tree/main/examples/data_generation_and_training
有关已训练的 Speculators 模型列表，请查看 Red Hat AI Hub

附录

Eagle3 算法

Eagle3 Algorithm

`speculators_config`:

{
  "architectures": ["Eagle3Speculator"],
  "auto_map": {"": "eagle3.Eagle3SpeculatorConfig"},
  "Speculators_model_type": "eagle3",
  "Speculators_version": "0.3.0",

  "draft_vocab_size": 10000,
  "transformer_layer_config": {
    "num_hidden_layers": 1,
    "hidden_size": 4096,
    ...
  },

  "Speculators_config": {
    "algorithm": "eagle3",
    "proposal_methods": [{
      "proposal_type": "greedy",
      "speculative_tokens": 3,
      ...
    }],
    "verifier": {
      "name_or_path": "meta-llama/Llama-3.1-8B-Instruct",
      "architectures": ["LlamaForCausalLM"]
    }
  }
}

此配置将推测器定义为一个完整的模型，包含

模型身份
- architectures: 推测器的模型类（例如，Eagle3Speculator）
- auto_map: 用于 Hugging Face 兼容性的自定义模型加载
- Speculators_model_type: 特定推测器实现
草稿模型架构
- transformer_layer_config: 草稿模型 Transformer 层的完整规范
- draft_vocab_size: 减少词汇量以实现高效的草稿生成（通常为 10k-32k 令牌）
- 模型特定配置选项
推测解码配置
- algorithm: 推测解码算法（EAGLE3）
- proposal_methods: 带有参数的令牌生成策略
  - speculative_tokens: 每步生成的草稿令牌数
  - verifier_accept_k: 验证期间考虑的前 k 个预测数
  - accept_tolerance: 接受草稿令牌的概率阈值
- verifier: 使用哪个验证器模型并针对其进行验证
  - name_or_path: HuggingFace 模型 ID 或本地路径
  - architectures: 兼容性检查所需的验证器架构