本文基于 vLLM commitid:c314af1abfddff7b6cce9af578be72c496c6a5e4的代码分析各种投机采样算法实现

一、vLLM 支持的投机采样方法总览

方法枚举定义在 vllm/config/speculative.py:66-76(SpeculativeMethod),MTP 子类型在 :37-59(MTPModelTypes)。共有以下几大类:

方法 `method`	类别	是否需要额外草稿模型	核心实现(Proposer)
`ngram`	无模型 / 基于历史串匹配	否	`vllm/v1/spec_decode/ngram_proposer.py:12`
`ngram_gpu`	无模型,GPU 版 n-gram	否	`vllm/v1/spec_decode/ngram_proposer_gpu.py:28`
`suffix`	无模型 / 后缀树(Arctic Inference)	否(需装 arctic-inference 包)	`vllm/v1/spec_decode/suffix_decoding.py:9`
`draft_model`	独立小模型自回归草稿	是(任意小 LLM)	`vllm/v1/spec_decode/draft_model.py:19`
`eagle`	EAGLE v1/v2 头	是(EAGLE head)	`vllm/v1/spec_decode/eagle.py:10`
`eagle3`	EAGLE3 头	是(EAGLE3 head)	`eagle.py`(共用)+ GPU `worker/gpu/spec_decode/eagle/`
`mtp`	Multi-Token Prediction(统一入口)	权重多数内置于目标模型	依子类型分派,见下
`medusa`	Medusa 多头	是(medusa head)	`vllm/v1/spec_decode/medusa.py:18`
`mlp_speculator`	MLP 预测头	是(accelerator 权重)	`vllm/v1/spec_decode/llm_base_proposer.py`
`dflash`	DFlash(非因果注意力并行草稿)	是	`vllm/v1/spec_decode/dflash.py:23`
`dspark`	DSpark(块级草稿,DeepSeek/Qwen3/Gemma4)	权重随目标 checkpoint	`worker/gpu/spec_decode/dspark/`
`extract_hidden_states`	从目标模型抽取隐藏态(工具/训练用)	否(包裹目标模型)	`vllm/v1/spec_decode/extract_hidden_states.py:29`
`custom_class`	用户自定义 proposer(dotted path)	视实现	`vllm/v1/spec_decode/custom_class_proposer.py:12`

方法是怎么被自动识别的

关键在 SpeculativeConfig.__post_init__,自动检测段在 speculative.py:868-911。优先级从上到下:

若显式给了 method(eagle/eagle3/dflash/dspark)则直接采用(:869-870)
草稿模型名里含 eagle- 则 eagle(:876)
含 eagle3 则 eagle3(:878)
含 dflash 则 dflash(:880)
含 dspark 或架构是 Qwen3DSparkModel/Gemma4DSparkModel 则 dspark(:882-887)
hf_config.model_type == "medusa" 则 medusa(:888)
== "mlp_speculator" 则 mlp_speculator(:890)
model_type ∈ MTPModelTypes 则 mtp(:892-895)
否则则 draft_model(默认,:906)

另外在更早的 :675-690:含 ngram 字样归为 ngram;自定义类路径归为 custom_class;老的 deepseek_mtp 等子类型做向后兼容自动映射到 mtp。

二、各方法适用的主流开源模型

1. 无模型类(对模型无限制,适用于任意模型)

ngram / ngram_gpu:纯字符串匹配,不需要草稿模型,适用于任何模型。对高重复度场景(RAG、代码补全、长文摘要)效果好。文档示例用 Qwen/Qwen3-8B。
suffix:后缀解码(Arctic Inference),同样与目标模型无关,适合 agent/多轮重复场景。

2. draft_model(通用,靠 tokenizer 兼容)

目标模型 + 同族小模型做草稿。典型:Qwen/Qwen3-4B-Thinking-2507 配 Qwen/Qwen3-0.6B;Llama 系列配小 Llama。
支持 use_heterogeneous_vocab 允许草稿/目标词表不同(如 HuggingFaceTB/SmolLM2-135M-Instruct 给别的目标做草稿)。

3. EAGLE / EAGLE3(需专门训练的 head)

eagle:yuhuili/EAGLE-LLaMA3-Instruct-8B(配 meta-llama/Meta-Llama-3-8B-Instruct)
eagle3:yuhuili/EAGLE3-LLaMA3.1-Instruct-8B、RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3、AngelSlim/Qwen3-8B_eagle3

4. MTP(目标模型自带的多 token 预测层)

mtp 是统一入口,具体子类型由草稿(通常即目标自身)的 model_type 决定,覆盖模型家族(见 MTPModelTypes):

deepseek_mtp → DeepSeek-V3/V4 系列
qwen3_next_mtp / qwen3_5_mtp → Qwen3-Next / Qwen3.5
glm4_moe_mtp / glm4_moe_lite_mtp / glm_ocr_mtp → GLM-4 MoE 系列
ernie_mtp → 文心 ERNIE
mimo_mtp / mimo_v2_mtp → 小米 MiMo(如 XiaomiMiMo/MiMo-7B-Base)
gemma4_mtp → Gemma-4(如 google/gemma-4-E2B-it 配 gg-hf-am/gemma-4-E2B-it-assistant,走专用 gemma4.py:31 proposer)
step3p5_mtp → Step-3.5(专用 step3p5.py:24)
其余:nemotron_h_mtp、exaone_moe_mtp/exaone4_5_mtp、longcat_flash_mtp、minimax_m3_mtp、bailing_hybrid_mtp、pangu_ultra_moe_mtp、hy_v3_mtp、inkling_mtp

5. Medusa / MLP Speculator(经典 head 类)

medusa:FasterDecoding/medusa-* 系列(老格式 config 无 model_type,vLLM 会注入,见 :817-823)
mlp_speculator:IBM 的 accelerator,如 ibm-ai-platform/llama3-8b-accelerator、ibm-ai-platform/llama-13b-accelerator

6. DFlash / DSpark(较新,专用草稿)

dflash:laguna-ai/Laguna-Qwen3-32B-dflash(需非因果注意力后端,常配 attention_backend: FLASH_ATTN)
dspark:deepseek-ai/dspark_qwen3_4b_block7 / ..._8b_block7,以及 DeepSeek-V4 DSpark(权重随目标 checkpoint,:934-940)

三、各方法的起服务命令

统一通过 --speculative-config '{...}'(简写 -sc)传 JSON,解析见 vllm/engine/arg_utils.py:1557。以下为文档/测试里的真实示例。

ngram / ngram_gpu(无需模型)

vllm serve Qwen/Qwen3-8B \
  --speculative-config '{"method":"ngram","num_speculative_tokens":5,"prompt_lookup_max":4,"prompt_lookup_min":2}'

suffix

vllm serve <目标模型> \
  --speculative-config '{"method":"suffix","num_speculative_tokens":32,"suffix_decoding_max_spec_factor":2.0}'

draft_model

vllm serve Qwen/Qwen3-4B-Thinking-2507 -tp 1 --max-model-len 2048 \
  --speculative-config '{"method":"draft_model","model":"Qwen/Qwen3-0.6B","num_speculative_tokens":5}'

eagle / eagle3

vllm serve meta-llama/Meta-Llama-3-8B-Instruct --tensor-parallel-size 4 \
  --speculative-config '{"method":"eagle","model":"yuhuili/EAGLE-LLaMA3-Instruct-8B","num_speculative_tokens":2,"draft_tensor_parallel_size":1}'

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --speculative-config '{"method":"eagle3","model":"RedHatAI/Llama-3.1-8B-Instruct-speculator.eagle3","num_speculative_tokens":3,"max_model_len":16384}'

mtp(权重通常内置于目标模型,一般无需单独 model)

vllm serve XiaomiMiMo/MiMo-7B-Base -tp 1 \
  --speculative-config '{"method":"mtp","num_speculative_tokens":1}'

# Gemma4 需要单独 assistant 权重:
vllm serve google/gemma-4-E2B-it -tp 1 --max-model-len 8192 \
  --speculative-config '{"method":"mtp","model":"gg-hf-am/gemma-4-E2B-it-assistant","num_speculative_tokens":1}'

medusa

vllm serve <目标模型> \
  --speculative-config '{"method":"medusa","model":"FasterDecoding/medusa-vicuna-7b-v1.3","num_speculative_tokens":4}'

mlp_speculator

vllm serve meta-llama/Meta-Llama-3-8B-Instruct \
  --speculative-config '{"method":"mlp_speculator","model":"ibm-ai-platform/llama3-8b-accelerator","draft_tensor_parallel_size":1}'

dflash

vllm serve <Qwen3-32B 目标> \
  --speculative-config '{"method":"dflash","model":"laguna-ai/Laguna-Qwen3-32B-dflash","num_speculative_tokens":16,"max_model_len":32768,"attention_backend":"FLASH_ATTN"}'

dspark

vllm serve <Qwen3 目标> \
  --speculative-config '{"method":"dspark","model":"deepseek-ai/dspark_qwen3_4b_block7","num_speculative_tokens":7,"attention_backend":"FLASH_ATTN","draft_sample_method":"probabilistic"}'

下一篇我们将逐个分析，每一种算法是怎么工作的，进行详细的code walk through

vLLM各种投机采样算法实现分析(上)