vLLM Speculators：用标准化格式训练并部署投机解码 Draft 模型

本篇介绍 vLLM 生态中 Speculators 项目的定位与能力：如何通过 vLLM 离线生成训练数据、训练单层/多层 draft 模型、以 Hugging Face 兼容的 speculators 格式分发模型，并直接 vllm serve 到 vLLM 中自动启用投机解码。读完后，你将理解 speculators 模型配置的完整字段结构，以及 vLLM 在加载时如何自动解析该格式并推断出 speculative_config。

为什么需要 Speculators：投机解码的原理与收益

大语言模型逐 token 生成文本，存在根本性瓶颈：每个 token 都需要一次完整的模型前向传播，而在等待访存瓶颈型操作返回时，GPU 算力利用率很低。投机解码（Speculative Decoding）的思路是用一个更小、更快的 "draft" 模型——很多时候只是单个 transformer 层——提前预测多个 token，再由主模型并行验证这批 token，从而把逐 token 的访存型解码转化为并行验证的计算型操作。

投机解码带来的核心收益包括：

• 降低时延：面向聊天机器人、代码助手等交互型应用，token 生成速度可提升 2～3 倍，响应时间直接影响用户体验；
• 更高的 GPU 利用率：把大模型 latency / memory-bound 的解码过程转化为 compute-bound 的并行 token 验证，改善硬件利用；
• 无损质量：投机解码并不近似替代目标模型——被接受的 token 与目标模型在同一采样配置下必然生成的 token 完全一致；被拒绝的 draft token 会被丢弃并由目标模型重新生成；
• 成本效率：减少每个请求占用硬件的时间，从而在同一 GPU 上服务更多请求。

对于用户实时等待响应的延迟敏感场景（对话式 AI、交互式编程助手、流式文本生成），Speculators 提供了从训练到部署的完整工具链。

Speculators 的四大核心能力

Speculators（vllm-project 开源库）用于加速 LLM 推理的投机解码，提供与 vLLM 无缝衔接的 draft 模型高效训练能力。其四大关键特性为：

1. 使用 vLLM 离线生成训练数据：通过 vLLM 生成目标模型的 hidden states（中间层激活），数据样本落盘后可用于 draft 模型训练；
2. Draft 模型训练支持：端到端支持单层与多层 draft 模型的训练，同时覆盖非 MoE 与 MoE 模型；
3. 标准化、可扩展的格式：提供 Hugging Face 兼容的投机模型定义格式，并附带工具把外部研究仓库的模型转换为标准 speculators 格式；
4. 与 vLLM 无缝集成：专为直接部署进 vLLM 而设计，以最小开销实现低时延、生产级推理。

训练数据生成：vLLM 的 extract_hidden_states 方法

"用 vLLM 离线生成训练数据" 这一能力对应 vLLM 内置的 extract_hidden_states 投机方法：在目标模型推理时抽取指定层的激活并保存为 .safetensors 文件。完整的离线示例位于 examples/features/speculative_decoding/extract_hidden_states_offline.py，核心用法如下：

from vllm import LLM, SamplingParams
from vllm.config.kv_transfer import KVTransferConfig

llm = LLM(
    model="Qwen/Qwen3-8B",  # 目标模型
    speculative_config={
        "method": "extract_hidden_states",
        "num_speculative_tokens": 1,
        "draft_model_config": {
            "hf_config": {
                "eagle_aux_hidden_state_layer_ids": [1, 2, 3, 4],  # 目标模型层索引
            },
        },
    },
    kv_transfer_config=KVTransferConfig(
        kv_connector="ExampleHiddenStatesConnector",
        kv_role="kv_producer",
        kv_connector_extra_config={
            "shared_storage_path": tmpdirname,
            "allow_custom_save_path": True,
        },
    ),
)

每个请求产出一个 .safetensors 文件，包含 hidden_states（形状 [num_tokens, num_extracted_layers, hidden_size]）与 token_ids（形状 [num_tokens]）。这些落盘的 hidden states 正是训练 EAGLE 类 draft 模型的训练数据。该方法的完整参数说明（含在线服务端模式、每请求选项与默认值）见 docs/features/speculative_decoding/extract_hidden_states.md。注意两点前提限制：chunked prefill 与该特性不兼容，必须关闭；在线部署时官方建议使用 /dev/shm/ 等 RAM 文件系统以改善落盘性能。

speculators 模型格式：vLLM 如何解析它

speculators 格式的 draft 模型是一个标准 Hugging Face 模型仓库，其 config.json 中包含 speculators_config 字段。vLLM 端的解析逻辑集中在 vllm/transformers_utils/configs/speculators/base.py 中的 SpeculatorsConfig 类（model_type = "speculators"）。

配置的必需字段

从 SpeculatorsConfig.validate_speculators_config 的校验逻辑可以确认一个合法的 speculators 配置必须满足：

• speculators_config.proposal_methods[0].speculative_tokens：提案方法及其投机 token 数（当前 vLLM 只消费第一个提案方法）；
• speculators_config.verifier.name_or_path：验证器（目标）模型标识符；
• speculators_model_type：speculators 算法类型，必须属于受支持集合；
• transformer_layer_config：draft 模型自身的 transformer 层配置字典。

支持的算法类型

受支持的 speculators 类型注册在 vllm/transformers_utils/configs/speculators/algos.py 的 SUPPORTED_SPECULATORS_TYPES 中，通过 register_speculator 装饰器注册。当前仓库确认支持以下类型及其到 vLLM 运行时 method 的映射（见 SpeculatorsConfig.build_vllm_speculative_config）：

speculators_model_type	映射的 vLLM method	说明
eagle3	eagle3	支持 draft_vocab_size、target_hidden_size、norm_before_residual、eagle_aux_hidden_state_layer_ids 等字段；目标架构映射到 Eagle3LlamaForCausalLM / Eagle3Qwen3ForCausalLM
peagle	eagle3（附加 parallel_drafting: True）	并行 EAGLE；mask_token_id 必填，映射为 proposer 的 pard_token
dflash	dflash	并行 draft（block 式），mask_token_id 与 aux_hidden_state_layer_ids 必填；目标层索引按 i - 1 语义映射
dflash2	dflash	在 DFlash 上增加分组卷积与低秩 candidate selector 头，复用 DFlash 运行时
dspark	dspark	在 DFlash 基础上增加 Markov logit-bias 头，可选置信度头（enable_confidence_head）

每种类型都定义了自身特有的配置字段转换逻辑（例如 EAGLE-3 的辅助隐状态层、DFlash 的 dflash_config 子配置），从源码结构看，这使同一个 speculators 格式能够承载从单层自回归 EAGLE 头到块式并行 draft 的多种架构。

vLLM 加载时的自动推断流程

当你直接以 speculators 模型作为 model 启动服务时——vllm serve <speculator-model>，无需显式传 --speculative-config——vLLM 的自动检测链路位于 vllm/transformers_utils/config.py 的 maybe_override_with_speculators：

1. 通过 PretrainedConfig.get_config_dict 读取模型 config.json，检查是否存在 speculators_config 字段；不存在则原样返回，按普通模型加载；
2. 调用 SpeculatorsConfig.extract_vllm_speculative_config 校验并构建 vLLM 风格的 speculative 配置（method + num_speculative_tokens）；
3. 若用户显式提供了 vllm_speculative_config，允许覆盖（如 attention_backend 等），但随后 method 与 model 两个字段会被 speculators 格式锁定的值重新固定；
4. 用 speculators_config["verifier"]["name_or_path"] 替换 model 与 tokenizer——即目标模型从 draft 模型的 config 中解析出来，draft 模型本身则作为投机配置的 model。

这意味着部署侧的完整配置信息（目标模型、draft 模型、method、投机深度）都收敛在 speculators 模型的 config.json 一个文件里，真正做到"下载即用"。

端到端正确性验证：仓库中的集成测试

tests/v1/e2e/spec_decode/speculators/test_speculators.py 中的 test_speculators_model_integration 完整验证了上述简化集成路径。该测试以 RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3（GSM8k 参考区间 75%～80%，阈值 0.72）和 RedHatAI/Qwen3-8B-speculator.eagle3（参考区间 87%～92%，阈值 0.84）两个 speculators 格式模型为样本，检查：

• speculator 模型被正确检测，speculative_config 被自动推断且 num_speculative_tokens > 0；
• draft 模型被设置为 speculator 模型自身，验证器模型从其 config 中正确提取；
• 开启投机解码后 GSM8k 精度通过合理性阈值；
• 开启投机解码的输出与同一验证器模型关闭投机解码的参考输出一致（66% 以上的 prompt 完全匹配）。

该测试同时是 lossless 性质的验证：与 docs/features/speculative_decoding/README.md 所述一致，vLLM 的投机解码在算法层面经过验证是无损的（被接受的 token 等价于目标模型在同一采样配置下的输出），仅有浮点精度与 batch 尺寸带来的 logprob 微小差异。

方法选型与延伸阅读

Speculators 产出的 draft 模型主要服务于模型类方法（EAGLE 系列、并行 draft），这类方法在低 QPS 延迟场景下收益最高；而 n-gram、suffix 等轻量方法适合高 QPS 峰值流量下不想增加额外 draft 负载的部署。完整的 --speculative-config schema（各 key 的类型、默认值与适用 method）、各方法横向对比表与无损性说明，见 docs/features/speculative_decoding/README.md。

整体工作流可概括为一条闭环：vLLM 抽取目标模型 hidden states 落盘 → Speculators 库训练单层/多层 draft（支持 MoE）→ 以 speculators 标准格式（Hugging Face 兼容）保存 → vllm serve 加载 draft 模型自动解析出验证器与投机配置 → 无损投机解码上线。仓库内可直接参考的资源包括 示例脚本、hidden state 抽取文档、配置解析实现与端到端集成测试，可沿此深入各层实现细节。