# PR #21910 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Fix ngram doc for speculative_num_draft_tokens default
- 合并时间：2026-04-02 13:18
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/21910

---

# 执行摘要

本次 PR 修正了 ngram 推测解码文档中关于 `--speculative-num-draft-tokens` 参数默认值的错误描述。原文档错误地声称该参数默认值与 `--speculative-ngram-max-trie-depth` 参数相关，但实际上代码中硬编码为 `12`，且这两个参数功能正交。此变更仅涉及文档更新，无代码逻辑改动，风险极低但有助于提升文档准确性。

# 功能与动机

文档中关于 ngram 推测解码的参数描述存在错误：
- 原文档声称：`--speculative-num-draft-tokens` 参数的默认值是 `min(--speculative-ngram-max-trie-depth, 12)`
- 实际代码实现：该参数默认值硬编码为 `12`，且与 `--speculative-ngram-max-trie-depth` 参数功能正交（前者控制每步验证的草稿令牌数量，后者控制后缀匹配长度）

此修正旨在使文档描述与代码实现保持一致，避免用户在使用推测解码功能时产生误解。

# 实现拆解

仅修改一个文档文件：

**文件：`docs/advanced_features/speculative_decoding.md`**

| 行号 | 原内容 | 新内容 | 说明 |
|------|--------|--------|------|
| ~387 | `If omitted, defaults to min(--speculative-ngram-max-trie-depth, 12).` | （空） | 移除错误的默认值依赖描述 |
| ~387 | `12 (with default ngram settings)` | `12` | 简化默认值显示，直接显示硬编码值 |

变更后参数表格更清晰：
```markdown
| Parameter | Description | Default |
|---|---|---|
| `--speculative-num-draft-tokens` | Number of draft tokens verified per step. | `12` |
| `--speculative-ngram-min-bfs-breadth` | Minimum BFS breadth. | `1` |
| `--speculative-ngram-max-bfs-breadth` | Maximum BFS breadth. | `10` |
```

# 评论区精华

该 PR 未产生任何 review 评论或讨论，由作者 hnyls2002 直接合并。考虑到变更仅涉及 1 行文档修正，且内容明确（修正错误描述），这种处理方式是合理的。

# 风险与影响

**风险分析：**

- 无回归风险：仅修改文档，不涉及代码逻辑
- 无性能影响：纯文档更新，不影响系统运行时
- 无安全风险：不修改安全相关代码或配置
- 无兼容性问题：文档修正不会破坏向后兼容性

**影响分析：**

1. **对用户的影响**：修正了文档中的错误信息，避免用户在使用 ngram 推测解码功能时对参数默认值产生误解。特别是原文档中关于两个参数存在依赖关系的错误描述可能误导用户配置。
2. **对系统的影响**：无任何运行时影响，系统行为完全不变。
3. **对团队的影响**：维护了文档的准确性，有助于后续开发和用户支持工作，体现了对文档质量的重视。

# 关联脉络

从近期历史 PR 分析来看，该 PR 与以下趋势相关：

1. **文档维护常态化**：类似 PR #21463（迁移 API 端点文档）也涉及文档更新，表明团队持续维护文档准确性。
2. **推测解码功能演进**：标签 `speculative-decoding` 在仓库中已有使用，本次修正针对该功能的文档细节，属于功能完善的一部分。
3. **小范围修正模式**：与 PR #21884（移除 HiRadixCache 硬钉功能）等涉及代码重构的 PR 不同，本次变更属于典型的文档小修正，通常由发现问题的贡献者直接提交并合并。

虽然该 PR 本身改动很小，但反映了团队对文档准确性的重视，特别是在复杂功能（如推测解码）的参数说明上确保与代码实现一致。