执行摘要

• 一句话：修复流式会话中推测解码超限导致KV缓存错误的bug。
• 推荐动作：值得精读，特别是_trim_overshoot和_free_kv_aligned的设计，展示了如何处理页面对齐释放和状态修剪，对理解流式会话缓存管理有参考价值。

功能与动机

PR body指出，推测解码每轮接受多个令牌，当请求完成时，可能超过max_new_tokens边界，超限令牌进入KV缓存，导致下一个回合的token/KV不匹配，引发注意力错误。必须修剪KV状态以避免此问题，确保流式会话的正确性。

实现拆解

1. 入口点修改：在cache_finished_req方法中计算finished_len并调用_trim_overshoot。
2. 核心修剪逻辑：新增_trim_overshoot方法，计算目标位置target = origin + finished_len，使用_free_kv_aligned释放超限KV，并更新kv_allocated_len、kv_committed_len和output_ids。
3. KV释放辅助函数：新增_free_kv_aligned方法，处理页面对齐的KV释放，避免部分页面释放损坏已提交令牌。
4. 重构现有逻辑：修改_free_tail方法使用_free_kv_aligned，统一释放逻辑，提高代码可维护性。

关键文件：

• python/sglang/srt/mem_cache/session_aware_cache.py（模块 会话缓存；类别 source；类型 core-logic；符号 _trim_overshoot, _free_kv_aligned）: 核心缓存管理文件，修复流式会话中超限问题，涉及关键状态修剪和KV释放逻辑。

关键符号：cache_finished_req, _trim_overshoot, _free_kv_aligned, _free_tail

评论区精华

review评论指出_trim_overshoot方法缺少对req.swa_evicted_seqlen的更新，这可能导致滑动窗口注意力（SWA）状态不一致。此问题在后续PR #22900中得到修复，体现了设计权衡和状态管理的重要性。

• 缺失swa_evicted_seqlen更新 (correctness): 后续PR #22900修复了此问题，添加了swa_evicted_seqlen的更新。

风险与影响

• 风险：风险包括：
  1) 回归风险：修改核心缓存路径可能影响其他会话逻辑，需测试覆盖；
  2) 性能影响：新增页面对齐释放可能增加微小开销，但避免了内存泄漏；
  3) 兼容性：仅影响使用推测解码的流式会话，其他路径不受影响；
  4) 状态一致性：未更新swa_evicted_seqlen可能导致SWA泄漏，但已在#22900修复。
  • 影响：对用户：修复流式会话中推测解码的正确性，避免输出错误，提升用户体验。对系统：确保KV缓存与令牌一致，提高系统可靠性和内存管理效率。对团队：通过重构释放逻辑，减少代码重复，便于未来维护和扩展。
  • 风险标记：核心路径变更, 状态一致性风险

关联脉络

• PR #22900 trim_overshoot: cap swa_evicted_seqlen + unit test: 修复本PR中缺失的swa_evicted_seqlen更新，并提供单元测试，是直接后续补丁。
• PR #22862 Streaming session: fix retract tail leak via _free_tail: 同为流式会话正确性修复，涉及类似KV泄漏问题，共享_free_kv_aligned逻辑。
• PR #22651 streaming session: spec v2 bonus accounting + comprehensive test matrix: 总览PR，链接到本PR作为流式会话正确性工作的一部分，提供上下文和测试覆盖。