执行摘要

• 一句话：修复 CPU 卸载未对齐滑动窗口断言失败
• 推荐动作：本 PR 是一次精准的最小修复，展示了如何在不改动分配逻辑的前提下通过修正断言边界解决生产问题。建议关注其边界分析方法和 review 中 orozery 对简洁性的坚持。对于使用 CPU offload 的团队，此修复可直接合入。

功能与动机

Issue #48959 报告了 CPU KV 卸载中一个有效未对齐滑动窗口外部加载时，scheduler 的 sanity check 断言失败导致 EngineCore 崩溃的问题。具体几何：sliding window 4096 tokens，GPU block 32 tokens，offload chunk 256 tokens，cached prefix 98012 tokens，valid pending span 129 GPU blocks，而旧断言边界仅为 128 blocks。两个独立 TP=2 生产环境复现了该断言。

实现拆解

1. 定位问题：在 vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py 的 update_state_after_alloc 方法中，第 858-863 行的断言使用 group_config.sliding_window_size_in_chunks * self.config.blocks_per_chunk 作为 num_pending_gpu_blocks 的上界，但该计算假设窗口起始与 chunk 对齐，未对齐时实际物理 GPU 块数可能多 1 块。
2. 分析边界：最大物理 GPU 块数为 ceil((sliding_window_tokens + gpu_block_size - 1) / gpu_block_size)，对于生产几何（4096 token 窗口 + 32 token 块）等于 129，而 chunk 对齐上界为 128。
3. 修复：将断言条件加上 + 1，即 num_pending_gpu_blocks <= group_config.sliding_window_size_in_chunks * self.config.blocks_per_chunk + 1。
4. 简化：根据 orozery 的 review，移除了最初引入的辅助函数和组配置字段，仅保留一行核心改动，并删除了相关测试，以最小侵入性修复。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py（模块 卸载调度器；类别 source；类型 core-logic；符号 update_state_after_alloc）: 核心文件，包含 update_state_after_alloc 方法中的滑动窗口边界断言。改动加 1 以容忍未对齐窗口。

关键符号：update_state_after_alloc

关键源码片段

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

核心文件，包含 update_state_after_alloc 方法中的滑动窗口边界断言。改动加 1 以容忍未对齐窗口。

# scheduler.py 中 update_state_after_alloc 方法的部分逻辑
# 计算 GPU 块数和本地计算的块数
num_gpu_blocks = cdiv(num_cached_tokens, tokens_per_block)
assert len(group_blocks) >= num_gpu_blocks
num_locally_computed_gpu_blocks = num_gpu_blocks
# 跳过滑动窗口或 mamba 填充产生的空占位块
for i, block in enumerate(group_blocks[:num_gpu_blocks]):
    if not block.is_null and block.block_hash is None:
        num_locally_computed_gpu_blocks = i
        break
assert (
    num_locally_computed_tokens
    <= num_locally_computed_gpu_blocks * tokens_per_block
)
num_pending_gpu_blocks = num_gpu_blocks - num_locally_computed_gpu_blocks
​
# 滑动窗口边界检查
if group_config.sliding_window_size_in_chunks is not None:
    # 原断言：pending GPU 块数 <= chunk 对齐窗口大小
    # 但未对齐窗口可能多使用 1 块，因此加 1 以容许
    assert (
        num_pending_gpu_blocks
        <= group_config.sliding_window_size_in_chunks
        * self.config.blocks_per_chunk
        + 1 # 修复：允许一个额外块
    )

评论区精华

orozery 在 review 中指出：“This looks correct, but over-complicated for the sake of a sanity check assertion. I suggest that instead of introducing a utility function and field in the group config, let's just fix the assert to be a bit more permissive: ... + 1”。coltonottley 同意并简化了实现，同时移除了测试，最终 PR 只包含一行插入。

• 简化修复方案 (design): 采用一行改动，保持最小侵入性。

风险与影响

• 风险：改动仅为放宽一个 sanity check 断言，不影响实际分配、传输、取消或缓存策略。风险极低。但需注意，若其他代码隐含依赖原断言精确值（可能性低），放宽可能导致未发现的问题。此外，关联的另一生命周期缺陷（#48966）仍存在，但超出本 PR 范围。
• 影响：影响范围限于使用 CPU KV 卸载且配置滑动窗口的生产部署，尤其当 cached prefix 与 sliding window 组合导致未对齐边界时。修复后此类场景不再因断言失败导致 EngineCore 崩溃。验证表明 TP=4 下 97,792 token 外部加载正常。改单行、无功能影响。
• 风险标记：缺少测试覆盖, 边界条件变更

关联脉络

• PR #48906 [KV Offload] Deduplicate replicated MLA KV in the shared CPU region: 同一 KV offload 模块的性能优化，涉及调度器配置，与本 PR 同属 offloading 调度器相关。
• PR #49440 [Bugfix][KV Offload] Namespace persistent cache by model runner: KV offload 的 bug 修复，修改了 file_mapper.py 等文件，与本 PR 同属 offloading 子系统。
• PR #49671 [Bugfix][KV Offloading] Defer request finalization until final store: 同样修改了 scheduler.py，修复 offloading 调度器中的完成时序问题，与本 PR 相关。