执行摘要

• 一句话：新增 blocks_per_chunk 配置支持异构 KV 缓存
• 推荐动作：建议精读以了解配置扩展模式。关注 build_offloading_config 中互斥校验的实现思路，可作为后续类似配置扩展的参考。

功能与动机

Issue #48635 提出，像 DeepSeek-V4-Flash 和 Gemma-4 这样的模型有多个 KV 缓存组，各组的 GPU block 大小不同。原有 token 数 block_size 配置依赖于所有组有相同的 tokens_per_block 才能正确转换为 blocks_per_chunk，导致异构配置下断言失败。用户需要直接配置 offloading chunk 大小以优化性能（如减少 disk I/O 瓶颈）。

实现拆解

1. 新增 blocks_per_chunk 配置入口：在 vllm/distributed/kv_transfer/kv_connector/v1/offloading/config.py 的 build_offloading_config 函数中，从 extra_config 读取新键 blocks_per_chunk。
2. 配置互斥校验：若 blocks_per_chunk 和 block_size 同时存在，则抛出 ValueError，要求用户只能指定其一。
3. 值校验：当 blocks_per_chunk 提供时，确保其值大于 0，否则抛错。
4. 向后兼容：若仅提供 block_size，则保留原有 token 转 chunk 逻辑；若仅提供 blocks_per_chunk，则直接使用用户指定的块数，跳过对 tokens_per_block 一致性的断言。
5. 单元测试：在 tests/v1/kv_offload/test_factory.py 中新增三个测试，覆盖：异构组使用 blocks_per_chunk 成功配置、互斥校验、blocks_per_chunk 非正数校验。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/v1/offloading/config.py（模块 配置层；类别 source；类型 core-logic）: 实现核心逻辑：添加 blocks_per_chunk 读取、互斥校验、值校验，保留原有 block_size 路径。
• tests/v1/kv_offload/test_factory.py（模块 测试；类别 test；类型 test-coverage；符号 test_offloading_spec_accepts_blocks_per_chunk_for_heterogeneous_groups, test_block_size_and_blocks_per_chunk_are_mutually_exclusive, test_blocks_per_chunk_must_be_positive）: 新增三个单元测试，覆盖正常配置、互斥校验、值校验场景。

关键符号：build_offloading_config

关键源码片段

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

实现核心逻辑：添加 blocks_per_chunk 读取、互斥校验、值校验，保留原有 block_size 路径。

# vllm/distributed/kv_transfer/kv_connector/v1/offloading/config.py
# 在 build_offloading_config 函数中新增 blocks_per_chunk 处理
​
blocks_per_chunk = 1
blocks_per_chunk_config = extra_config.get("blocks_per_chunk") # 新增：读取新配置
 tokens_per_chunk = extra_config.get("block_size") # 原有配置
​
 # 互斥校验：如果两个配置同时存在，报错明确提示
 if blocks_per_chunk_config is not None and tokens_per_chunk is not None:
     raise ValueError(
         "Specify only one of 'block_size' or 'blocks_per_chunk' "
         "in kv_connector_extra_config."
     )
​
 if blocks_per_chunk_config is not None:
     blocks_per_chunk = int(blocks_per_chunk_config)
     if blocks_per_chunk <= 0:
         raise ValueError("'blocks_per_chunk' must be greater than 0.")
 elif tokens_per_chunk is not None:
     # 原有逻辑：通过 tokens_per_block 一致性断言转换为 blocks_per_chunk
     tokens_per_chunk_int = int(tokens_per_chunk)
     unique_tokens_per_block = {group.tokens_per_block for group in groups}
     assert len(unique_tokens_per_block) == 1, (
         "If 'block_size' is specified ..., all groups must have the same block size."
     )
     tokens_per_block = unique_tokens_per_block.pop()
     assert tokens_per_chunk_int % tokens_per_block == 0
     blocks_per_chunk = tokens_per_chunk_int // tokens_per_block

tests/v1/kv_offload/test_factory.py

新增三个单元测试，覆盖正常配置、互斥校验、值校验场景。

# tests/v1/kv_offload/test_factory.py
# 测试 1：异构组使用 blocks_per_chunk 成功创建 spec
​
def test_offloading_spec_accepts_blocks_per_chunk_for_heterogeneous_groups():
    config = _make_layout_vllm_config(
        cpu_bytes_to_use=65536,
        extra_config={"blocks_per_chunk": 2},
    )
    # 使用混合 KV 缓存组（tokens_per_block 分别为 12 和 16）
    spec = _create_spec(config, _make_hybrid_kv_cache_config())
​
    assert spec.tokens_per_block == (12, 16)
    assert spec.blocks_per_chunk == 2
​
​
# 测试 2：block_size 和 blocks_per_chunk 互斥抛出异常
​
def test_block_size_and_blocks_per_chunk_are_mutually_exclusive():
    config = _make_layout_vllm_config(
        cpu_bytes_to_use=65536,
        extra_config={
            "block_size": 64,
            "blocks_per_chunk": 2,
        },
    )
    with pytest.raises(ValueError, match="Specify only one"):
        _create_spec(config, _make_kv_cache_config())
​
​
# 测试 3：blocks_per_chunk 为 0 或负数抛出异常
​
def test_blocks_per_chunk_must_be_positive():
    config = _make_layout_vllm_config(
        cpu_bytes_to_use=65536,
        extra_config={"blocks_per_chunk": 0},
    )
    with pytest.raises(ValueError, match="greater than 0"):
        _create_spec(config, _make_kv_cache_config())

评论区精华

PR 作者 Debasish-87 在评论中指出 CI 中唯一失败的检查 buildkite/ci/pr/lm-eval-kv-offload-1xh200 的 GSM8K 准确率 0.39 略低于阈值 0.40，但变更不涉及 runtime 逻辑，其他 KV-offloading 评估均通过。维护者 orozery 判断该失败与 PR 无关，表示重试后通过。无其他讨论。

• CI 测试失败是否相关 (other): 维护者 orozery 判断与 PR 无关，重试即可。

风险与影响

• 风险：风险较低。变更仅涉及配置解析和校验，不修改运行时 offloading 逻辑。主要风险是用户在异构场景下使用 blocks_per_chunk 时可能设置不合理的值导致性能下降，但校验只限制正值，未做上限检查。此外，若用户误同时指定两个参数，会得到清晰的错误提示。
• 影响：影响范围限定于使用 KV offloading 且 kv_connector_extra_config 中指定了 blocks_per_chunk 的用户。对于现有用户（使用 block_size）无影响。新功能支持了 DeepSeek-V4-Flash 和 Gemma-4 等模型在异构 KV 缓存组下启用 offloading，并允许更细粒度的 chunk 调优（如 disk offloading 场景）。
• 风险标记：新配置项可能导致误用, 无 runtime 路径变更

关联脉络

• PR #48635 [Feature][KV-offloading]: Relax Offloading Block Size asserts: 本 PR 正是为了解决该 issue 提出的需求而创建。
• PR #48251 [Bugfix][Attention] Preserve post-load tensors across weight reloads: 同为 KV 缓存相关，但内容和模块不同。