执行摘要

• 一句话：定义 KV Offload 后端配置边界，重构配置所有权
• 推荐动作：该 PR 是架构分层的优秀范例，建议所有涉及 vLLM 卸载系统或配置管理的工程师精读。关键设计决策包括：依赖倒置（kv_offload 定义接口，connector 实现翻译）、冻结数据类确保不变性、以及系统性术语统一。阅读时重点关注 build_offloading_config 如何编排多个配置源，以及 OffloadingSpec 如何从庞杂的初始化简化为单一配置对象。该 PR 也为后续 MLA 去重功能奠定了配置基础。

功能与动机

源自 issue #47929 的 review 讨论。评审者 orozery 指出 kv_offload 目录不应从 offloading connector 或 vLLM 内部导入，要求定义干净的结构体，由 connector 构建（原文："define clean structs on kv_offload, and have the offloading connector build them"）。此 PR 实现了该所有权分离，建立清晰的配置边界。

实现拆解

1. 新增配置结构体：创建 vllm/v1/kv_offload/config.py，定义五个 @dataclass(frozen=True) 类：OffloadingGroupConfig（每组的 tokens_per_block 和层名）、OffloadingModelConfig（模型名和 dtype）、OffloadingCacheConfig（tokens_per_hash 和 blocks_per_chunk）、OffloadingParallelConfig（并行参数与预计算的 is_parallelism_agnostic 标志）、以及组合的 OffloadingConfig。这些结构体是 kv_offload 的唯一配置入口，不依赖任何 connector 代码。
2. 实现配置翻译：在 vllm/distributed/kv_transfer/kv_connector/v1/offloading/config.py 中新增 build_offloading_config 函数，接收 VllmConfig 和 KVCacheConfig，提取上下文并行因子、块几何、打包检测、并行性无关判定、事件配置等，返回完整的 OffloadingConfig。该函数承担了原本分散在 OffloadingSpec.__init__ 和 FileMapper 中的解析逻辑。
3. 统一构造函数：将 OffloadingSpec 及其子类（CPUOffloadingSpec、TieringOffloadingSpec）的构造函数从 (vllm_config, kv_cache_config) 改为单个 OffloadingConfig 参数，提取原有计算逻辑并委托给 connector。同时更新 OffloadingSpecFactory.create_spec 和 FileMapper.from_offloading_spec 以适配新签名。
4. 采用 chunk 术语：根据 review 建议，全局重命名以统一描述卸载单元。原有的 block_size 变为 tokens_per_block，offloaded_block_size 变为 tokens_per_chunk，hash_block_size 变为 tokens_per_hash，block_size_factor 变为 blocks_per_chunk。涉及调度器的 GroupOffloadConfig、命名空间键、以及相关测试。
5. 测试与清理：移除 kv_offload 目录对 connector 的反向导入边界测试（因难以维护）。新增针对打包/非打包布局、并行性无关标志、混合模型文件身份、外部插件构造的 characterization 测试。FileMapper 测试改为通过 OffloadingConfig 构建 mock spec，减少硬编码。

关键文件：

• vllm/v1/kv_offload/config.py（模块 卸载配置；类别 source；类型 core-logic；符号 OffloadingGroupConfig, OffloadingModelConfig, OffloadingCacheConfig, OffloadingParallelConfig）: 核心新增文件，定义归一化配置结构体 OffloadingConfig 及其子结构，是配置边界的基础
• vllm/distributed/kv_transfer/kv_connector/v1/offloading/config.py（模块 连接器配置；类别 source；类型 core-logic；符号 is_kv_cache_tensor_packed, build_offloading_config）: 连接器端新增配置翻译函数，将 vLLM 配置转换为归一化的 OffloadingConfig，实现所有权分离
• vllm/distributed/kv_transfer/kv_connector/v1/offloading/scheduler.py（模块 调度器；类别 source；类型 core-logic；符号 get_sliding_window_size_in_blocks, get_sliding_window_size_in_chunks, resolve_mamba_align_size, from_spec）: 核心调度器适配新配置结构，重命名群组配置字段并使用 chunk 术语，包含滑动窗口大小计算等关键逻辑调整
• vllm/v1/kv_offload/base.py（模块 基类；类别 source；类型 core-logic；符号 init）: OffloadingSpec 基类构造函数重构，从接收两个参数改为单个 OffloadingConfig，移除内部计算逻辑
• tests/v1/kv_offload/test_factory.py（模块 工厂测试；类别 test；类型 test-coverage；符号 _get_extra_config, _create_spec, _make_layout_vllm_config, _make_sizing_kv_cache_config）: 新增大量 characterization 测试，覆盖打包布局、并行性无关标志、混合模型文件身份、外部插件构造等场景
• tests/v1/kv_offload/test_file_mapper.py（模块 文件映射测试；类别 test；类型 test-coverage；符号 _full_attention_group, test_hybrid_file_identity_uses_resolved_tokens_per_hash, _sliding_window_group, test_parallel_agnostic_enabled_for_single_full_attention）: FileMapper 测试重写，适应新配置结构并增加并行性无关标志的覆盖

关键符号：build_offloading_config, is_kv_cache_tensor_packed, OffloadingConfig, OffloadingGroupConfig, OffloadingSpec.init, get_sliding_window_size_in_chunks, resolve_mamba_align_size, FileMapper.from_offloading_spec

关键源码片段

vllm/v1/kv_offload/config.py

核心新增文件，定义归一化配置结构体 OffloadingConfig 及其子结构，是配置边界的基础

# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""Normalized configuration consumed by native offloading backends."""
​
from collections.abc import Mapping
from dataclasses import dataclass
from typing import Any
​
​
@dataclass(frozen=True)
class OffloadingGroupConfig:
    # Total token span covered by one block across all workers
    # (accounts for context parallelism).
    tokens_per_block: int
    # Layer names belonging to this group.
    layer_names: tuple[str, ...]
​
​
@dataclass(frozen=True)
class OffloadingModelConfig:
    # Model identifier (e.g. HuggingFace model path).
    name: str
    # KV cache data type (e.g. "float16").
    dtype: str
​
​
@dataclass(frozen=True)
class OffloadingCacheConfig:
    # Tokens per block hash.
    tokens_per_hash: int
    # Blocks coalesced into one offload chunk.
    blocks_per_chunk: int
​
​
@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
    # True when concatenating a block's data across all workers yields
    # the same result regardless of the parallelism configuration.
    is_parallelism_agnostic: bool
​
​
@dataclass(frozen=True)
class OffloadingConfig:
    groups: tuple[OffloadingGroupConfig, ...]
    # KV bytes stored by one worker per block.
    worker_kv_bytes_per_block: int
    # Whether the scheduler emits KV cache events. When true,
    # the offloading backend should emit events as well.
    enable_kv_cache_events: bool
    # Offloading-specific configuration from kv_connector_extra_config.
    extra_config: Mapping[str, Any]
    # Unique identifier for this engine, distinct per DP rank.
    engine_id: str
    model: OffloadingModelConfig
    cache: OffloadingCacheConfig
    parallel: OffloadingParallelConfig

评论区精华

讨论主要围绕三个主题：

• 配置边界：orozery 强调 kv_offload 不应导入 connector 或 vLLM 内部结构，最终定义干净的数据类并由 connector 翻译。
• 命名规范：orozery 提出使用“chunk”统一描述卸载单元，避免“key”的歧义，得到积极采纳并在整个域中实施重命名。

• 测试策略：orozery 建议移除难以维护的边界导入测试，并恢复 test_file_mapper.py 中使用 mock spec 的方式（而非构建真实 config），以简化维护。

  • Clean backend configuration boundary (design): 新增 OffloadingConfig 等结构体，build_offloading_config 实现翻译，实现了所有权分离
  • Adopt chunk terminology (design): 全局重命名，涉及 config、spec、scheduler、FileMapper 和测试
  • Test helper: revert to mock spec (testing): Change72 应用了 revert，测试文件改为通过 OffloadingConfig 构建 mock spec
  • Remove reverse import boundary test (testing): Change72 移除了 test_kv_offload_config_boundary_has_no_reverse_runtime_imports 测试

风险与影响

• 风险：
  1. 缓存摘要变更：FileMapper 命名空间记录了解析后的哈希粒度、上下文并行缩放后的块大小和重命名的身份键，导致 FS/OBJ 命名空间摘要变更。存量磁盘缓存会冷缺失，混合版本 P2P 对等节点因配置指纹不匹配而安全关闭，但用户需注意首次启动的缓存重建开销。
  2. 插件接口断裂：实验性的 OffloadingSpec 构造函数签名从 (vllm_config, kv_cache_config) 改为 (OffloadingConfig)，外部 spec_module_path 加载的插件需要相应更新（虽然迁移是机械的）。
  3. 遗留不一致：Mamba hybrid + context parallel 场景下，tokens_per_block 对所有组统一应用 DCP×PCP 因子，但 resolve_kv_cache_block_sizes 有意让 Mamba 组不缩放。此既有差异在 PR 中保留未修，可能影响该场景下的卸载大小计算。
  4. 大量改动覆盖风险：27 文件，+1275/-843 的改动涉及核心配置流，虽然测试通过，但边缘情况（如无块场景、混合注意力）可能未被充分覆盖。
     - 影响：对使用原生卸载功能的用户（通过 OffloadingConnector）而言，重构透明但不兼容：存量缓存会冷缺失，需首次重建。对实验性外部插件用户，需要更新 OffloadingSpec 子类构造签名。对系统层面，配置所有权清晰化降低了耦合，为后续实现 MLA 副本去重（issue #47929 核心目标）扫清了障碍。对团队，统一术语和测试模式提高了可维护性。该 PR 不改变模型执行路径，不产生性能差异。
     - 风险标记：缓存摘要变更, 插件接口断裂, Mamba 缩放不一致遗留, 大量改动覆盖风险

关联脉络

• PR #47929 [Feature]: Deduplicate replicated MLA KV across TP ranks in native offloading: 该 issue 是此 PR 的源头，要求定义干净配置边界以支持后续 MLA 去重
• PR #47636 [Bugfix] Fix data parallel port offset in P2P manager: 该 PR 合入后，本 PR 需要适配 data_parallel_index 暴露等变更，已集成到配置结构