# PR #22049 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[Speculative] Support penalty for spec v2 overlap scheduling
- 合并时间：2026-04-09 16:59
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/22049

---

# 执行摘要
此 PR 为 spec v2 重叠调度新增了惩罚参数（如频率惩罚、存在惩罚）支持，解决了之前验证阶段忽略这些参数导致输出质量偏差的问题。通过核心逻辑文件修改和测试验证，确保了推测解码功能完整性，是 spec v2 功能演进的关键一步。

# 功能与动机
动机源自 issue #11762，该 issue 列出了 spec v2 重叠调度的功能优化项，其中一项为“penalty support”。PR body 明确说明，此前 spec v2 在验证时忽略了 `frequency_penalty`、`presence_penalty`、`repetition_penalty` 和 `logit_bias`，导致输出未被惩罚。关闭此项以提升输出质量和一致性。

# 实现拆解
实现主要包括两个文件修改：
- **python/sglang/srt/speculative/eagle_info_v2.py**：
 - 在 `prepare_for_decode` 函数中，添加惩罚状态累积逻辑，通过 `penalizer_orchestrator.cumulate_output_tokens` 更新计数器，但 review 指出应累积所有新接受 token。
 - 在 `sample` 函数中，应用惩罚到验证 logits，代码示例如下：
    ```python
    if sampling_info.acc_additive_penalties is not None:
        next_token_logits.add_(
            torch.repeat_interleave(
                sampling_info.acc_additive_penalties, self.draft_token_num, dim=0
            )
        )
    ```
 类似处理缩放惩罚和 logit 偏置。

- **test/registered/spec/eagle/test_eagle_infer_beta.py**：
 - 新增 `test_penalty()` 函数，使用并发请求测试多种惩罚组合（如 `frequency_penalty=2`、`presence_penalty=1`），并验证服务器响应。

# 评论区精华
review 评论由 gemini-code-assist[bot] 提出，核心交锋点包括：
- **惩罚累积逻辑**：> “In speculative decoding, multiple tokens can be accepted in a single verify round. This logic only accumulates the last accepted token...” 指出当前实现只累积最后一个 token，可能导致计数器不准确。
- **属性名错误**：> “acc_linear_penalties does not exist in SamplingBatchInfo. It should be acc_additive_penalties...” 强调属性名错误会引发运行时异常。
提交历史显示有 'fix' 提交，可能已解决这些问题，但未提供讨论细节。

# 风险与影响
**风险**：
- 惩罚累积不完整可能影响频率 / 存在惩罚的准确性，导致输出偏差。
- 属性名错误风险可能导致运行时 AttributeError，影响系统稳定性。
- 惩罚应用引入额外计算，可能轻微增加推理延迟。
**影响**：
- 对用户：spec v2 推理现在能正确应用惩罚参数，提升输出预期性。
- 对系统：增强功能完整性，为后续 speculative 解码优化奠定基础。
- 对团队：促进 spec v2 功能演进，与 issue #11762 中的其他项协同推进。

# 关联脉络
此 PR 与 issue #11762 直接相关，该 issue 概述了 spec v2 重叠调度的多个功能项。从历史 PR 看，PR #22294（ngram 推测解码增强）和 PR #22230（EAGLE3 支持 Qwen3-VL）都涉及推测解码功能，显示团队在此领域的持续投入。通过此 PR，penalty 支持项得到实现，有助于完善 spec v2 的整体功能矩阵。