执行摘要

• 一句话：将调度块大小显式注入 KV 缓存管理层
• 推荐动作：建议深入阅读此 PR，了解 vLLM KV 缓存管理层的分层架构（KVCacheManager → KVCacheCoordinator → SingleTypeKVCacheManager）和如何通过逐步显式化设计为大型重构做准备。值得关注的设计决策：使用断言确保不变性，将重复计算集中化。

功能与动机

PR 作者说明：'This is a small, behavior-preserving refactor that threads an explicit scheduler_block_size through KVCacheManager → KVCacheCoordinator → SingleTypeKVCacheManager, instead of having HybridKVCacheCoordinator recompute the LCM of group block sizes internally.' 同时指出这是 '#43447 (selective prefix-cache retention for sliding-window KV cache) 的预备步骤。'

实现拆解

步骤

1. 在 vllm/v1/core/kv_cache_manager.py 的 KVCacheManager.__init__ 中添加 scheduler_block_size 参数，并将其传递给 get_kv_cache_coordinator。
2. 在 vllm/v1/core/kv_cache_coordinator.py 的 KVCacheCoordinator 基类及所有子类构造函数中添加同名字段，通过断言确保 scheduler_block_size 是 hash_block_size 和所有 group block_size 的倍数；存储为实例成员并转发到每个 SingleTypeKVCacheManager。
3. 在 vllm/v1/core/single_type_kv_cache_manager.py 中接收并存储 scheduler_block_size（当前仅占位，为后续 PR 使用）。
4. 在调度器 vllm/v1/core/sched/scheduler.py 中构造 KVCacheManager 时传入 self.block_size 作为 scheduler_block_size。同步更新 vllm/v1/simple_kv_offload/manager.py。
5. 移除 HybridKVCacheCoordinator 中内部计算的 self.lcm_block_size，改用传入的 self.scheduler_block_size。
6. 更新所有测试文件：test_prefix_caching.py 新增辅助函数 make_kv_cache_manager，其余测试补充参数。全部 126 个测试通过。

关键文件：

• vllm/v1/core/kv_cache_coordinator.py（模块 协调器；类别 source；类型 core-logic）: 核心协调器，引入了 scheduler_block_size 参数和断言，移除了重复的 lcm 计算。
• tests/v1/core/test_prefix_caching.py（模块 前缀缓存；类别 test；类型 test-coverage；符号 make_kv_cache_manager）: 测试主文件，新增 make_kv_cache_manager 辅助函数自动推导 scheduler_block_size，简化测试修改。
• vllm/v1/core/single_type_kv_cache_manager.py（模块 单类型管理；类别 source；类型 core-logic）: 每个缓存类型管理器接收并存储 scheduler_block_size，作为后续使用的占位。
• vllm/v1/core/kv_cache_manager.py（模块 缓存管理；类别 source；类型 core-logic）: KV 缓存管理器入口，新增 scheduler_block_size 参数并向下传递。
• vllm/v1/core/sched/scheduler.py（模块 调度器；类别 source；类型 core-logic）: 调度器是源头，在构造 KVCacheManager 时传入 scheduler_block_size。

关键符号：make_kv_cache_manager

关键源码片段

vllm/v1/core/kv_cache_coordinator.py

核心协调器，引入了 scheduler_block_size 参数和断言，移除了重复的 lcm 计算。

# KVCacheCoordinator.__init__ 核心变更片段
# 省略了其他参数和初始化细节，只展示 scheduler_block_size 相关部分
def __init__(
    self,
    kv_cache_config: KVCacheConfig,
    max_model_len: int,
    max_num_batched_tokens: int,
    use_eagle: bool,
    enable_caching: bool,
    enable_kv_cache_events: bool,
    dcp_world_size: int,
    pcp_world_size: int,
    scheduler_block_size: int, # 新增显式参数，由调度器传入
    hash_block_size: int,
    metrics_collector: KVCacheMetricsCollector | None = None,
):
    self.kv_cache_config = kv_cache_config
    self.max_model_len = max_model_len
    self.enable_caching = enable_caching
​
    # 断言：调度块大小必须同时是哈希块大小和所有组块大小的倍数
    assert scheduler_block_size % hash_block_size == 0 and all(
        scheduler_block_size % g.kv_cache_spec.block_size == 0
        for g in kv_cache_config.kv_cache_groups
    )
    self.scheduler_block_size = scheduler_block_size

评论区精华

njhill 在审查 KVCacheCoordinator.__init__ 时建议在构造函数中添加断言验证 scheduler_block_size % hash_block_size == 0 且能被所有 group block_size 整除。作者采纳并在提交 ba4d14b 中使用 assert 实现。这是唯一的 review 讨论。

• 添加 scheduler_block_size 整除断言 (correctness): 作者接受建议，在下一 commit 中添加了 assert 语句。

风险与影响

• 风险：主要风险来自新增的断言：如果 scheduler_block_size 与 hash_block_size 或 group block_size 不满足整除关系，会在运行时引发 AssertionError。但调度器传入的值（self.block_size）确保了兼容性。另一风险是有未被发现的调用点未更新参数，不过从文件列表看所有调用点均已修改。总体风险较低。
• 影响：影响范围限于 vLLM V1 核心 KV 缓存管理模块。对内部 API 使用者（如自定义调度器）是强制变更，需要在构造 KVCacheManager 时提供 scheduler_block_size。对最终用户无感知，功能完全等价。CI 测试全部通过确认回归风险低。
• 风险标记：新增断言风险, 内部 API 强制变更

关联脉络

• 暂无明显关联 PR