# PR #40455 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Doc] Clarify supported keys for --speculative-config
- 合并时间：2026-04-22 19:36
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/40455

---

# 执行摘要

- 一句话：澄清 speculative decoding 中 --speculative-config 参数的文档，添加键值说明和示例。
- 推荐动作：对于使用 speculative decoding 的工程师和用户，此 PR 值得浏览以了解正确配置选项；关注设计决策如 CLI 命名约定和文档结构，但无需深入代码分析。

# 功能与动机

修复 issue #35573，该 issue 指出 `--speculative-config` 选项缺乏清晰的键和值文档，导致用户猜测语法、遇到解析错误或静默失败，阻碍了 speculative decoding 的采用。PR body 明确目标是澄清用户面向的选项，无行为变更。

# 实现拆解

1. **添加核心 schema 部分**：在 `docs/features/speculative_decoding/README.md` 中新增 `## --speculative-config schema` 节，包含常见键（如 `method`、`model`、`num_speculative_tokens`）和方法特定键（如 N-gram 的 `prompt_lookup_min`/`max`）的表格，说明类型、默认值和含义。
2. **更新 CLI 示例标准化**：修改 `draft_model.md`、`parallel_draft_model.md`、`mtp.md` 中的示例，将 `--speculative_config` 统一为 `--speculative-config`，并调整其他参数如 `--max_model_len` 为 `--max-model-len` 以保持连字符风格一致性。
3. **添加引用和澄清**：在 schema 部分引用 engine arguments 文档和 `vllm.config.SpeculativeConfig` API，明确采样参数（如 `temperature`）不属于 `--speculative-config`，并说明表格非 exhaustive。
4. **配套文档调整**：仅文档文件变更，无测试、配置或代码改动，确保用户文档准确性和可读性。

关键文件：
- `docs/features/speculative_decoding/README.md`（模块 文档；类别 docs；类型 documentation）: 添加了核心的 --speculative-config schema 部分，包括常见键和方法特定键的表格，是文档更新的主要入口。
- `docs/features/speculative_decoding/draft_model.md`（模块 文档；类别 docs；类型 documentation）: 更新 CLI 示例，标准化参数命名并添加 schema 引用，影响用户实际操作。
- `docs/features/speculative_decoding/parallel_draft_model.md`（模块 文档；类别 docs；类型 documentation）: 类似更新 CLI 示例，确保命名一致性，是配套文档调整。
- `docs/features/speculative_decoding/mtp.md`（模块 文档；类别 docs；类型 documentation）: 最小化更新 CLI 示例，保持文档整体一致性。

关键符号：未识别


# 评论区精华

review 中重点讨论了文档准确性和一致性：
- **准确性争议**：gemini-code-assist[bot] 指出 N-gram 默认值（`prompt_lookup_min` 默认应为 `prompt_lookup_max` 而非 1）与代码实现不匹配，作者更新以纠正。
- **命名一致性**：DarkLight1337 提到 CLI 参数应统一使用连字符风格，作者响应并修改了示例中的其他参数。
- **内容精简**：DarkLight1337 建议缩短 `method` 示例列表和表格，避免冗长，作者进行了修剪。
- **错误键澄清**：gemini-code-assist[bot] 指出 `tensor_parallel_size` 在 `speculative_config` 中无效，作者移除了相关误导说明。

 - N-gram 默认值准确性 (correctness): 作者更新文档以匹配代码实现，确保准确性。
- CLI 参数命名一致性 (design): 作者统一修改为连字符风格（如 `--max-model-len`），提升 CLI 一致性。
- 文档内容精简与引用 (documentation): 作者修剪了示例，并添加了到 engine arguments 和 `vllm.config.SpeculativeConfig` 的引用。

# 风险与影响

- 风险：风险较低，主要为文档误导风险：如果键值描述不准确（如默认值错误），可能导致用户配置错误，但 review 中已纠正。无代码变更，因此无回归、性能、安全或兼容性风险。
- 影响：对用户影响显著：改善 speculative decoding 配置的文档体验，减少猜测和错误，提升功能易用性。对系统无直接影响，不改变运行时行为。对团队而言，文档更清晰有助于后续维护和用户支持。
- 风险标记：文档误导风险

# 关联脉络

- 暂无明显关联 PR