执行摘要

• 一句话：集中 seq_lens_cpu/sum 维护到单一辅助方法
• 推荐动作：合并后建议执行 PR body 中的 test plan。此 PR 的设计决策（延迟计算 + 统一同步点）值得在类似状态维护中借鉴。

功能与动机

消除 seq_lens_cpu 和 seq_lens_sum 在多处分散维护的重复和潜在不一致（如 spec v2 重叠模式下快照/恢复导致过时值），为未来优化提供一个集中、可控的同步点。

实现拆解

1. 新增 refresh_seq_lens_cpu 方法（schedule_batch.py）：带 sync 参数，sync=True 且 is_spec_v2 时执行 D2H 同步，否则仅基于 seq_lens_cpu 重算和。
2. 修改生产者（schedule_batch.py 的 prepare_for_decode、filter_batch、merge_batch；eagle_info_v2.py 的 prepare_for_decode 和 prepare_for_extend_to_fill_draft_kvcache）：移除内联求和及显式 .cpu() 调用，改为设 seq_lens_sum = None 或调用辅助方法（sync=False 当 CPU 副本已最新）。
3. 添加延迟刷新点（forward_batch_info.py 的 init_new）：构建 ForwardBatch 时若 seq_lens_sum is None，调用 refresh_seq_lens_cpu(sync=False) 确保非重叠路径获正确值。
4. 设置核心同步点（scheduler.py 的 run_batch）：重叠解码路径中，进入 _overlap_forward_isolation 前调用 batch.refresh_seq_lens_cpu()，确保快照捕获最新 GPU 值。

关键文件：

• python/sglang/srt/managers/schedule_batch.py（模块 调度层；类别 source；类型 core-logic；符号 refresh_seq_lens_cpu）: 核心变更文件：新增 refresh_seq_lens_cpu 方法，修改 prepare_for_decode、filter_batch、merge_batch 为延迟计算 seq_lens_sum。
• python/sglang/srt/speculative/eagle_info_v2.py（模块 推测解码；类别 source；类型 core-logic）: 移除 prepare_for_decode 中的内联 D2H 求和操作，改为调用统一方法。
• python/sglang/srt/model_executor/forward_batch_info.py（模块 前向批处理；类别 source；类型 data-contract）: 添加惰性刷新点：构建 ForwardBatch 时若 seq_lens_sum 为 None 则自动刷新。
• python/sglang/srt/managers/scheduler.py（模块 调度器；类别 source；类型 core-logic）: 在重叠解码前添加刷新调用，确保快照捕获最新值。

关键符号：refresh_seq_lens_cpu, prepare_for_decode, filter_batch, merge_batch, prepare_for_extend_to_fill_draft_kvcache, prepare_for_v2_verify, init_new

关键源码片段

python/sglang/srt/managers/schedule_batch.py

核心变更文件：新增 refresh_seq_lens_cpu 方法，修改 prepare_for_decode、filter_batch、merge_batch 为延迟计算 seq_lens_sum。

# python/sglang/srt/managers/schedule_batch.py
​
class ScheduleBatch:
    # ...
​
    def refresh_seq_lens_cpu(self, sync: bool = True):
        # sync=True 时，从 GPU 复制 seq_lens 到 CPU（spec v2 需要避免过时）
        # sync=False 时，仅基于现有的 seq_lens_cpu 重新计算和
        if sync and self.is_spec_v2:
            self.seq_lens_cpu = self.seq_lens.cpu()
        self.seq_lens_sum = int(self.seq_lens_cpu.sum())
​
    def prepare_for_decode(self):
        # ... 原有 seq_lens 增加逻辑 ...
        # 原内联求和 self.seq_lens_sum += bs
        self.seq_lens_sum = None # 延迟到实际需要时计算
​
    def filter_batch(self, ...):
        # ... 原有过滤 ...
        # 原内联求和 self.seq_lens_sum = self.seq_lens.sum().item()
        self.seq_lens_sum = None
​
    def merge_batch(self, other):
        # ... 原有合并 ...
        # 原内联求和 self.seq_lens_sum += other.seq_lens_sum
        self.seq_lens_sum = None

python/sglang/srt/managers/scheduler.py

在重叠解码前添加刷新调用，确保快照捕获最新值。

# python/sglang/srt/managers/scheduler.py
​
def run_batch(self, batch, ...):
    # ...
    if self.is_generation:
        if self.enable_overlap:
            # 刷新 seq_lens_cpu 和 sum，确保快照抓取最新值
            batch.refresh_seq_lens_cpu()
​
            with self._overlap_forward_isolation(batch):
                # ... 前向逻辑 ...

评论区精华

此 PR 仅有自动化配额提示，无技术讨论。

• 暂无高价值评论线程

风险与影响

• 风险：若 refresh_seq_lens_cpu 被遗漏调用或 sync 参数错误（如应 sync 却传 False），会导致 seq_lens_sum 为 None，进而触发 TypeError 或 KV 缓存分配错误。非 spec v2 重叠解码路径的 sync=False 假设 seq_lens_cpu 已最新，若后续新增修改点打破该假设，可能使用过期数据。无专用测试文件，回归风险依赖集成测试。
• 影响：用户：无直接可见变化，但减少了潜在 bug（如 #24070 类似的清理问题）。系统：性能上减少不必要的 seq_lens.cpu() 调用，但对实际吞吐影响很小。团队：更清晰的结构，降低新生产者忘记更新 sum 的可能性。
• 风险标记：核心路径变更, 缺少测试覆盖

关联脉络

• 暂无明显关联 PR