执行摘要

• 一句话：canonical_layout 下保留 per-layer KV 注册，修复启动失败
• 推荐动作：值得精读，改动虽小但涉及 KV offload 与 canonical layout 两个设计约束的取舍。关注 prefer_cross_layer_blocks 的语义变化及其在调度器中的消费点，可作为理解 KV connector 配置体系的入口。

功能与动机

PR body 指出：connector 偏好跨层块，但跨层 slab 没有 per-layer refs 可供认证，统一注意力模型（如 Qwen3-30B-A3B at tp2）在 V1 model runner 上因 canonical_layout 被拒绝而无法启动。Issue 评论中 Etelis 进一步说明：即使请求 canonical，跨层偏好仍会覆盖并导致崩溃。本变更保住 per-layer 注册路径，解锁 canonical offload。

实现拆解

1. 记录配置：在 OffloadingConnector.__init__ 中，通过 build_offloading_config(vllm_config, kv_cache_config) 取得配置后保存 self._canonical_layout = offloading_config.canonical_layout，为后续偏好决策提供状态。
2. 调整偏好属性：将 prefer_cross_layer_blocks 从恒定 True 改为 return not self._canonical_layout。这样当用户请求 canonical_layout 时，调度器会退回 per-layer 块注册，避免因跨层 slab 无法认证而启动失败；未请求 canonical 时行为完全不变。
3. 新增单元测试：在 tests/v1/kv_connector/unit/offloading_connector/test_config.py 中新增 test_prefer_cross_layer_blocks_yields_to_canonical_layout，通过 mock 工厂 make_connector 在无 GPU 环境下构造 connector，分别断言默认偏好跨层块、canonical_layout: True 时偏好被禁用。
4. 配套验证：PR 描述在 2x H200 上对 Qwen3-30B-A3B tp2 做 E2E：canonical_layout 下可正常启动且所有层认证可移植、CPU 加载验证通过；canonical 关闭时跨层分配不变。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/v1/offloading_connector.py（模块 KV连接器；类别 source；类型 core-logic；符号 prefer_cross_layer_blocks, OffloadingConnector.init）: 核心修复：prefer_cross_layer_blocks 由恒定 True 改为依据 _canonical_layout 动态返回，并在 init 中记录该配置，是解锁 canonical offload 的关键改动。
• tests/v1/kv_connector/unit/offloading_connector/test_config.py（模块 KV连接器；类别 test；类型 test-coverage；符号 test_prefer_cross_layer_blocks_yields_to_canonical_layout, make_connector）: 新增测试覆盖 canonical_layout 下 prefer_cross_layer_blocks 的行为，确保默认偏好跨层块、canonical 时退回 per-layer，无 GPU 即可运行。

关键符号：prefer_cross_layer_blocks, OffloadingConnector.init, test_prefer_cross_layer_blocks_yields_to_canonical_layout, make_connector

关键源码片段

vllm/distributed/kv_transfer/kv_connector/v1/offloading_connector.py

核心修复：prefer_cross_layer_blocks 由恒定 True 改为依据 _canonical_layout 动态返回，并在 init 中记录该配置，是解锁 canonical offload 的关键改动。

class OffloadingConnector(KVConnectorBase_V1, SupportsHMA):
    @property
    def prefer_cross_layer_blocks(self) -> bool:
        # 跨层 slab 没有 per-layer 引用可用于认证 canonical 映射，
        # 因此请求 canonical_layout 时必须退回 per-layer 注册
        return not self._canonical_layout
​
    @property
    def requires_kv_delivery(self) -> bool:
        # 以 kv_both 角色运行，但作为尽力而为缓存：丢失保存只是未来缓存未命中
        return False
​
    def __init__(self, vllm_config, role, kv_cache_config):
        super().__init__(vllm_config, role, kv_cache_config)
​
        offloading_config = build_offloading_config(vllm_config, kv_cache_config)
        # 保存 canonical_layout 标志，供 prefer_cross_layer_blocks 属性决策
        self._canonical_layout = offloading_config.canonical_layout
        spec = OffloadingSpecFactory.create_spec(offloading_config)
​
        # 按角色创建调度器或 worker 实例
        if role == KVConnectorRole.SCHEDULER:
            self.connector_scheduler = OffloadingConnectorScheduler(spec, vllm_config, kv_cache_config)
        elif role == KVConnectorRole.WORKER:
            self.connector_worker = OffloadingConnectorWorker(spec, vllm_config, kv_cache_config)

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

新增测试覆盖 canonical_layout 下 prefer_cross_layer_blocks 的行为，确保默认偏好跨层块、canonical 时退回 per-layer，无 GPU 即可运行。

def test_prefer_cross_layer_blocks_yields_to_canonical_layout():
    # canonical_layout 下 connector 不得请求 cross-layer 块：
    # 跨层 slab 没有 per-layer 引用可进行 canonical 映射认证
    from vllm.distributed.kv_transfer.kv_connector.v1.base import KVConnectorRole
    from vllm.distributed.kv_transfer.kv_connector.v1.offloading_connector import (
        OffloadingConnector,
    )
​
    kv_cache_config = _make_kv_cache_config()
    connector_module = "vllm.distributed.kv_transfer.kv_connector.v1"
​
    def make_connector(extra_config: dict | None) -> OffloadingConnector:
        # mock 掉 SpecFactory 与 Scheduler，仅验证配置驱动的偏好逻辑
        with (
            patch(f"{connector_module}.offloading_connector.OffloadingSpecFactory"),
            patch(f"{connector_module}.offloading_connector.OffloadingConnectorScheduler"),
        ):
            return OffloadingConnector(
                _make_vllm_config(extra_config=extra_config),
                KVConnectorRole.SCHEDULER,
                kv_cache_config,
            )
​
    # 默认仍偏好跨层块；请求 canonical_layout 时退回 per-layer 注册
    assert make_connector(None).prefer_cross_layer_blocks
    assert not make_connector({"canonical_layout": True}).prefer_cross_layer_blocks

评论区精华

Etelis 在 issue 评论中解释根因：@orozery as mentioned, the problem is the conflict with cross-layers, even when we do want cannonical crosslayers overrides it (crashes)。Maintainer orozery 触发 CI 并在修复后批准合入；Claude bot 因 fork 关闭自动审查，未产生额外 review 评论。

• canonical_layout 与 cross-layer 偏好冲突 (correctness): 通过让 prefer_cross_layer_blocks 在 canonical_layout 下返回 False，保留 per-layer 注册路径，冲突消除。

风险与影响

• 风险：变更集中在单属性决策和配置记录，但影响 KV 块分配策略：canonical_layout 下从跨层块退回 per-layer 块，可能影响缓存复用效率和卸载带宽。风险点包括：
  1) prefer_cross_layer_blocks 被调度器用于分配路径，行为变化需在 V1 调度器与 offloading worker 中覆盖足够测试；
  2) 仅新增单元测试，E2E 依赖 PR 描述的手动验证；
  3) 若 canonical_layout 与跨层块存在其他隐式依赖，可能在其他模型或非 MoE 场景出现回归。
  • 影响：影响范围：仅当用户显式请求 canonical_layout 且使用 OffloadingConnector 时行为改变，其余路径不变。直接受益者是 V1 运行器上的统一注意力 MoE 模型（Qwen3-MoE、Mixtral、GLM-4.5-Air/4.6），可启用 canonical offload。对团队而言是低风险小改动，但解锁了一个此前不可用的功能组合。
  • 风险标记：canonical 路径行为变更, 影响跨层块分配策略, 缺少自动化 E2E 覆盖

关联脉络

• 暂无明显关联 PR