执行摘要

• 一句话：修复 SWA 卸载中失效窗口内 pending 块误阻塞就绪前缀
• 推荐动作：值得精读 _sliding_window_lookup 的“状态作用域”设计：一个只应在当前有效窗口内生效的标志位，如何随窗口失效（MISS/RETRY）正确清除，是小而典型的调度状态机 bug，且修复只改 12 行源码。测试写法（先 mock 扫描器、再真实 manager 集成、同步/异步双参数化）也值得借鉴。对 KV offload / SWA 相关贡献者推荐阅读。

功能与动机

PR body 描述了具体症状：两 chunk 窗口 [HIT, HIT, MISS, HIT_PENDING] 当前返回 None——反向扫描在 miss 已经排除不完整后缀后仍保留 pending 标志，核心调度器因此对就绪前缀不提交任何加载，请求被无谓 defer。关联 issue #49829 指出 TieringOffloadingManager.lookup() 对 HIT_PENDING 无 deadline，慢写会持续 defer 请求直至客户端超时（实测 300 秒超时、单请求累积 127 万次 lookup）；本 PR 修复其中的 stale pending 标志子问题，并明确不声称修复 stalled write 本身。

实现拆解

1. 变更入口：vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py 的 _sliding_window_lookup 方法。这是 offloading connector 调度器为 SWA（滑动窗口）KV group 查找可用前缀窗口的核心路径，从 keys 尾部反向扫描，按 consecutive_hits 是否达到 required_window 决定返回窗口结束索引、0 或 None。
2. 核心改造：把原先单一 defer_lookup 语义拆分。新增 pending_in_window 状态，HIT_PENDING 只置位该状态并计为 hit；MISS 分支在清零 consecutive_hits 的同时置 pending_in_window = False，理由是缺口使右侧不完整窗口彻底失效；RETRY 分支同样重置 pending 但保留全局 defer_lookup（位置不确定，保守 defer）。返回值统一为“窗口命中且无 defer 无 pending 才返回索引，否则返回 None”。
3. 行为边界：窗口内真实存在的 pending 块仍会 defer（pending_in_window 为 True 时返回 None）；RETRY 的保守语义不受影响；非 SWA 路径 _maximal_lookup 未改动。
4. 测试配套：tests/v1/kv_connector/unit/offloading_connector/test_scheduler.py 新增两个回归用例。test_pending_chunk_behind_gap_does_not_defer 用 mock lookup 直测扫描器；test_swa_load_does_not_wait_for_unusable_pending_suffix 用真实 CPUOffloadingManager 构造 full 组前 4 块就绪、swa 组前 2 块就绪而第 4 块写挂起的场景，参数化 async_scheduling 走完整调度循环，验证 load.dst_spec.group_sizes == [2, 2] 与恢复后 num_scheduled_tokens == 9，并断言 pending 块仍保持 HIT_PENDING。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py（模块 卸载调度；类别 source；类型 core-logic；符号 _sliding_window_lookup）: 修复核心所在：_sliding_window_lookup 引入 pending_in_window 状态，将 HIT_PENDING 的 defer 语义限定在当前连续窗口内，MISS/RETRY 即清除，避免失效窗口的 pending 块反向阻塞就绪前缀的加载。
• tests/v1/kv_connector/unit/offloading_connector/test_scheduler.py（模块 卸载调度；类别 test；类型 test-coverage；符号 test_pending_chunk_behind_gap_does_not_defer, test_swa_load_does_not_wait_for_unusable_pending_suffix）: 新增两个回归测试：test_pending_chunk_behind_gap_does_not_defer 直测扫描器返回 2，test_swa_load_does_not_wait_for_unusable_pending_suffix 用真实 CPUOffloadingManager 验证同步/异步调度下就绪前缀被加载且 pending 块仍保持 HIT_PENDING。

关键符号：_sliding_window_lookup, test_pending_chunk_behind_gap_does_not_defer, test_swa_load_does_not_wait_for_unusable_pending_suffix

关键源码片段

vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py

修复核心所在：_sliding_window_lookup 引入 pending_in_window 状态，将 HIT_PENDING 的 defer 语义限定在当前连续窗口内，MISS/RETRY 即清除，避免失效窗口的 pending 块反向阻塞就绪前缀的加载。

def _sliding_window_lookup(
    self,
    keys: Sequence[OffloadKey],
    sliding_window_size: int,
    req_context: ReqContext,
    initial_window_size: int | None = None,
) -> int | None:
    """返回 keys 中最后一个满足窗口大小的连续命中窗口的结束索引。
​
    从尾部向前扫描；首个窗口可能因最右侧 chunk 不完整而需要更大的窗口。
    全部 miss 时返回 0，后端要求延后查询时返回 None。
    """
    defer_lookup = False # RETRY 引发的全局延后，不会因窗口失效而清除
    pending_in_window = False # 当前连续窗口内是否存在未落盘的 HIT_PENDING
    consecutive_hits = 0
    required_window = initial_window_size or sliding_window_size
    for idx in range(len(keys) - 1, -1, -1):
        match self.manager.lookup(keys[idx], req_context):
            case LookupResult.HIT:
                consecutive_hits += 1
            case LookupResult.HIT_PENDING:
                # 块在缓存中但尚未可读：计入连续命中，但标记窗口内存在 pending，
                # 命中窗口时仍需返回 None 延后加载，避免读到未就绪数据。
                pending_in_window = True
                consecutive_hits += 1
            case LookupResult.RETRY:
                # 位置不确定：不计数，且保留全局 defer；继续扫描以让 manager
                # 触发异步查询。RETRY 同样中断当前连续窗口。
                defer_lookup = True
                consecutive_hits = 0
                pending_in_window = False
                required_window = sliding_window_size
            case LookupResult.MISS:
                # 缺口使右侧未完成的窗口彻底失效：命中数与 pending 状态一并清除。
                # 位于缺口右侧的 pending chunk 无法再与左侧 HIT 组成连续窗口。
                consecutive_hits = 0
                pending_in_window = False
                required_window = sliding_window_size
        if consecutive_hits == required_window:
            return (
                None
                if defer_lookup or pending_in_window
                else idx + required_window
            )
    return None if defer_lookup or pending_in_window else consecutive_hits

评论区精华

作者在 PR body 中做了详尽的“非重复工作”论证：检查了 #49829 与 #53087 的讨论，检索了 _sliding_window_lookup、HIT_PENDING gap 等关键词，确认 #53087 处理有界等待、#53330 处理 P2P 供给需求覆盖、#51787 处理缓存新鲜度，本 PR 只修已失效滑动窗口上的 stale pending 标志，不触碰 stalled write 本身。

维护者 orozery 以 /ci run 触发 Buildkite CI #88819 并直接 approve；claude[bot] 提示 fork 来源 PR 的自动 review 被禁用。

作者披露 OpenAI Codex 参与调查、实现与测试执行，并给出本地验证（双 Layer Gemma2 哑权重、BF16、RTX 4060 Laptop、重载 32 个前缀 token、8 个生成 token 与参考一致），同时诚实标注这不是训练模型精度评估、真实 stalled-copy 实验或吞吐/TTFT 基准。

• 与 issue #49829 的边界界定 (question): 变更范围得到明确界定，与并行修复互补而非重复，维护者 accordingly approve。
• 测试设计：从扫描器单测到真实 manager 集成 (testing): 测试通过（249 passed，81.88 秒），覆盖单元与集成两层，行为被双边锁定。
• fork PR 的自动 review 与 CI 触发 (other): 未运行额外 bot review，由维护者直接批准并触发上游 CI。

风险与影响

• 风险：语义变更风险：_sliding_window_lookup 返回值直接决定调度器是否提交加载，若 pending_in_window 清除逻辑有误，可能提前加载未就绪 chunk 造成 cache miss 回退。代码顺序上该逻辑自洽：扫描从右向左，pending 一旦被更左侧的 MISS 清除，说明该 pending 位于缺口右侧，确实无法与左侧 HIT 组成连续窗口。
  组合风险：RETRY 设置全局 defer_lookup 但清除 pending，若窗口内同时存在两者，仍返回 None（defer 优先），保守行为保留。
  影响面：仅 SWA 组 + offload 场景，initial_window_size 参与的首窗口逻辑也随 MISS/RETRY 同步重置；非 SWA 的 _maximal_lookup 路径未改动。
  验证局限：作者自述 GPU 输出一致性检查非真实 stalled-copy 实验，上游 CI 仍是最终验证。

• 影响：用户侧：SWA 模型 + CPU/P2P KV offload 场景下，前缀已就绪却因无关写挂起而被 defer 的请求不再空等，TTFT 与超时风险下降。
  系统侧：每步调度对 candidate prefix 的扫描不再被失效窗口内的 pending 块反向阻塞，调度器可下发更多加载任务，提升 offload 命中率与利用率。
  团队侧：新增回归测试固化扫描器语义，为后续 #49829 的 deadline 修复（真正 stalled write）提供更干净的基础；代码量小、无配置/API/部署变更，维护成本低。

• 风险标记：窗口状态机语义变更, 同步/异步双路径回归, 作用域限定 SWA offload, 无真实 stalled-write 验证

关联脉络

• PR #49829 [Bug][KV Offload] HIT_PENDING has no deadline; a stalled write can defer requests until the client timeout: 父问题：本 PR 修复其观察到的 stale pending 标志子问题，但明确不解决 stalled write 本身，是同一问题线上的前置修复。
• PR #53087 （PR body 提及）HIT_PENDING bounded waits 处理: 作者确认 #53087 负责有界等待，与本 PR 的窗口语义修复互补而非重复。
• PR #53330 （PR body 提及）P2P supply/demand 覆盖修复: 作者检索后确认其处理 P2P 供给需求覆盖，与本 PR 范围不同。
• PR #51787 （PR body 提及）cache recency 相关修复: 作者检索后确认其处理缓存新鲜度，与本 PR 范围不同。