# PR #21840 完整报告

- 仓库：`sgl-project/sglang`
- 标题：scheduler: add prefill-only update in merge batch
- 合并时间：2026-04-02 14:33
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/21840

---

# 执行摘要
本次 PR 修复了调度器在合并批次时未正确更新 `is_prefill_only` 标志的问题，该缺陷会导致特定场景下调度器错误跳过解码步骤、触发内存泄漏检查。变更仅涉及一行代码，风险较低，但 review 中指出了 `filter_batch` 方法中潜在的状态一致性问题未解决。

# 功能与动机
**问题背景**：当仅预填充批次（如 `max_new_tokens=0` 的 logprob 请求）先被合并到运行批次时，`running_batch.is_prefill_only` 被设为 `True`；随后若正常生成批次通过 `merge_batch()` 合并到同一批次，该标志因 `merge_batch` 从未更新而保持 `True`。这导致调度器错误跳过解码步骤、返回 `None` 并虚假进入空闲路径——触发内存泄漏检查，而 KV 缓存仍为活跃请求分配。

**引用 PR body 关键表述**：
> "introduced in: https://github.com/sgl-project/sglang/pull/14320"

# 实现拆解
变更集中在调度器批次管理模块：
- **文件**：`python/sglang/srt/managers/schedule_batch.py`
- **方法**：`merge_batch`
- **关键改动**：在方法末尾添加一行代码：
  ```python
  self.is_prefill_only = self.is_prefill_only and other.is_prefill_only
  ```
 确保合并两个批次时，`is_prefill_only` 标志仅当两个批次均为 prefill-only 时才保持 `True`。

# 评论区精华
review 中 gemini-code-assist[bot] 提出两点有价值建议：
1. **代码风格一致性**：
 > "Consider using the `&=` operator for consistency with the other boolean flag updates in this method (lines 2265-2268)."
 建议使用 `&=` 运算符以保持与同方法中 `has_stream`、`has_grammar` 等布尔标志更新模式一致。

2. **状态一致性风险**：
 > "the `is_prefill_only` flag (and potentially `return_hidden_states`) should be re-evaluated in the `filter_batch` method... Currently, `filter_batch` re-evaluates flags like `has_stream` and `has_grammar` but omits `is_prefill_only`, which could lead to stale state..."
 指出 `filter_batch` 方法中未重新评估 `is_prefill_only` 标志，若从混合批次中过滤掉生成请求，可能导致调度器状态过时。

讨论未显示这些建议是否被采纳，但 PR 已获批准合并。

# 风险与影响
**风险**：
- 核心风险在于 `filter_batch` 中未重新评估 `is_prefill_only`，可能导致过滤操作后标志状态不一致，引发调度行为错误。
- 变更虽小，但缺少针对此修复的单元测试，无法验证边缘场景（如混合批次过滤）。

**影响**：
- 修复了特定场景下的内存泄漏问题，提升系统稳定性。
- 仅影响调度器内部批次合并逻辑，对用户透明，无性能开销或兼容性变更。
- 团队需关注 `filter_batch` 中潜在的状态一致性问题，可能需后续 PR 解决。

# 关联脉络
- **历史 PR 关联**：PR body 指出问题最初在 PR #14320 中引入（提供的近期历史 PR 列表中无此编号，推测为更早的 PR），本次修复针对该引入点。
- **演进趋势**：近期 PR 如 #21225（移除 Ngram 窗口参数）、#20501（融合温度与 softmax 内核）显示调度器和内核优化是持续重点，本次修复属于调度器状态机正确性维护的一部分。