vLLM 源码完全拆解（三十二）：投机解码的配置层——SpeculativeConfig 如何把 method 变成一条执行路径

为什么值得单独讲配置层

前面几篇已经分别讲过 vLLM 的投机解码流水线、EAGLE 草稿、批量验证和 KV 回滚。那些文章回答的是“草稿 token 怎么生成、怎么验证、被拒绝的 KV 怎么释放”。但有一个更靠前的问题一直没有系统展开：vLLM 到底怎么决定这次服务走哪一条投机路径？

答案集中在 vllm/config/speculative.py 里的 SpeculativeConfig。它看起来只是一个 dataclass，实际上承担了三个职责：

1. 把用户输入的 JSON、YAML 或旧式命令行参数，规范化成一组有约束的字段；
2. 根据 method 字段和草稿 checkpoint 的声明，选择对应的 SpeculatorConfig 实现类；
3. 把该实现类的能力标志（是否读目标模型隐状态、需要多少 lookahead KV 槽、是否独立 workspace）暴露给调度器、KV 管理器和模型执行器。

换句话说，投机解码在 vLLM 里的所有分支，最终都能追溯到这个对象上的某个字段或某个 ClassVar。本文基于 vLLM main 分支 2026 年 11 月的源码，按“字段 → 分派 → 派生配置 → 运行时契约 → 校验 → 实战”的顺序走一遍。文中出现的代码都是真实源码的节选，省略了与本主题无关的装饰器和类型注解。

SpeculativeMethod：一个封闭集合，外加一个注册表

先看方法名的类型定义。源码把内置方法写成一个 Literal 联合：

1
SpeculativeMethod = Literal[
2
    "ngram",
3
    "draft_model",
4
    "suffix",
5
    "custom_class",
6
    EagleModelTypes,
7
    NgramGPUTypes,
8
    DSparkModelTypes,
9
]

其中 EagleModelTypes 又展开为：

1
EagleModelTypes = Literal[
2
    "eagle", "eagle3", "extract_hidden_states", MTPModelTypes, DFlashModelTypes
3
]

MTPModelTypes 是一长串模型类型名，包含 deepseek_mtp、mimo_mtp、glm4_moe_mtp、ernie_mtp、nemotron_h_mtp 等。这些名字并不是让用户一个一个去记，而是为了兼容各家 checkpoint 在 model_type 字段里写下的不同 MTP 变体。构造阶段会把它们统一归一成 "mtp"，细节在后面讲。

除了内置集合，源码还留了一个运行时注册表：

1
def register_speculative_method(name, config_cls):
2
    if name in get_args(SpeculativeMethod) or name in _CONFIG_BY_METHOD:
3
        raise ValueError(f"'{name}' is a built-in speculative method.")
4
    if name in _CUSTOM_CONFIGS and _CUSTOM_CONFIGS[name] != config_cls:
5
        raise ValueError(f"Speculative method '{name}' is already registered.")
6
    _CUSTOM_CONFIGS[name] = config_cls
7

8
def registered_speculative_methods() -> list[str]:
9
    return sorted(_CUSTOM_CONFIGS)

注册表的存在，意味着插件可以定义自己的投机方法：写一个 SpeculatorConfig 子类，设置 speculator_class 指向自己的 BaseSpeculator 实现，然后在 vLLM 的 general plugin 里注册。SpeculativeConfig.method 的校验器会先查内置集合，查不到再查注册表：

1
@field_validator("method")
2
def _validate_method(cls, value):
3
    if value is None or value in get_args(SpeculativeMethod):
4
        return value
5
    if value not in (registered := registered_speculative_methods()):
6
        raise ValueError(
7
            f"Unknown speculative method {value!r}. Built-in methods: "
8
            f"{sorted(get_args(SpeculativeMethod))}; registered custom "
9
            f"methods: {registered}."
10
        )
11
    return value

这是一个很典型的设计：内置方法用静态 Literal 获得类型检查和 IDE 补全，外部方法用动态注册获得扩展性，两条路径在同一个校验点汇合。错误消息同时列出两类方法名，部署脚本里写错方法名时能直接看到正确候选。

SpeculativeConfig 的字段全景

SpeculativeConfig 的字段很多，如果按源码顺序读会显得零散。按用途可以分成五组。

post_init：一次构造，三层查找

SpeculativeConfig 的 __post_init__ 是整个配置层最核心的函数。它要在一个构造函数里完成方法推断、别名归一、配置类查找和草稿模型派生。可以把流程画成三层查找。

第一层是用户输入。无论用户写的是 --speculative-config '{"method": ...}'、旧式散装参数，还是 Python 里直接构造 SpeculativeConfig，最终都变成 dataclass 字段。真正完成这层归一的是 EngineArgs.create_speculative_config：它把 --spec-method、--spec-model、--spec-tokens 三个旧式参数合并进 --speculative-config 字典，检查同一个字段是否被两种写法同时指定，把连字符键名统一成下划线，再注入目标模型的 ModelConfig 与 ParallelConfig，最后调用 SpeculativeConfig(**kwargs)。源码在这里特意把 argparse 的类型设成 json.loads，就是为了推迟 Pydantic 校验——因为 SpeculativeConfig 的构造依赖目标模型配置，命令行解析阶段还拿不到它。

第二层是方法推断。源码的注释交代了设计意图：method 是后来引入的参数，用来描述“不依赖模型的草稿器”；model 仍然表示草稿模型、EAGLE 头或额外权重。如果用户没有显式给 method，源码会尽量从 model 推断；推断不出来就默认按 "draft_model" 处理。

推断顺序大致是：

1
if (custom_cls := get_custom_speculator_config_class(self.method)) is not None:
2
    self.custom_method = self.method
3
    self.method = custom_cls.base_method
4
elif self.method is None and SpeculativeConfig._is_custom_proposer_path(self.model):
5
    self.method = "custom_class"
6
elif self.method is None and self.model in ("ngram", "[ngram]"):
7
    self.method = "ngram"
8
elif self.method is None and self.model is None:
9
    self.method = "draft_model"

注意第一支：如果 method 命中注册表，源码不会把它留在 method 里，而是先存进 custom_method，再把 method 改写成该自定义方法所继承的内置方法。后面的所有逻辑——找配置类、取 base_method、检查 supported_options——都只认内置方法名。这是一个很干净的隔离：自定义方法只需要声明“我基于哪一种内置形态”，框架不需要为它写一套平行分支。

接着是别名归一：

1
if self.method in get_args(MTPModelTypes) and self.method != "mtp":
2
    logger.warning("method `%s` is deprecated and replaced with mtp.", self.method)
3
    self.method = "mtp"
4
elif self.method == "[ngram]":
5
    self.method = "ngram"

老 checkpoint 里常见 deepseek_mtp、glm4_moe_mtp 这类方法名。源码保留它们作为输入别名，但内部统一按 mtp 处理，并打一条弃用警告。这样做的好处是旧部署脚本不会立刻失效，同时内部只有一条 MTP 路径需要维护。

第三层是配置类查找。get_method_config_class 把方法名映射到 _CONFIG_BY_METHOD 中的类：

1
_CONFIG_BY_METHOD = {
2
    "extract_hidden_states": "...ExtractHiddenStatesSpeculatorConfig",
3
    "draft_model": "...StandaloneARSpeculatorConfig",
4
    "ngram": "...NgramSpeculatorConfig",
5
    "ngram_gpu": "...NgramGPUSpeculatorConfig",
6
    "eagle": "...EagleSpeculatorConfig",
7
    "eagle3": "...Eagle3SpeculatorConfig",
8
    "mtp": "...MTPSpeculatorConfig",
9
    "dflash": "...DFlashSpeculatorConfig",
10
    "dspark": "...DSparkSpeculatorConfig",
11
}

"suffix" 和 "custom_class" 不在这个字典里，它们会走 V1 专用的 v1_speculator_configs 模块。这个分叉很重要：V1 的 suffix decoding 和“按模块路径注册 proposer”是旧模型执行器的能力，V2 speculator 架构没有对应实现，所以源码用 _V1_ONLY_METHODS 明确隔离。

拿到配置类后，执行 config_cls.default_model(self)。这个钩子决定“用户没给 model 时，草稿模型从哪里来”：

• N-gram 的默认模型是 None，因为它本来就不需要权重；
• MTP 的默认模型是目标模型的权重路径。源码优先取 target.model_weights，因为某些加载器（如 runai_streamer）会把 model 改成本地缓存目录，而原始路径保存在 model_weights 里；
• DSpark 对 DeepSeek 系列默认指向目标模型：V4/V4.1 的 DSpark 权重就放在目标 checkpoint 里，不需要单独下载；MiniMax-M3 等目标则走单独的草稿下载路径；
• EAGLE 和独立草稿模型没有合理默认值，必须由用户显式指定。

随后调用 config_cls.configure(self)。这个钩子做三件事：填默认值、构造草稿 ModelConfig、必要时改写 method。N-gram 的 configure 会补上 prompt_lookup_min = prompt_lookup_max = 5。源码的 TODO 写得很坦率：这两个值是“任意选的”，还没有系统调参。独立草稿模型的 configure 则要构造一份完整的 ModelConfig(runner="draft", ...)，细节下一节展开。

configure 之后还有一个容易被忽略的步骤：get_speculator_config_class 会再查一次草稿 checkpoint 自己声明的 speculator_config_class：

1
declared_cls = _get_draft_declared_config_class(spec_config)
2
if declared_cls is not None and issubclass(declared_cls, config_cls):
3
    return declared_cls
4
return config_cls.specialize(spec_config)

这解决了一个现实问题：同一个 method="mtp"，不同 checkpoint 可能需要不同的草稿图。与其在 vLLM 里写一堆 if model_type == ...，不如让 checkpoint 自己声明配置类。specialize 是第二层机制，用于在同一个方法内部按字段细分，例如 MTPSpeculatorConfig.specialize 会在多模块 MTP 时返回 MultiModuleMTPSpeculatorConfig。

如果没有声明，就按固定顺序检测 checkpoint：

1
_CHECKPOINT_DETECTION_ORDER = ("eagle", "eagle3", "dflash", "dspark", "mtp")

每个配置类的 matches 用模型路径或 model_type 判断。例如 EagleSpeculatorConfig.matches 检查路径里是否含 "eagle-"，Eagle3SpeculatorConfig.matches 检查是否含 "eagle3"，MTPSpeculatorConfig.matches 检查 hf_config.model_type 是否属于 MTP 类型集合。顺序有讲究：eagle 在 eagle3 之前，但 eagle3 的匹配串更长、更具体；如果路径同时包含两者，先命中 eagle 反而可能误判。源码目前按这个顺序写，实际部署时最好显式给 method，不要依赖路径猜测。

如果用户显式给了 method，而 checkpoint 声明的 base_method 与它不一致，源码会直接报错，并在消息里说明草稿模型实际是什么类型：

1
raise ValueError(
2
    f"speculative_config requested method={requested!r}, but "
3
    f"the draft model {draft.model!r} is a {declared!r} checkpoint ..."
4
)

这类错误在部署阶段比运行阶段更有价值。它把“配置写错”与“权重不匹配”两类问题提前到了启动期。

最后是 supported_options 检查。源码维护一份方法专属选项列表：

1
_METHOD_SPECIFIC_OPTIONS = (
2
    "dspark_draft_topk",
3
    "draft_lm_head_quantization",
4
    "index_share_for_mtp_iteration",
5
    "xpress_topc",
6
    "speculator_options",
7
)

如果某个选项非空，但当前配置类的 supported_options 不包含它，就报错。例如给 MTP 配 dspark_draft_topk，或者给 EAGLE 配 index_share_for_mtp_iteration，都会在启动期被拦下。这个机制比在每个方法里手写 if 更可维护：新增选项时只需要在对应配置类声明它支持，检查逻辑不用改。

SpeculatorConfig：方法能力的声明式描述

三层查找最终都会落到一个 SpeculatorConfig 实例上。它不是草稿器本身，而是草稿器的配置描述。源码把它的定位写得很清楚：默认值描述“一个没有草稿 checkpoint、也没有特殊要求”的草稿器；自定义草稿器可以继承它，或者继承某个内置草稿器的配置类。

SpeculatorConfig 用 ClassVar 声明静态能力，用 property 声明依赖配置字段的动态值。

1
base_method: ClassVar[str | None] = None
2
speculator_class: ClassVar[str | None] = None
3
supported_options: ClassVar[frozenset[str]] = frozenset()
4

5
uses_target_hidden_states: ClassVar[bool] = False
6
uses_separate_workspace_lane: ClassVar[bool] = False
7
prefer_dense_token_history: ClassVar[bool] = False
8
proposes_draft_tokens: ClassVar[bool] = True
9
adaptive_verification_uses_draft_logits: ClassVar[bool] = True
10
draft_has_own_vocab: ClassVar[bool] = False
11
supports_watermarking: ClassVar[bool] = False
12
supports_pcp: ClassVar[bool] = False

1
@property
2
def num_lookahead_tokens(self) -> int:
3
    return 0
4

5
@property
6
def max_model_len(self) -> int | None:
7
    return None
8

9
@property
10
def num_prefill_lookahead_tokens(self) -> int:
11
    return 1 if self.uses_target_hidden_states else 0
12

13
@property
14
def max_num_new_slots_for_drafting(self) -> int:
15
    return 0

1
_CACHE_ONLY_ROPE_TYPES = frozenset(
2
    {"default", "linear", "llama3", "ntk", "proportional"}
3
)

StandaloneAR 的 configure：一份草稿 ModelConfig 怎么诞生

独立草稿模型是最容易理解的路径，也是观察 vLLM 配置层细节最好的样本。DraftModelSpeculatorConfig.configure 在用户给了 model 时会构造：

1
spec.draft_model_config = ModelConfig(
2
    model=spec.model,
3
    runner="draft",
4
    tokenizer=(spec.model if spec.use_heterogeneous_vocab else target.tokenizer),
5
    tokenizer_mode=target.tokenizer_mode,
6
    dtype=target.dtype,
7
    max_model_len=spec.max_model_len,
8
    spec_target_max_model_len=target.max_model_len,
9
    quantization=spec.quantization,
10
    hf_overrides=draft_hf_overrides,
11
    ...
12
)

可以按来源把这些字段分成三类。

第一类继承目标模型：tokenizer_mode、dtype、seed、trust_remote_code、enforce_eager、max_logprobs、config_format。这些字段不影响草稿模型的“身份”，只影响运行时环境，继承是为了减少配置负担。

第二类来自草稿专属字段：model、revision、code_revision、quantization。这些是用户为草稿模型单独指定的。

第三类需要特殊处理：

• runner="draft" 告诉 ModelConfig 这不是目标模型，某些校验和默认值会走草稿分支；
• tokenizer 默认继承目标。只有开了 use_heterogeneous_vocab 才用草稿自己的 tokenizer，因为此时两边词表不同，需要各自的编码器；
• max_model_len 用 spec.max_model_len，可以为空；
• spec_target_max_model_len 把目标模型的上限传进去，供 ModelConfig 在校验时参考。

hf_overrides 的合并也有一层讲究。源码把目标的 hf_overrides 分成两类：可调用的和字典形式的。字典形式的覆盖会改变目标模型的结构（例如替换注意力实现），不应该作用于草稿模型；可调用的覆盖通常是运行时开关（例如强制某个 RoPE 实现），两边都应该生效。compose_draft_hf_overrides 只把可调用部分传给草稿模型。

草稿 ModelConfig 构造完后，源码还会做几件事：

1. 如果配置类声明 shares_target_positions，尝试抬高草稿的 max_position_embeddings；
2. 调用 adapt_draft_model_config，例如 EAGLE 会把草稿的 hf_config 包一层 EAGLEConfig；
3. 调用 resolve_num_speculative_tokens，从 checkpoint 的 n_predict 推导 K；
4. 校验 draft_tensor_parallel_size；
5. 调用 create_draft_parallel_config 派生草稿并行配置。

第四步的校验函数很简短，但约束很强：

1
if speculative_draft_tensor_parallel_size is None:
2
    speculative_draft_tensor_parallel_size = target_parallel_config.tensor_parallel_size
3
elif speculative_draft_tensor_parallel_size not in (1, target_parallel_config.tensor_parallel_size):
4
    raise ValueError(
5
        f"{speculative_draft_tensor_parallel_size=} cannot be "
6
        f"other value than 1 or target model tensor_parallel_size"
7
    )

为什么只允许这两个值？因为草稿模型和目标模型必须跑在同一组 GPU 上，权重切分要么全切（与目标一致），要么不切（每卡一份）。中间值会让 TP 组的通信拓扑冲突。

第五步的 create_draft_parallel_config 还有一个细节：专家并行只在草稿本身是 MoE 时才继承。源码的判断是：

1
enable_ep = target_parallel_config.enable_expert_parallel
2
if draft_model_config is not None:
3
    enable_ep = enable_ep and draft_model_config.is_moe

如果目标模型是 MoE 并开了 EP，草稿是稠密小模型，那么草稿不应该被纳入 EP。否则执行器会按专家并行去切分一个没有专家的模型，要么报错，要么产生无意义的通信。

resolve_num_speculative_tokens 里有一条 MTP 专属校验也值得注意：

1
n_predict = getattr(spec.draft_model_config.hf_config, "n_predict", None)
2
if spec.num_speculative_tokens is None:
3
    spec.num_speculative_tokens = n_predict
4
elif spec.num_speculative_tokens > n_predict and spec.num_speculative_tokens % n_predict != 0:
5
    raise ValueError(
6
        f"num_speculative_tokens:{spec.num_speculative_tokens}"
7
        f" must be divisible by {n_predict=}"
8
    )

MTP 层的数量由 checkpoint 决定，例如 DeepSeek 系列通常是一到若干层。如果用户想每步草稿超过层数，就必须是层数的整数倍，因为实现会循环复用这些 MTP 模块；不是整数倍就无法均匀分配，接受率也会变得难以解释。

compute_hash：配置如何进入编译缓存键

配置层还有一个容易被忽略的职责：产生哈希，作为编译缓存的键。compute_hash 的注释写得非常明确：

Provide a hash that uniquely identifies all the configs that affect the structure of the computation graph from input ids/embeddings to the final hidden states.

它列出的因素包括：

• uses_aux_hidden_states：EAGLE3 和 extract_hidden_states 会额外返回中间层隐状态，图结构不同；
• 草稿模型的 compute_hash()；
• eagle_aux_hidden_state_layer_ids：具体接哪几层，也改变图；
• custom_method；
• speculator_options 的排序项；
• speculator_config.hash_factors()。

最后一项是各配置类自己补充的因素。MTPSpeculatorConfig.hash_factors 返回 index_share_for_mtp_iteration，因为是否共享稀疏索引会改变草稿图；DSparkSpeculatorConfig.hash_factors 返回 enable_adaptive_verification，因为自适应验证会改变 DSpark 的草稿图。

这里有一个容易踩坑的地方：新增字段时必须同步更新 factors。如果某个字段影响图结构却没进哈希，两个不同配置会命中同一份编译缓存，轻则性能不符预期，重则加载了错误的 kernel。注释用 WARNING 强调这一点，说明它确实发生过。

运行时：谁在读这些字段

配置层本身不做计算，它的价值在于被谁读取。按读者梳理一遍，可以更清楚它在系统中的位置。

1
def needs_eagle_block_drop(self) -> bool:
2
    return self.use_eagle() and not (self.use_dflash() or self.use_dspark())
3

4
def use_eagle_block_drop(self) -> bool:
5
    return self.needs_eagle_block_drop() and not self.disable_eagle_block_drop

_verify_args：启动期的静态检查清单

__post_init__ 末尾会调用 _verify_args。它把跨字段的约束集中在一个地方，可以作为部署前的检查清单。

1
if self.tensor_parallel_size is not None:
2
    raise ValueError("'tensor_parallel_size' is not a valid argument in the "
3
                     "speculative_config. Please pass 'draft_tensor_parallel_size' instead.")
4
if self.num_speculative_tokens is None:
5
    raise ValueError("num_speculative_tokens must be provided with speculative model ...")
6
if self.num_speculative_tokens <= 0:
7
    raise ValueError(...)

1
if (rates is None) == (length is None):
2
    raise ValueError(
3
        "rejection_sample_method='synthetic' requires exactly one of "
4
        "synthetic_acceptance_rates or synthetic_acceptance_length."
5
    )

1
elif (self.synthetic_acceptance_rates is not None
2
      or self.synthetic_acceptance_length is not None):
3
    raise ValueError(
4
        "synthetic_acceptance_rates / synthetic_acceptance_length "
5
        "are only valid with rejection_sample_method='synthetic'."
6
    )

1
if self.draft_model_config:
2
    self.draft_model_config.verify_with_parallel_config(self.draft_parallel_config)

N-gram 草稿器：配置项落到一个 KMP 扫描

N-gram 是唯一一个不需要任何权重的投机方法，也因此最适合用来观察“配置项如何落到算法”。它的配置只有三个字段真正参与计算：

• prompt_lookup_min：最短匹配窗口；
• prompt_lookup_max：最长匹配窗口；
• num_speculative_tokens：最多取多少个后续 token。

NgramProposer.__init__ 把它们读成 min_n、max_n、k，再读目标模型的 max_model_len。然后预分配两个 max_num_seqs × k 的 int32 缓冲区，用于批量草稿结果。

真正有意思的是 _find_longest_matched_ngram_and_propose_tokens。它要回答的问题是：给定一条已经生成的 token 序列，找出它的后缀中与序列内部某个片段相同的最长 n-gram，然后把该片段后面的 k 个 token 当作草稿。

源码用了一个很巧的处理：先把整个序列翻转。翻转之后，“后缀匹配”变成“前缀匹配”，问题转化为标准的 KMP 前缀函数计算。注释里给出的定义是：

也就是“以位置 i 结尾的最长后缀，同时是整个翻转序列的前缀”。KMP 的递推逻辑是：

• 如果 tokens[prev_lps] == tokens[i]，前缀长度加一；
• 否则回退到 lps[prev_lps-1]，继续尝试更短的前缀；
• 当长度达到 max_n 时，主动回退到 lps[max_n-1]，避免匹配超过配置上限。

源码里有一个容易忽略的细节：

1
if prev_lps >= longest_ngram:
2
    longest_ngram = prev_lps
3
    position = i

这里用的是 >= 而不是 >。因为序列已经翻转，i 越大表示在原序列里越靠前。用 >= 会让相同长度的匹配保留更靠后的 i，也就是原序列里更早出现的位置。源码注释解释了动机：希望取原序列中最早出现的那个匹配，而不是最近的。

找到最长匹配后，还要把它映射回原序列：

1
start_position = total_token - 1 - position + longest_ngram
2
k = min(k, total_token - start_position)
3
return origin_tokens[start_position : start_position + k]

第一行把翻转坐标还原成原坐标，并跳过匹配到的 n-gram 本身；第二行保证不会取到序列末尾之外。

整个扫描只依赖当前请求自己的 token 序列，不依赖一个全局语料库。这一点经常被误解：名字里的 “prompt lookup” 听起来像是在一个外部 prompt 集合里查找，实际上它只在当前序列内部找重复片段。因此它的收益高度依赖输入的结构：代码、表格、重复模板、few-shot 示例这类高重复文本收益明显；开放式创意写作几乎没有可匹配片段，草稿长度会经常为 0。

配置层的两个默认值也值得注意。NgramSpeculatorConfig.configure 在用户没给窗口时直接设成 5 和 5，源码的 TODO 写的是“任意选的，还没有调参”。这意味着默认配置并不是一个经过系统优化的值，只是能跑。实际部署时应该根据负载的重复度调整：重复度高的场景可以把 prompt_lookup_max 调大，让匹配更具体；重复度低时缩小窗口，避免匹配到过于泛化的短片段。

批量路径则用 Numba 并行。源码设了一个 8192 token 的阈值：批内总 token 数低于阈值时用单线程，高于阈值才启用多线程，避免线程调度开销盖过收益。线程数被限制为 min(1, cpu_count // 2) 再除以 TP 度，注释里保留了把上限从 1 提到 8 的 TODO，原因是当前 N-gram 还没有做 TP 并行化，所有 TP rank 都会跑同一份 proposer，线程开多了只会互相抢核。

NgramProposer.__init__ 末尾还会用一批 dummy 请求触发一次 JIT 编译。注释估计编译时间不到一秒，但如果不预热，第一个真实请求会承担这段延迟。对在线服务来说，这一秒的尾延迟很容易被监控抓到。

V2 的路径有所不同：NgramSpeculatorConfig.speculator_class 指向 NgramGPUSpeculator，而 ngram_gpu 这个独立方法名也映射到同一族实现。V1 则继续使用上面这个 CPU 版 NgramProposer。两套实现共享同一组配置字段，但执行位置不同。

草稿器的形态：从 EAGLE 到 Medusa，再到块扩散

配置层的 method 最终对应到不同的草稿图。理解这些图的形态，才能明白为什么某些字段只对某些方法有意义。

EAGLE 的核心是把“草稿”从 token 空间搬到特征空间。它不训练一个完整的小语言模型，而是复用目标模型倒数几层的隐状态，加上当前 token 的 embedding，输入一个小型 Transformer 来预测下一 token 的特征。论文给出的整体结构如下。

图源：EAGLE 论文（arXiv:2401.15077）图 1。

这张图解释了 uses_target_hidden_states 为什么是 EAGLE 系的核心标志：草稿头的输入不是原始 token，而是目标模型内部的特征。因此模型执行器必须在前向时额外输出中间层隐状态，eagle_aux_hidden_state_layer_ids 决定接哪几层。也解释了 needs_eagle_block_drop：位置 p 的草稿 KV 依赖位置 p 的隐状态和下一个 token，在下一个 token 被确认之前，这个 KV 是不稳定的。

Medusa 走了另一条路：不训练草稿头去预测特征，而是在目标模型最后隐状态之上接多个轻量头，每个头预测第 k 步之后的 token。它的结构如下。

图源：Medusa 论文（arXiv:2401.10774）。

多个头并行预测，意味着候选 token 之间可能互相矛盾，验证时必须把它们组织成一棵树，而不是一条链。Medusa 论文里的树注意力示意如下。

图源：Medusa 论文（arXiv:2401.10774）。

树状验证的代价是 mask 构造和输入布局更复杂。也正因为这个代价，2026 年的 vLLM 内置方法列表里已经没有 medusa：并行草稿的生态位被 DFlash 和 DSpark 占据，它们用块扩散或块并行草稿绕开了“多分支树验证”的复杂度。DFlash 的 num_lookahead_tokens = K+1 和 max_num_draft_seqs 就是为这种块式草稿准备的：后者直接用 max_num_batched_tokens // num_lookahead_tokens 算出草稿 pass 最多能容纳多少请求，因为它每个请求的草稿查询数比目标 batch 的每请求查询数更多。

这也说明配置层的 method 列表不是一张永久不变的表。旧方法会被移除，新方法会通过注册表加入；读源码时要同时看 SpeculativeMethod 和 _CONFIG_BY_METHOD，后者才是真正可用的映射。

方法之间的横向对比

把各 SpeculatorConfig 的能力标志放在一张表里，可以看出设计上的取舍。

从这张表能读出几条设计规律。

第一，读目标隐状态的方法几乎都需要尾块丢弃。EAGLE 系用隐状态加下一个 token 造草稿 KV，DFlash/DSpark 只用隐状态，所以后两者不需要。这说明“隐状态怎么被使用”比“是否读隐状态”更能决定 KV 契约。

第二，独立 workspace 目前只有 DSpark 一个。它是一个特化的并行草稿，把整个草稿 pass 放到单独的 lane 里，避免和目标 batch 抢同一份 workspace 布局。这是一个很强的隔离，代价是显存要单独预留。

第三，PCP 支持集中在 MTP 和 DSpark，两者都是 DeepSeek 系的草稿形态。这说明 PCP 这条路径是为特定生产负载优化的，而不是通用能力。

工程实践：配置层最容易踩的坑

一个完整的配置示例与逐步解析

下面这段配置同时启用了 EAGLE3 和多档动态 K，并给草稿头单独量化：

1
{
2
  "method": "eagle3",
3
  "model": "org/eagle3-draft-head",
4
  "num_speculative_tokens": 4,
5
  "num_speculative_tokens_per_batch_size": [[1, 8, 4], [9, 32, 3], [33, 128, 2]],
6
  "draft_lm_head_quantization": "fp8",
7
  "draft_tensor_parallel_size": 1,
8
  "disable_eagle_block_drop": false
9
}

逐步走一遍：

1. method 已给出且在白名单内，_validate_method 直接通过；
2. __post_init__ 不进入推断分支，因为 method 非空；
3. get_method_config_class 返回 Eagle3SpeculatorConfig；
4. model 非空，configure 构造草稿 ModelConfig，把目标的 hf_config 包成 EAGLEConfig；
5. n_predict 若存在，校验 num_speculative_tokens 与它的关系；
6. get_speculator_config_class 检查草稿是否声明了自己的配置类；未声明则用 Eagle3SpeculatorConfig.specialize；
7. _verify_args 检查 draft_lm_head_quantization：EagleSpeculatorConfig.supported_options 包含它，但还需要草稿的 head_dtype == dtype，否则报错；
8. _verify_and_get_draft_tp 确认 TP=1 合法；
9. create_draft_parallel_config 生成草稿并行配置；
10. 运行时调度器读 num_speculative_tokens_per_batch_size 选择本步 K，KV 管理器读 num_lookahead_tokens 预留槽，执行器读 uses_target_hidden_states 输出隐状态，并读 use_eagle_block_drop 决定是否丢弃尾块。

第 7 步的细节值得展开。draft_lm_head_quantization 只在草稿头的 lm_head 与模型主体使用同一种 dtype 时合法。如果草稿头的 lm_head 本身已经是低精度，再套一层 FP8 量化会引入额外误差，而且目标模型验证时用的不是这个头，接受长度可能明显下降。源码选择在启动期拒绝，而不是运行时警告。

与其它框架配置层的对照

vLLM 的配置层是“声明式能力 + 运行时注册表”的组合。对照其它框架可以更清楚它的位置。

TensorRT-LLM 的投机配置分散在 builder 阶段和 executor 阶段：EAGLE-3 的草稿层和验证策略要在构建期就确定，运行期只能选择开关。它的优势是构建期可以做更激进的融合，劣势是换一种投机方法要重新构建引擎。相关实现可以参考 TensorRT-LLM 源码完全拆解（二十二）：EAGLE-3 一体式草稿。

SGLang 的投机配置更接近 vLLM，同样是运行期选择 draft 模型或 EAGLE，但它的 SpeculativeAlgorithm 枚举和 vLLM 的 method 字符串不完全对应。SGLang 把“草稿器”和“验证器”分开描述，vLLM 则用一个 SpeculatorConfig 同时描述两者。

DeepInfer 的 DSpark 是另一类：草稿和验证都在一个 TileLang kernel 里完成，配置主要决定块大小和置信度调度，而不是“选哪一种草稿器”。相关实现可以参考 DeepInfer 源码完全拆解（五）：投机解码。

这些差异说明：配置层的形状取决于框架把“多样性”放在哪一层。vLLM 把多样性放在 speculator 实现上，配置层只负责把它们统一成一组能力标志；TensorRT-LLM 把多样性放在构建期；DeepInfer 把多样性压缩到一个内核的参数里。

小结

SpeculativeConfig 不是一个简单的参数容器，而是 vLLM 投机解码的分派中枢。它做的事情可以归纳为四步：

1. 把用户输入规范化成有约束的字段，并兼容旧参数与方法别名；
2. 通过 __post_init__ 的三层查找，把 method 和草稿 checkpoint 解析成具体的 SpeculatorConfig 实现类；
3. 让实现类用 ClassVar 声明能力、用 property 描述依赖字段的动态值，形成调度器、KV 管理器和执行器共同读取的契约；
4. 在启动期用 _verify_args 把所有跨字段约束一次性检查完，把错误挡在加载之前。

读懂这一层之后，再看投机解码的草稿生成、批量验证和 KV 回滚，就能明白每一条分支的条件判断是在读哪个字段。配置层是理解整个投机解码实现的地图，后面的源码只是在照着这张地图走路。

下一篇将讨论 vLLM 的 speculator 基类与工厂：SpeculatorConfig.speculator_class 指向的那条类继承链，BaseSpeculator 的 propose 与 accept 接口约定，以及 V1 proposer 与 V2 speculator 两套实现如何在新旧模型执行器之间共存。

参考资料

1. vLLM 仓库：vllm/config/speculative.py
2. vLLM 仓库：vllm/v1/worker/gpu/spec_decode/speculator_config.py
3. vLLM 仓库：vllm/v1/spec_decode/ngram_proposer.py
4. vLLM 官方文档：Speculative Decoding
5. EAGLE: Speculative Sampling Requires Rethinking Feature Uncertainty
6. Medusa: Simple LLM Inference Acceleration Framework with Multiple Decoding Heads
7. DeepSeek-V3 Technical Report（MTP 与多 token 预测）