# PR #51611 完整报告

- 仓库：`vllm-project/vllm`
- 标题：[Doc] Fix stale rejection_sample_method and synthetic_acceptance_rate
- 合并时间：2026-08-13 18:56
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/51611

---

# 执行摘要

- 一句话：同步 speculative decoding README 配置表格
- 推荐动作：值得快速浏览：这是文档与代码同步的典型示例，可学习作者如何评估 stale PR、选择最小修复范围以及处理合并冲突。对关注文档质量的贡献者有参考价值；代码层面无需精读。

# 功能与动机

关联 Issue #51609 指出 `--speculative-config` 表格与代码脱节：`rejection_sample_method` 文档值 `strict, probabilistic, synthetic` 已过时（#40651 将其改为 `standard, synthetic, block`），`synthetic_acceptance_rate` 已拆分（#40662）。用户按文档传参会触发 `ValidationError`。PR 作者选择了对现有表格做最小修复，而非复用 stale 的 #37383，避免引入更多错误信息。

# 实现拆解

1. **定位目标表格**：修改 `docs/features/speculative_decoding/README.md` 第 86-88 行的 `--speculative-config` 表格，该表格列出 speculative decoding 相关配置参数。
2. **更新 `rejection_sample_method` 行**：将取值从 `strict, probabilistic, synthetic`（默认 `strict`）改为 `standard, synthetic, block`（默认 `standard`），并向读者说明 `probabilistic` 已归入 `draft_sample_method` 维度。
3. **拆分 `synthetic_acceptance_rate`**：替换为 `synthetic_acceptance_rates`（`list[float]`，非递增且长度需等于 `num_speculative_tokens`）和 `synthetic_acceptance_length`（`float`，取值 `[1, num_speculative_tokens + 1]`），并注明两者互斥。
4. **冲突处理与验证**：rebase 到最新 `main` 解决与 #51500 的相邻行冲突；触发 CI Buildkite #83722 运行 markdownlint，由 CI 验证文档格式。
5. **配套说明**：纯文档变更，无代码、测试或配置改动；作者说明本地无 Python 环境，依赖 CI 检查。

关键文件：
- `docs/features/speculative_decoding/README.md`（模块 文档；类别 docs；类型 documentation）: 本 PR 唯一修改文件，修正 --speculative-config 表格两行过时说明，直接解决用户按文档传参报错问题。

关键符号：未识别


# 评论区精华

核心讨论集中在合并冲突处理和方案取舍上：
- mergify 机器人先提示合并冲突；作者 `qwerqwerqwe8688-jpg` 评论表示已 rebase 并解决与 #51500 的冲突，邀请维护者 `hmellor` 查看。
- PR body 解释为何不基于 stale 的 #37383 重写大段文档：该 PR 已过时且记录了不存在的 `speculative_token_tree` 键，采用最小修复更安全。
- `hmellor` 触发 CI 并最终批准合并，无未解决的疑虑。

- 合并冲突处理与 rebase (other): 作者 rebase 后冲突解决，维护者 hmellor 触发 CI 并批准合并。
- 为何不复制 stale PR #37383 而采用最小修复 (design): 采用最小修复方案，避免引入更多错误。

# 风险与影响

- 风险：风险极低，但仍存在两类：
 1. **文档漂移风险**：`vllm/config/speculative.py` 的配置字段未来若再次演进，本次修正仍可能过时；Issue #51609 已明确列出代码位置（`speculative.py:79, 218`）便于后续同步。
 2. **验证盲区**：作者本地无 Python 环境，未实际运行 markdownlint，依赖 CI 结果；若 CI 未覆盖该文件，格式问题可能未被发现。实际 CI Buildkite #83722 已通过。
 - 影响：面向文档读者：修复了用户按 README 配置 speculative decoding 时因参数名 / 取值过期而启动失败的问题，影响面覆盖所有查阅此文档的开发者。对系统代码零影响。维护成本低，但要求未来配置变更时同步更新此表（已有 Issue 跟踪机制）。
 - 风险标记：纯文档变更 , 依赖 CI 校验 markdownlint, 文档可能随配置演进再次漂移

# 关联脉络

- PR #51256 [BugFix] Reserve the bonus query slot in DFlash scheduling budget: 该 PR 修改了 vllm/config/speculative.py，与本 PR 文档落点的配置字段同源，但功能无关；可作为配置语义演进的参考。