执行摘要

• 一句话：澄清 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