执行摘要

• 一句话：修复 KV 缓存配置中 per-group 块计数错误
• 推荐动作：值得合并。改动简洁，测试充分，修复了一个潜伏且可能影响容量评估的 bug。设计上逐组计算块需求是更正确的做法，推荐关注 UniformTypeKVCacheSpecs 聚合行为的理解。

功能与动机

PR body 指出对于 packed UniformTypeKVCacheSpecs，组的 page_size_bytes 是聚合的，旧公式用组0的 page_size 归一化所有组导致并发度计算错误。在讨论中 ormandj 确认 root cause：UniformTypeKVCacheSpecs 报告聚合 page_size，而旧公式未逐组归一化。

实现拆解

1. 在 vllm/v1/core/kv_cache_utils.py 中重写 get_max_concurrency_for_kv_cache_config，移除中间变量 num_layer_per_group 和基于第一组 page_size 的块计算，改为对每个组直接调用 cdiv(group.kv_cache_spec.max_memory_usage_bytes(vllm_config), group.kv_cache_spec.page_size_bytes) 后求和。
2. 更新函数文档字符串，说明逐组求和的设计原理。
3. 在 tests/v1/core/test_kv_cache_utils.py 中扩展原有测试 test_get_max_concurrency_for_kv_cache_config，添加三种额外配置：不均匀组（标准 layout）、UniformTypeKVCacheSpecs 组（worker config 形状）、以及 scheduler config 形状（通过 generate_scheduler_kv_cache_config 转换），验证结果一致。
4. 新增 test_get_max_concurrency_packed_kv_cache_config 函数，模拟 packed 配置下的并发度计算，进一步覆盖 worker 和 scheduler 形状的一致性。添加 import copy 以支持测试。

关键文件：

• vllm/v1/core/kv_cache_utils.py（模块 KV缓存；类别 source；类型 core-logic；符号 get_max_concurrency_for_kv_cache_config）: 核心实现：修改了 get_max_concurrency_for_kv_cache_config 函数，修复了并发度计算中的归一化错误。
• tests/v1/core/test_kv_cache_utils.py（模块 测试用例；类别 test；类型 test-coverage；符号 test_get_max_concurrency_packed_kv_cache_config, test_get_max_concurrency_for_kv_cache_config）: 测试配套：扩展了现有测试并新增 test_get_max_concurrency_packed_kv_cache_config，覆盖不均匀组、UniformType 组和 worker/scheduler 形状一致性。

关键符号：get_max_concurrency_for_kv_cache_config

关键源码片段

vllm/v1/core/kv_cache_utils.py

核心实现：修改了 get_max_concurrency_for_kv_cache_config 函数，修复了并发度计算中的归一化错误。

def get_max_concurrency_for_kv_cache_config(
    vllm_config: VllmConfig, kv_cache_config: KVCacheConfig
) -> float:
    """
    Get the maximum concurrency for the given KV cache configuration.
​
    A request at max_model_len consumes whole blocks from each group's block
    table — cdiv(per-request bytes, page bytes) of the group's spec — and all
    groups draw those block ids from one shared pool, so the per-request
    total is the sum over groups. The memory/page ratio is identical whether
    a group carries an aggregated UniformTypeKVCacheSpecs (worker config) or
    a representative per-layer spec (scheduler config), so both capacity
    call sites agree.
    """
    # 对每个组独立计算需要多少块，然后求和
    # 旧公式用第一组的 page_size 归一化所有组的内存，在组大小不同时出错
    num_blocks_per_request = sum(
        cdiv(
            group.kv_cache_spec.max_memory_usage_bytes(vllm_config),
            group.kv_cache_spec.page_size_bytes,
        )
        for group in kv_cache_config.kv_cache_groups
    )
    max_concurrency = kv_cache_config.num_blocks / num_blocks_per_request
    return max_concurrency

评论区精华

ivanium 指出 PR 描述不准确，认为 'page_size 相同'，计算不匹配是因为 packed 布局让组内实际层数不同。ormandj 确认并重新分析，总结出 UniformTypeKVCacheSpecs 聚合 size 导致错误归一化，并修正了 PR 描述。ivanium 随后 LGTM。

• PR 描述中 root cause 的准确性 (correctness): 双方达成一致，root cause 为旧公式未能逐组归一化，修复逻辑不变。
• 其他组件（BlockPool, DSpark）是否相关 (question): 无关，讨论聚焦于核心修复。

风险与影响

• 风险：风险极低。该函数仅在启动阶段用于容量告警和日志输出，实际调度依赖 num_blocks 而非 max_concurrency。测试覆盖了均匀、不均匀、UniformType 三种场景，以及 worker/scheduler 形状的一致性。无性能、安全、兼容性风险。
• 影响：对用户：启动日志中的最大并发数更为准确，可能减少误告警。对系统：无运行时影响，不改变调度行为。对团队：发现了因 packed KV cache 引入的计算潜藏 bug，并提供了清晰的修复与测试。
• 风险标记：仅影响元数据, 调度无影响

关联脉络

• PR #40694 KV-cache logging and warnings improvement: PR body 提及该 PR 使 token log 与 max_concurrency 一致，但未修正 per-group 计算。
• PR #38408 Add KV-cache logging and warnings: PR body 提及该 PR 添加日志和警告，但未关注 per-group 计算正确性。