# PR #21589 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[sgl] two potential spec_v2 bug fixes
- 合并时间：2026-04-06 10:41
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/21589

---

# 执行摘要
本 PR 修复了 Speculative Decoding V2 中导致 Eagle3 模型崩溃的两个潜在 bug：1）在 eagle_worker_v2.py 中补充设置 forward_batch.return_logprob = False 以保持与 V1 行为一致；2）在 logits_processor.py 中修复 aux_pruned_states 未填充的问题。这些修复提升了推测解码 V2 路径的稳定性和正确性，影响范围有限但关键，建议合并后关注相关测试结果。

# 功能与动机
根据 PR body，当 Eagle3 模型启用 SGLANG_ENABLE_SPEC_V2 时发生崩溃。作者识别出两个问题：
- forward_batch.return_logprob = False 在 eagle_worker.py（V1）中已设置，但在 V2 版本中遗漏，可能导致参数不一致。
- aux_pruned_states 在 logits_processor.py 的某些条件下未填充，引用作者原话："aux_pruned_states is not populated, it's populated in previous two conditions, but not for the condition we fixed."

# 实现拆解
## 1. eagle_worker_v2.py 修改
在 `_draft_extend_for_prefill` 函数中添加一行代码：
```python
forward_batch.return_logprob = False
```
这确保了与 V1 行为一致，避免因 logprob 返回设置导致的潜在问题。

## 2. logits_processor.py 修改
在 `_get_pruned_states` 函数中新增逻辑：
- 初始化 `aux_pruned_states_lists`：如果 `aux_hidden_states` 不为 None，则为每个隐藏状态创建空列表。
- 在循环中填充：如果 `aux_pruned_states_lists` 不为 None，遍历 `aux_hidden_states` 并切片添加到对应列表。
- 最终拼接：如果 `aux_pruned_states_lists` 不为 None，将列表拼接为 `aux_pruned_states`。
关键代码片段：
```python
aux_pruned_states_lists = (
    [[] for _ in aux_hidden_states]
    if aux_hidden_states is not None
    else None
)
...
if aux_pruned_states_lists is not None:
    for j, hidden in enumerate(aux_hidden_states):
        aux_pruned_states_lists[j].append(
            hidden[pt + start_len : pt + extend_len]
        )
...
if aux_pruned_states_lists is not None:
    aux_pruned_states = [torch.cat(lst) for lst in aux_pruned_states_lists]
```

# 评论区精华
Review 讨论较少，只有 Qiaolin-Yu 的批准，没有具体技术交锋。从提交历史看，有一个合并主分支的提交（SHA: bad6521），可能涉及冲突解决，但未提供详细讨论。

# 风险与影响
## 风险
- **核心路径变更**：logits_processor.py 的修改涉及推测解码的核心逻辑，虽然修复了 bug，但需确保不影响其他使用场景。
- **性能开销**：aux_pruned_states 的填充增加了列表操作和拼接，但通过条件检查（`if aux_hidden_states is not None`）避免了不必要的计算。
- **测试覆盖**：缺少针对这两个修复的专项测试，依赖现有 CI 测试（已通过 run-ci 标签触发）。

## 影响
- **用户影响**：直接修复 Eagle3 模型在 SpecV2 下的崩溃，提升用户体验。
- **系统影响**：确保推测解码 V2 路径的状态一致性，避免运行时错误。
- **团队影响**：维护了 V1/V2 行为一致性，减少后续开发混淆。

# 关联脉络
与近期 PR 的关联：
- PR#22146（隔离 Spec V1 路径）：同属推测解码相关修改，本 PR 修复 V2 bug，可能补充了 V2 路径的完整性。
- PR#22104（重新启用 SpecV2 测试）：本 PR 的 bug 修复可能影响此类测试的稳定性，建议合并后验证测试结果。
从历史 PR 看，推测解码（speculative-decoding）是近期活跃模块，本 PR 是其中重要的 bugfix，有助于提升该功能的鲁棒性。