vLLM 推测解码配置与适用场景
说明 vLLM 推测解码的 JSON 配置，比较草稿模型与 n-gram 方法的启动方式，并解释适用负载、显存参数、启动检查、延迟指标解读和基准测试要点。
配置 vLLM 推测解码时，按 vLLM 的推测解码文档 用 vllm serve --speculative-config 传入单个 JSON：method 的常见值包括 draft_model、ngram、suffix、mtp、eagle3 和 dflash，num_speculative_tokens 表示每步提议的 token 数；同一组键也适用于 Python 的 LLM(..., speculative_config={...})，该功能主要面向中低 QPS、受显存带宽约束、需要降低 token 间延迟的负载。不要把 APC 与推测解码混为一谈：Automatic Prefix Caching 文档 说明，APC 复用相同前缀的 KV cache，适合反复处理同一长文档或复用历史的多轮聊天，但只缩短 prefill；请求没有共同前缀，或时间主要花在生成较长答案时，不会因此获得性能收益。
vllm serve 配置：方法与启动参数
开始前，先确定目标模型标识、业务允许的输入与输出长度上限、可用 GPU 资源，以及能够代表真实业务的请求样本。不要先猜性能数字再选参数。
采用 draft_model 时，Draft Models 文档 的示例用 model 指定 Qwen/Qwen3-0.6B，每步提议 5 个 token；草稿模型与目标模型默认需要共享词表。旧式的 --speculative-model 和 --num-speculative-tokens 分开传参方式已经弃用，应改用统一 JSON：
vllm serve YOUR_VALUE \
--speculative-config '{"model": "Qwen/Qwen3-0.6B", "num_speculative_tokens": 5, "method": "draft_model"}'
将 YOUR_VALUE 替换为符合上述词表约束的目标模型标识，不要原样保留占位符。
如果不想增加一个草稿模型，N-Gram Speculation 文档 说明，ngram 方法不需要草稿模型，候选内容来自 prompt 中匹配的 n-gram：
vllm serve YOUR_VALUE \
--speculative-config '{"method": "ngram", "num_speculative_tokens": 5, "prompt_lookup_max": 4}'
这里的 prompt_lookup_max 是最大 n-gram 窗口。提示中缺少可复用片段时，不要仅凭配置存在就认定它适合当前请求。
适用场景：先判断瓶颈
先按前缀是否复用、输出长短、请求到达压力和主要延迟环节整理真实请求。对同一长文档反复提问或进行多轮聊天时，应把 APC 单独纳入对照；对中低 QPS、显存带宽受限且更关心 token 间延迟的负载，则应测试推测解码。
如果请求之间没有共同前缀，或者长答案生成占据主要时间，不要把 APC 当作解决主要瓶颈的手段。比较草稿模型与 ngram 时，也应保持目标模型、硬件和请求条件一致，不要同时修改上下文长度、并发限制或显存参数，否则无法判断变化来自哪项配置。
显存与并发参数
资源参数以 vllm serve 命令行参考 为准，启动前需要逐项确认：
--max-model-len覆盖 prompt 与 output；未设置时从模型配置推导。--gpu-memory-utilization是当前实例使用的 GPU 显存比例，默认值为0.92。--kv-cache-memory-bytes直接设置每张 GPU 的 KV cache 大小；设置后，--gpu-memory-utilization不再决定这部分容量。--max-num-seqs和--max-num-batched-tokens分别限制单次迭代处理的序列数和 token 数。
可按实际需求把占位符加入启动命令：
--max-model-len YOUR_VALUE
--gpu-memory-utilization YOUR_VALUE
--max-num-seqs YOUR_VALUE
--max-num-batched-tokens YOUR_VALUE
不要照抄其他机器的参数。先固定业务上下文和并发边界，再比较是否启用推测解码；否则模型容量、KV cache 和请求规模会同时干扰结果。
如何检查是否值得启用
验证时按 Benchmark CLI 文档 使用 vllm bench serve 指向运行中的服务，并记录以下口径：
- 报告包含 request throughput、output-token throughput 和 total-token throughput。
- TTFT 从客户端发出请求，计算到收到第一个 streamed output。
- ITL 记录相邻 streamed output 之间的间隔；TPOT 按请求计算，并排除首 token。
- 推测解码时，一个 streamed output 可能包含多个 token，因此 ITL 与 TPOT 可能分离。
--request-rate控制每秒请求数，默认值inf会立即发送全部请求；受控测试应填写自己的负载值。--max-concurrency可以限制尚未完成的请求。- 对同一服务重复运行基准测试可能命中 prefix cache，并抬高吞吐结果。
可使用文档中的在线端点执行 ShareGPT 测试：
vllm bench serve \
--backend vllm \
--model YOUR_VALUE \
--endpoint /v1/completions \
--dataset-name sharegpt \
--request-rate YOUR_VALUE \
--max-concurrency YOUR_VALUE
YOUR_VALUE 中的模型应与服务实际加载的模型一致，负载参数则应来自自己的业务要求，不要为了得到更好看的结果而任意放宽并发。
常见出错点
最常见的问题是把“服务能够启动”直接等同于“配置有收益”。做启用与停用对照时，只改变推测解码配置；比较不同方法时，再单独更换 speculative_config，其余条件保持一致。
不要混用旧式独立参数和新的 JSON，也不要在同一次试验中同时修改 APC、上下文长度、显存比例与并发限制。重复运行产生的结果应与独立对照分开记录，避免把缓存影响误认为配置收益。
判断收益时同时查看吞吐、TTFT、ITL 和 TPOT，不要只凭单一指标下结论；发现结果变差时，也应先核对请求前缀、输出长度和负载分布，再决定是否保留该配置。
本文步骤均按文中链接的官方文档整理，未运行或测量；使用前应对照当前版本复核。