jetson-speculative-decoding

Jetson 推测解码（vLLM）

推测解码让较小的“草稿”模型提出 token，再由目标模型通过一次前向传递进行验证，从而降低每个 token 的延迟。在 Jetson 上，收益与损失主要取决于显存余量，而非草稿质量。这项技能记录了 LLM 不会预先了解的部分。

目的

通过追加合适的 --speculative-config 并验证其是否能提升单流解码速度，调优现有 Jetson vLLM 部署。

适用情况

• TPOT/ITL 是瓶颈（TTFT 正常，只是输出较慢）。
• 工作负载为单流或低并发（≤2）。高并发时，推测解码通常得不偿失。
• Jetson 系列为 Thor 或 AGX Orin。不要在 Orin Nano/NX 上建议使用 EAGLE-3——通常没有足够的显存余量来同时运行目标模型和草稿模型，启动时会发生 OOM。

不适用情况

• 高并发服务（≥8）：批量解码通常胜过推测解码；草稿模型只会占用显存。
• 没有已发布 EAGLE-3 head 的模型——不要临时训练一个来“解决”问题。
• 已应用 jetson-inference-mem-tune 标志，且 --gpu-memory-utilization 已接近上限。请先至少释放约 2 GB 显存。

前置条件

• 已有可用的 jetson-llm-serve vLLM 服务配置。
• 除目标模型外，还需有足够的显存余量容纳草稿模型或 EAGLE-3 head。
• 启用推测解码前，已使用 jetson-llm-benchmark 获取基准数据。
• 目标模型具有兼容的 EAGLE-3 head，或有一个同系列的小型草稿模型可用于回退方案。

操作说明

在 jetson-llm-serve 中展示的 vllm serve 命令后追加 --speculative-config。

EAGLE-3（目标模型已发布对应 head 时优先使用）：

--speculative-config '{
  "method": "eagle3",
  "model": "<eagle3-head-repo-id>",
  "num_speculative_tokens": 5,
  "draft_tensor_parallel_size": 1
}'

草稿模型（回退方案——搭配同系列的小型模型）：

--speculative-config '{
  "method": "draft_model",
  "model": "<small-draft-model-repo-id>",
  "num_speculative_tokens": 4,
  "draft_tensor_parallel_size": 1
}'

Jetson 专属调优规则

• num_speculative_tokens：Thor 从 5 开始，AGX Orin 从 3 开始。只有在草稿接受率 >0.6 时，较高的值才会带来收益。
• 始终搭配 jetson-llm-serve 使用的同一 vLLM 运行时路径：Thor 使用上游 vLLM 0.20+（vllm/vllm-openai:latest）或经过验证的原生 vLLM 0.20+；Orin JetPack 7.2 / L4T r39+ 使用上游 vLLM 0.20+；较旧的 Orin 使用 NVIDIA-AI-IOT vLLM 镜像。不要在 Thor 上使用 Orin NVIDIA-AI-IOT vLLM 镜像。较旧的运行时可能不支持 EAGLE-3 或当前的 --speculative-config 格式。
• 与非推测解码基准相比，将 --gpu-memory-utilization 降低约 0.05，为草稿模型留出显存余量。

如何验证是否确实有效

1. 在启用推测解码前后，使用 jetson-llm-benchmark（vLLM 路径）并设置 --concurrency 1 运行测试。
2. 验收标准：并发数为 1 时，throughput_tok_s 至少提升 30%，且 tpot_ms_p50 至少下降 20%。
3. 如果提升 <10%，或并发数为 8 时 throughput_tok_s 下降，请禁用推测解码。草稿模型带来的成本高于收益。

局限性

• 推测解码可改善以解码为主的工作负载；它不会降低以 TTFT 为主的延迟。
• 高并发可能抵消其收益，因为连续批处理本已能让 GPU 保持繁忙。
• Orin Nano/NX 通常没有足够的显存余量来同时容纳目标模型和草稿模型。
• 接受率和草稿开销因模型而异，因此应在启用前后进行基准测试，而不要假定一定能提速。

错误处理

• 如果 vLLM 拒绝 --speculative-config，请确认 Thor 和 Orin JetPack 7.2 / L4T r39+ 使用的是 vLLM 0.20+，且较旧的 Orin 使用的是与 JetPack 匹配的 NVIDIA-AI-IOT vLLM 镜像；如果运行时仍拒绝该配置，则切回非推测解码服务命令。
• 如果启动时发生 OOM，请降低 --gpu-memory-utilization、使用更小的草稿模型，或禁用推测解码并转交给 jetson-inference-mem-tune。
• 如果基准测试的吞吐量下降，请移除 --speculative-config；不合适的草稿方案还不如不用推测解码。

交接给

• 使用 jetson-llm-benchmark 量化变化。
• 如果启用推测解码后启动时发生 OOM，请使用 jetson-inference-mem-tune。

来源

vLLM 推测解码文档和 Jetson AI Lab GenAI 教程。