执行摘要

• 一句话：修复 OffloadingConnector 忽略 skip_reading_prefix_cache 标志
• 推荐动作：推荐阅读。该 PR 虽然改动小，但展示了在多层缓存系统中保持语义一致的重要性。OffloadingConnector 与 KVCacheManager 的协调逻辑值得关注，特别是如何确保外部缓存与本地缓存行为同步。测试用例的设计（先填充缓存，重置本地，再验证跳过）可作为同类修复的参考模式。

功能与动机

根据 issue #44585，当请求设置了 skip_reading_prefix_cache=True（例如通过 prompt_logprobs 参数）时，KVCacheManager 已正确跳过本地前缀缓存，但 OffloadingConnector 仍然从 CPU 缓存查询并返回匹配块，导致 KV 块被错误加载。这违背了用户的显式意图，必须修复以使 OffloadingConnector 的行为与 KVCacheManager 一致。

实现拆解

修复分为三步：

1. 核心逻辑修改（vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py）：在 get_num_new_matched_tokens 方法中，将原始的 num_hit_tokens = self._lookup(req_status) 替换为条件分支：若 request.skip_reading_prefix_cache 为 True，则直接令 num_hit_tokens = 0，否则调用 self._lookup。其余状态更新（update_offload_keys、update_num_hit_blocks、_touch）保持不变，确保 offload 管理正常，仅阻断 CPU 加载。
2. 测试工具扩展（tests/v1/kv_connector/unit/offloading_connector/utils.py）：在 new_request 方法签名中添加 skip_reading_prefix_cache: bool = False 参数，并在构造 SamplingParams 时将其传入，使测试能够构造带有该标志的请求。
3. 测试用例新增（tests/v1/kv_connector/unit/offloading_connector/test_scheduler.py）：新增 test_skip_reading_prefix_cache 测试，参数化 async_scheduling 两种模式。测试流程：先用正常请求向 CPU 缓存填充一个块，重置 GPU 前缀缓存，再发送相同 token 但 skip_reading_prefix_cache=True 的请求，验证：
   1) expected_loaded 为空，未从 CPU 加载任何块；
   2) expected_stored 包含块，本地计算仍正常卸载；
   3) runner.manager.lookup.assert_not_called() 确认外部查找完全跳过。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py（模块 卸载调度；类别 source；类型 core-logic；符号 get_num_new_matched_tokens）: 核心修复文件，添加条件判断跳过 CPU 缓存查找，是 bug 的本源修改。
• tests/v1/kv_connector/unit/offloading_connector/test_scheduler.py（模块 卸载测试；类别 test；类型 test-coverage；符号 test_skip_reading_prefix_cache）: 新增测试用例，完整验证 skip_reading_prefix_cache 标志被正确处理，确保修复可靠。
• tests/v1/kv_connector/unit/offloading_connector/utils.py（模块 测试工具；类别 test；类型 test-coverage；符号 new_request）: 扩展测试工具 runner 的 new_request 方法，添加 skip_reading_prefix_cache 参数，使测试能构造需要标记的请求。

关键符号：get_num_new_matched_tokens, new_request, test_skip_reading_prefix_cache

关键源码片段

tests/v1/kv_connector/unit/offloading_connector/test_scheduler.py

新增测试用例，完整验证 skip_reading_prefix_cache 标志被正确处理，确保修复可靠。

# tests/v1/kv_connector/unit/offloading_connector/test_scheduler.py
​
@pytest.mark.parametrize("async_scheduling", [True, False])
def test_skip_reading_prefix_cache(request_runner, async_scheduling: bool):
    """验证 skip_reading_prefix_cache=True 时 OffloadingConnector 不会
    从 CPU 加载任何块，即使 CPU 缓存中有匹配的前缀。"""
    block_size = 4
    block_size_factor = 3
    offloaded_block_size = block_size * block_size_factor
    num_gpu_blocks = 100
​
    runner = request_runner(
        block_size=block_size,
        num_gpu_blocks=num_gpu_blocks,
        async_scheduling=async_scheduling,
        block_size_factor=block_size_factor,
    )
​
    # 第一步：向 CPU 缓存填充一个块（通过正常请求）
    runner.new_request(token_ids=[0] * offloaded_block_size)
    runner.manager.prepare_store.side_effect = lambda keys, req_context: (
        generate_store_output(keys)
    )
    runner.run(
        decoded_tokens=[EOS_TOKEN_ID],
        expected_stored=(0, 1, 2),
        expected_flushed=(0, 1, 2) if not async_scheduling else (),
    )
​
    # 重置 GPU 前缀缓存，使后续请求无法命中本地缓存
    runner.scheduler.reset_prefix_cache()
​
    # 第二步：发送相同 token 但设置 skip_reading_prefix_cache=True 的请求
    # 期望：不从 CPU 加载任何块，但本地计算的块仍正常卸载
    runner.new_request(
        token_ids=[0] * offloaded_block_size,
        skip_reading_prefix_cache=True,
    )
    runner.manager.prepare_store.side_effect = lambda keys, req_context: (
        generate_store_output(keys)
    )
    runner.run(
        decoded_tokens=[EOS_TOKEN_ID],
        expected_loaded=(), # 断言没有从 CPU 加载
        expected_stored=(0, 1, 2), # 新计算的块仍被卸载到 CPU
        expected_flushed=(0, 1, 2) if not async_scheduling else (),
    )
​
    # 验证外部查找方法完全未被调用
    runner.manager.lookup.assert_not_called()

tests/v1/kv_connector/unit/offloading_connector/utils.py

扩展测试工具 runner 的 new_request 方法，添加 skip_reading_prefix_cache 参数，使测试能构造需要标记的请求。

# tests/v1/kv_connector/unit/offloading_connector/utils.py
​
def new_request(
    self,
    token_ids: list[int],
    kv_transfer_params: dict | None = None,
    skip_reading_prefix_cache: bool = False, # 新增参数，默认 False
):
    """创建一个新请求并添加到调度器。
​
    Args:
        token_ids: 请求的 token ID 列表
        kv_transfer_params: KV 传输参数
        skip_reading_prefix_cache: 是否跳过读取前缀缓存，本参数
            会通过 SamplingParams 传播给请求
    """
    self.req_id += 1
​
    # 将 skip_reading_prefix_cache 传递给 SamplingParams
    sampling_params = SamplingParams(
        max_tokens=1000,
        skip_reading_prefix_cache=skip_reading_prefix_cache or None,
    )
    sampling_params.update_from_generation_config({}, EOS_TOKEN_ID)
​
    req = Request(
        request_id=str(self.req_id),
        prompt_token_ids=token_ids,
        sampling_params=sampling_params,
        pooling_params=None,
        block_hasher=self._block_hasher,
    )
    if kv_transfer_params is not None:
        req.kv_transfer_params = kv_transfer_params
​
    self.scheduler.add_request(req)

评论区精华

核心讨论来自 reviewer orozery：

• 第一次审查指出初始实现（直接 return (0, False)）会跳过必要逻辑（如 update_offload_keys、update_num_hit_blocks），建议只跳过 _lookup 调用。作者随后修改为 num_hit_tokens = 0 if request.skip_reading_prefix_cache else self._lookup(req_status)。
• 第二次审查建议将 ternary 表达式改为更易读的 if-else 结构，作者接受并调整。

• 最终实现确认正确，reviewer 批准并感谢作者贡献。

• skip_reading_prefix_cache 标志的处理方式 (correctness): 采用 if-else 分支：if request.skip_reading_prefix_cache: num_hit_tokens = 0 else: num_hit_tokens = self._lookup(req_status)。

风险与影响

• 风险：风险极低。变更仅在 get_num_new_matched_tokens 方法中添加了一条简单条件分支，且与本地 KVCacheManager 中的已有逻辑一致。新增的测试用例完整覆盖了同步/异步两种调度模式，并直接断言 lookup 未被调用。回归风险仅限于 offloading connector 的请求调度路径，但测试通过保证了正确性。潜在的性能影响可忽略：多了一次布尔检查。
• 影响：影响范围集中于使用 OffloadingConnector（原生 CPU KV 卸载）的用户，特别是同时使用 prompt_logprobs 或显式设置 skip_reading_prefix_cache=True 的场景。修复后，这些请求将如预期完全重算 prompt，不再错误加载 CPU 缓存的 KV 块。对于不涉及 skip_reading_prefix_cache 的正常请求，行为完全不变。
• 风险标记：核心调度路径变更, 条件分支新增

关联脉络

• PR #45206 [Bugfix][KVConnector][Mooncake] Close MooncakeDistributedStore on connector teardown: 同属 kv-connector 域的另一项 bugfix，修复连接器生命周期泄漏问题，体现了该模块的持续稳定化工作。
• PR #44424 [Bugfix] Fix CPU memory leak related to not cleaning up old remotes data: 同样针对 kv-connector 的 bugfix，解决 CPU 端内存泄漏，与本 PR 均属于外部缓存管理的修复，显示对离线 KV 传输可靠性的重视。