执行摘要

• 一句话：向 KV Offload 后端透传 DP 拓扑配置
• 推荐动作：值得快速浏览。PR 本身改动极小（8 个文件、23 行新增），但它是 KV offloading DP 拓扑信息补全的关键一步，为后续实现 DP-aware 的 offloading 布局/路由提供必要条件。值得关注：data_parallel_rank_local 的 None 语义约定，以及新增必填字段对第三方后端的兼容性影响。

功能与动机

PR body 明确指出：原生 KV-offloading 后端目前只拿到引擎的 data_parallel_index，但不知道总共有多少个 DP 副本，也不知道进程内的本地 DP rank，导致 OffloadingParallelConfig 无法描述完整的 DP 拓扑。为了支持后续后端做 DP 感知的 offloading 决策（如多副本数据布局、路由），需要将 data_parallel_size 和 data_parallel_rank_local 传入。

实现拆解

1. 在 vllm/v1/kv_offload/config.py 的 OffloadingParallelConfig 数据类中新增两个字段：data_parallel_size: int（DP 副本总数）和 data_parallel_rank_local: int | None（SPMD 模式下的本地 DP rank，非 SPMD 时为 None）。字段为必填，frozen dataclass，保持与既有字段风格一致。
2. 在 vllm/distributed/kv_transfer/kv_connector/v1/offloading/config.py 的 build_offloading_config() 中，构造 OffloadingParallelConfig 时从 parallel_config 透传 data_parallel_size 与 data_parallel_rank_local，完成配置源的接入。
3. 更新所有直接构造 OffloadingParallelConfig 的测试文件，为新增字段提供默认值：tests/v1/kv_offload/test_factory.py、tests/v1/kv_offload/test_file_mapper.py、tests/v1/kv_offload/tiering/test_fs_tier.py、tests/v1/kv_offload/tiering/test_obj_tier.py、tests/v1/kv_connector/unit/offloading_connector/test_worker.py。
4. 将 tests/v1/kv_connector/unit/offloading_connector/test_config.py 中的 test_preserves_data_parallel_index 扩展重命名为 test_preserves_data_parallel_config，验证 data_parallel_index=2、data_parallel_size=4、data_parallel_rank_local=1 三个值均正确透传。
5. 测试计划覆盖 42 个 offloading 配置测试、55 个 factory/file-mapper 测试、6 个 worker 测试以及 4 个 tiering 测试，并运行 ruff-format、ruff-check 与 git diff --check，全部通过。

关键文件：

• vllm/v1/kv_offload/config.py（模块 KV 卸载；类别 source；类型 core-logic）: 定义了 OffloadingParallelConfig 数据类，新增 data_parallel_size 与 data_parallel_rank_local 两个字段，是本次变更的数据契约核心。
• vllm/distributed/kv_transfer/kv_connector/v1/offloading/config.py（模块 KV 连接器；类别 source；类型 core-logic）: build_offloading_config() 是配置透传的入口，将 ParallelConfig 中的 DP 字段填入 OffloadingParallelConfig，本次变更的实际数据流发生在此。
• tests/v1/kv_connector/unit/offloading_connector/test_config.py（模块 卸载配置；类别 test；类型 test-coverage；符号 test_preserves_data_parallel_index, test_preserves_data_parallel_config）: 将 test_preserves_data_parallel_index 扩展为 test_preserves_data_parallel_config，验证三个 DP 字段同时正确透传，是本次变更的核心测试。

关键符号：build_offloading_config

关键源码片段

vllm/v1/kv_offload/config.py

定义了 OffloadingParallelConfig 数据类，新增 data_parallel_size 与 data_parallel_rank_local 两个字段，是本次变更的数据契约核心。

# vllm/v1/kv_offload/config.py
# 数据并行拓扑字段。此前只有 data_parallel_index，无法描述完整 DP 拓扑。
@dataclass(frozen=True)
class OffloadingParallelConfig:
    # Worker index in [0, world_size). 0 on the scheduler side.
    rank: int
    # Total number of workers.
    world_size: int
    # Tensor parallel size.
    tp_size: int
    # Pipeline parallel size.
    pp_size: int
    # Prefill context parallel size.
    pcp_size: int
    # Decode context parallel size.
    dcp_size: int
    # Data parallel replica index of this engine.
    data_parallel_index: int
    # Number of data parallel replicas.
    data_parallel_size: int
    # Local rank of the data parallel group, set only in SPMD mode.
    data_parallel_rank_local: int | None
    # True when the bytes that will be persisted for a block are portable
    # across parallelism configurations: for the direct layout, concatenating
    # the block's data across all workers in rank order yields the same bytes
    # under any topology; for the canonical layout, the canonical page itself
    # is topology-free.
    is_parallelism_agnostic: bool

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

build_offloading_config() 是配置透传的入口，将 ParallelConfig 中的 DP 字段填入 OffloadingParallelConfig，本次变更的实际数据流发生在此。

# vllm/distributed/kv_transfer/kv_connector/v1/offloading/config.py
# 从 ParallelConfig 透传数据并行拓扑到 OffloadingParallelConfig。
return OffloadingConfig(
    groups=groups,
    worker_kv_bytes_per_block=worker_kv_bytes_per_block,
    enable_kv_cache_events=(
        kv_events_config is not None and kv_events_config.enable_kv_cache_events
    ),
    extra_config=extra_config,
    engine_id=engine_id,
    model=OffloadingModelConfig(
        name=vllm_config.model_config.model,
        dtype=str(cache_dtype).removeprefix("torch."),
    ),
    cache=OffloadingCacheConfig(
        tokens_per_hash=tokens_per_hash,
        blocks_per_chunk=blocks_per_chunk,
    ),
    parallel=OffloadingParallelConfig(
        rank=parallel_config.rank,
        world_size=parallel_config.world_size,
        tp_size=parallel_config.tensor_parallel_size,
        pp_size=parallel_config.pipeline_parallel_size,
        pcp_size=parallel_config.prefill_context_parallel_size,
        dcp_size=parallel_config.decode_context_parallel_size,
        data_parallel_index=parallel_config.data_parallel_index,
        # 新增：DP 副本总数与进程内本地 DP rank（非 SPMD 时为 None）。
        data_parallel_size=parallel_config.data_parallel_size,
        data_parallel_rank_local=parallel_config.data_parallel_rank_local,
        is_parallelism_agnostic=is_parallelism_agnostic,
    ),
    replicated_layout=replicated_layout,
    canonical_layout=canonical_layout,
)

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

将 test_preserves_data_parallel_index 扩展为 test_preserves_data_parallel_config，验证三个 DP 字段同时正确透传，是本次变更的核心测试。

# tests/v1/kv_connector/unit/offloading_connector/test_config.py
# 验证 DP 拓扑的三个字段均能从 ParallelConfig 透传到 OffloadingParallelConfig。
def test_preserves_data_parallel_config():
    config = _make_vllm_config()
    config.parallel_config.data_parallel_index = 2
    config.parallel_config.data_parallel_size = 4
    config.parallel_config.data_parallel_rank_local = 1
​
    offloading_config = build_offloading_config(config, _make_kv_cache_config())
​
    # 断言三个字段完整透传，缺一不可。
    assert offloading_config.parallel.data_parallel_index == 2
    assert offloading_config.parallel.data_parallel_size == 4
    assert offloading_config.parallel.data_parallel_rank_local == 1

评论区精华

PR 无实质 review 评论；claude[bot] 指出 fork 来源的 PR 默认不自动 review，需要维护者触发。orozery 直接批准（APPROVED），评论中仅触发 CI（/ci run）。整体评审过程无争议。

• Fork PR 的自动 review 被禁用 (other): 未触发人工 review；orozery 直接批准并运行 CI。
• CI 运行确认 (other): CI 已触发，PR 被批准并合入。

风险与影响

• 风险：
  1. 这是配置数据类的接口扩展：OffloadingParallelConfig 是 frozen dataclass，新增必填字段会使所有直接构造该类的调用方在编译/运行时报错。本 PR 已同步更新仓库内所有测试构造点，但第三方 kv-connector 后端或外部插件如果直接构造该类，升级后会出现兼容性破坏。
  2. data_parallel_rank_local 的语义依赖 ParallelConfig.data_parallel_rank_local 的实现：当非 SPMD 模式时该值保持 None，后端消费此字段时需处理 None 分支，否则可能引发类型错误。
  3. 变更不涉及运行路径逻辑，对 DP 初始化、offloading 策略与数据移动均为零影响，回归风险集中在配置构造点遗漏。
     - 影响：影响范围限于 KV offloading 链路：一是配置数据的消费者（CPU offloading、tiering 等后端 spec）未来可基于 DP 拓扑做更精细的布局或路由决策；二是当前仓库内所有构造 OffloadingParallelConfig 的位置（约 6 个测试文件和 1 个配置构建函数）均已完成适配。对用户和系统运行行为没有直接变化，属于为后续功能铺路的平台性小改动。对团队而言，这是 kv-connector 功能线的一部分，相关后端开发者需要了解新字段的语义。
     - 风险标记：配置接口变更, 第三方兼容性, 无运行路径变更

关联脉络

• PR #51614 [Bugfix][KV Offload] Emit self-describing CPU events at KV-group block granularity: 同为 kv-connector / KV offload 功能线，修改同一组配置与事件语义，体现 KV offloading 正在逐步补全拓扑与事件信息。
• PR #52058 [Bugfix] Bound KV block zeroing launch geometry: 涉及 KV offload 的 worker 工具链（KVBlockZeroer），与本 PR 同属 KV offload 子系统，拓扑信息的补全可能为后续零化/传输逻辑提供上下文。
• PR #51218 [Bugfix] Report FULL_ATTENTION for uniform-base UniformTypeKVCacheSpecs groups instead of UNKNOWN: 同为 kv-connector 配置语义的修正，说明该模块正处在一个补齐描述信息的阶段。