执行摘要

• 一句话：排除 QSA ring 组，修复 MooncakeStore 混合注意力启动崩溃
• 推荐动作：值得精读。该 PR 展示了「transferable ≠ storable」的投影分层设计：同一 KV cache group 可因 prefix_cacheable 属性在不同连接器视角下呈现不同子集，并通过「扩展既有 API 而非新增 selector」控制接口膨胀。review 中 ivanium 与作者的几轮交锋（命名、抽象层次、API 删除）是接口设计讨论的良好案例。建议关注后续是否统一 select_transfer_block_ids 与 get_block_ids(group_ids=...) 的接口职责，以及 prefix_cacheable 属性在各 cache spec 上的契约覆盖。

功能与动机

修复 issue #54726（Qwen3.8-Flash-Next-FP8 + MooncakeStoreConnector 启动失败）。PR body 定位了两个根因：(1) QSA ring scratch cache 可传输但不是有效的 hash 寻址 prefix 数据，CircularBufferSpec.prefix_cacheable 显式为 False，ring 容量为 4（无投机 token）或 8（MTP=3），而 aligned attention/Mamba group 使用 block size 800，ring 被误纳入仅为可存储 prefix group 设计的 divisibility check；(2) MooncakeStore 通过比较每个 Mamba block size 与全局重写的 cache_config.block_size 来推断 align mode，在异构 group 下该全局值可能与已解析的 Mamba group size 不同，即使 mamba_cache_mode 已正确为 "align" 也会误报。

实现拆解

1. KVCacheConfig 增加 prefix-cacheable 投影：vllm/v1/kv_cache_interface.py 新增 prefix_cacheable_group_ids 与 prefix_cacheable_groups 两个 cached_property，以 transfer_group_ids 为基底再按 kv_cache_spec.prefix_cacheable 过滤，形成「可传输 group ⊇ 可存储 group」的分层投影。这样 NIXL 等连接器继续使用 transfer_groups 全量传输（含 QSA ring），而 MooncakeStore 只用可存储投影。
2. 扩展 KVCacheBlocks.get_block_ids：vllm/v1/core/kv_cache_manager.py 为 get_block_ids 增加 keyword-only 参数 group_ids: Sequence[int] | None，返回指定 group 的块 ID 元组。这是 review 中 ivanium 建议的设计：调度器直接按 store 投影取块，避免先取全量 block_ids 再二次投影，也避免为 MooncakeStore 新增通用 selector 接口。
3. MooncakeStore 调度器改用 store 投影并保持 group ID 稳定：vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/scheduler.py 的 __init__ 建立 _store_group_ids 与 _store_group_id_by_kv_cache_group_id 映射；update_state_after_alloc、build_connector_meta、_apply_current_save_block_ids 全部改为按 store 投影取块；register_finished_partial_tail 与 _handle_boundary_state_offloads 将原始 group ID 重映射为 store group ID，因此跳过 QSA ring 后 Mamba 边界状态编号不偏移。
4. 校验与注册逻辑修正：connector.py 的 _validate_kv_cache_config 不再拿全局 cache_config.block_size 与 Mamba block_size 比对，改为直接校验 spec.mamba_cache_mode == "align"，并新增「至少一个 prefix-cacheable group」前置检查；worker.py 的 register_kv_caches 用 store_layer_names 过滤非 prefix-cacheable 层，避免 QSA ring 缓存 tensor 被注册进 store 布局；coordinator.py 增加 mooncake_store_group_ids 辅助函数。
5. 测试与验证配套：新增 _make_qsa_hybrid_cache_config / _make_qsa_hybrid_kv_cache_config 夹具模拟 full + QSA ring + Mamba 三组缓存，覆盖 scheduler 投影、块 ID 投影、boundary state 重映射、worker 初始化与注册过滤、校验接受/拒绝场景；test_kv_cache_utils.py 覆盖新投影属性与 get_block_ids(group_ids=...)。PR body 报告 412 个单测通过、NIXL HMA 77 个用例通过，并附 GSM8K 评估（0.9697/0.9704）确认修复后 prefix-cache 命中与正确性不受影响。

关键文件：

• vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/scheduler.py（模块 调度器；类别 source；类型 core-logic；符号 MooncakeStoreScheduler）: 核心逻辑改造：引入 store group 投影与重映射，所有调度器路径（取块、保存、边界状态）都只处理 prefix-cacheable 组，是修复的主战场。
• vllm/v1/kv_cache_interface.py（模块 缓存接口；类别 source；类型 core-logic；符号 prefix_cacheable_group_ids, prefix_cacheable_groups）: 新增 prefix_cacheable_group_ids / prefix_cacheable_groups，构成 transfer 投影之上的可存储投影，是整个修复的 API 基础。
• vllm/v1/core/kv_cache_manager.py（模块 缓存管理；类别 source；类型 core-logic；符号 KVCacheBlocks.get_block_ids）: KVCacheBlocks.get_block_ids 扩展 group_ids 参数，让调度器按投影直接取块；这是 review 中 ivanium 明确要求的设计方向。
• vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/connector.py（模块 连接器；类别 source；类型 core-logic；符号 MooncakeStoreConnector._validate_kv_cache_config）: _validate_kv_cache_config 修复第二个隐藏问题：直接用 spec.mamba_cache_mode 校验 align 模式，并新增至少一个 prefix-cacheable group 的前置检查。
• vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/worker.py（模块 工作进程；类别 source；类型 core-logic；符号 MooncakeStoreWorker, MooncakeStoreWorker.register_kv_caches）: worker 只用 prefix_cacheable_groups 初始化，register_kv_caches 通过 store_layer_names 过滤非可存储层，防止 QSA ring tensor 被注册进 store；zhewenl 在 review 中坚持保留此过滤。
• vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/coordinator.py（模块 协调器；类别 source；类型 core-logic；符号 mooncake_store_group_ids）: 新增 mooncake_store_group_ids 辅助函数统一 store group ID 来源；ivanium 认为过度抽象，后续 commit 已部分简化。
• tests/v1/kv_connector/unit/test_mooncake_store_scheduler.py（模块 调度器；类别 test；类型 test-coverage；符号 _make_qsa_hybrid_cache_config, test_scheduler_projects_nonprefix_groups_and_mamba_ids, test_current_save_block_ids_use_store_group_projection, test_boundary_state_group_ids_are_remapped_to_store_projection）: 新增 QSA 混合缓存夹具与 4 个关键回归测试：投影、保存块 ID、边界状态重映射，是调度器行为锁定的核心测试。
• tests/v1/kv_connector/unit/test_mooncake_store_worker.py（模块 工作进程；类别 test；类型 test-coverage；符号 _make_qsa_hybrid_kv_cache_config, test_worker_init_excludes_nonprefix_cache_groups, test_register_kv_caches_excludes_nonprefix_cacheable_layers）: 验证 worker 初始化只含 prefix-cacheable 组、注册时排除 QSA 层，是「过滤是否必要」争论后的行为锁定。
• tests/v1/kv_connector/unit/test_mooncake_store_connector.py（模块 连接器；类别 test；类型 test-coverage；符号 _make_qsa_hybrid_kv_cache_config, test_validation_accepts_aligned_mamba_after_block_size_rewrite, test_validation_rejects_mamba_mode_directly）: 锁定校验行为：align 模式在 block_size 重写后仍被接受，none 模式直接拒绝，覆盖第二个隐藏问题的修复。
• tests/v1/core/test_kv_cache_utils.py（模块 缓存管理；类别 test；类型 test-coverage；符号 test_kv_cache_config_selects_prefix_cacheable_groups, test_kv_cache_blocks_selects_requested_groups）: 覆盖新 KVCacheConfig 投影属性与 KVCacheBlocks.get_block_ids(group_ids=...) 的通用行为，属于共享 API 的契约测试。
• tests/v1/kv_connector/unit/test_mooncake_store_hma_e2e.py（模块 端到端测试；类别 test；类型 test-coverage）: 端到端用例适配投影后行为（token_dbs 数量、group_participates、store 命名空间），确认 QSA ring 不再进入 store。

关键符号：prefix_cacheable_group_ids, prefix_cacheable_groups, KVCacheBlocks.get_block_ids, MooncakeStoreScheduler.init, MooncakeStoreScheduler.update_state_after_alloc, MooncakeStoreScheduler._apply_current_save_block_ids, MooncakeStoreScheduler.register_finished_partial_tail, MooncakeStoreScheduler._handle_boundary_state_offloads, MooncakeStoreConnector._validate_kv_cache_config, MooncakeStoreWorker.register_kv_caches, mooncake_store_group_ids

关键源码片段

vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/scheduler.py

核心逻辑改造：引入 store group 投影与重映射，所有调度器路径（取块、保存、边界状态）都只处理 prefix-cacheable 组，是修复的主战场。

class MooncakeStoreScheduler:
    """调度器侧组件：把可存储的 KV block 投影进 MooncakeStore。
​
    与 NIXL 等连接器不同，MooncakeStore 只处理 prefix-cacheable 的 group：
    QSA ring 这类 scratch 缓存可传输但不可 hash 寻址存储，必须被跳过。
    """
​
    def __init__(self, vllm_config: VllmConfig, kv_cache_config: KVCacheConfig):
        ...
        self.kv_cache_config = kv_cache_config
        # 仅保留可参与 hash 寻址存储的 transfer group；
        # QSA ring（CircularBufferSpec.prefix_cacheable=False）不在此列，
        # 从而避免其 4/8 的小容量进入只面向 block size 800 的 divisibility check。
        self._store_group_ids = kv_cache_config.prefix_cacheable_group_ids
        # 建立「调度器 group ID -> store group 索引」映射。
        # 不在投影内的 group 不在映射中，后续会被跳过且不造成 store group ID 偏移。
        self._store_group_id_by_kv_cache_group_id = {
            group_id: store_group_id
            for store_group_id, group_id in enumerate(self._store_group_ids)
        }
        store_groups = kv_cache_config.prefix_cacheable_groups
​
        # 在 store 投影上解析 Mamba group，只有 "align" 模式的边界状态
        # 才由 MooncakeStore 存储；不再依赖全局 block_size 做间接推断。
        mamba_groups = {
            group_id: group.kv_cache_spec
            for group_id, group in enumerate(store_groups)
            if isinstance(group.kv_cache_spec, MambaSpec)
        }
        assert all(
            spec.mamba_cache_mode == "align" for spec in mamba_groups.values()
        ), "MooncakeStoreScheduler requires mamba_cache_mode='align'"
        self._boundary_state_group_ids = frozenset(mamba_groups)
        ...
​
    def update_state_after_alloc(self, request, blocks, num_external_tokens):
        ...
        local_block_ids: tuple[list[int], ...] = ()
        if num_external_tokens > 0:
            # 直接按 store 投影取块 ID，避免先取全量块表再二次投影；
            # 这是扩展 KVCacheBlocks.get_block_ids(group_ids=...) 的原因。
            local_block_ids = blocks.get_block_ids(
                group_ids=self._store_group_ids,
            )
        ...

评论区精华

review 主要由维护者 ivanium 主导，核心交锋围绕接口设计与抽象层次：

• ivanium 建议将新属性命名为 prefix_cacheable_transfer_group_ids 以强调与 transfer 投影的从属关系，最终未采纳，保留了 prefix_cacheable_group_ids。
• ivanium 认为 coordinator 的 mooncake_store_group_ids 过度抽象（"This feels a bit overly abstracted"），后续 head commit 以 refactor 形式移除了 connector-local helper，直接用 KVCacheConfig 投影。
• ivanium 对 worker 中 store_layer_names 过滤提出疑问（"Not sure if we really need this"），作者 zhewenl 明确回应 "We still need this, otherwise non-cacheable groups like QSA ring will still be registered"，该过滤被保留并新增测试锁定。
• ivanium 建议扩展 KVCacheBlocks.get_block_ids(group_ids=...) 并考虑移除 kv_cache_config.select_block_ids() 接口，这一建议被完整采纳，成为最终 API 形态。

• ivanium 批准时留下未尽事宜："Overall good but I have an ask on interface design. I'll still approve to unblock."，指向 select_transfer_block_ids 与 get_block_ids(group_ids=...) 的职责划分仍可继续收敛。

• KVCacheConfig 新属性命名：prefix_cacheable_group_ids vs prefix_cacheable_transfer_group_ids (design): 重命名建议未采纳，最终保留 prefix_cacheable_group_ids；ivanium 在批准时表示 "Overall good but I have an ask on interface design. I'll still approve to unblock."

• coordinator 的 mooncake_store_group_ids helper 是否过度抽象 (design): head commit 59f6056 以 refactor 形式移除 connector-local helper，直接使用 KVCacheConfig 投影；coordinator 侧函数是否进一步内联未见后续讨论。
• worker 注册 KV cache 时 store_layer_names 过滤是否必要 (correctness): 过滤被保留，并新增 test_register_kv_caches_excludes_nonprefix_cacheable_layers 验证 QSA 层不进入注册。
• 扩展 KVCacheBlocks.get_block_ids 而非新增 select_block_ids 接口 (design): 建议被完整采纳：最终实现正是 get_block_ids 的 keyword-only group_ids 参数，MooncakeStore 各调用点直接传入 _store_group_ids。
• 是否移除 transfer 投影相关通用接口 (design): PR body 明确 "This deliberately does not change transfer_group_ids, transfer_groups, or select_transfer_block_ids"，NIXL 等连接器继续使用 transfer 投影，接口未移除；属于遗留的后续演进方向。

风险与影响

• 风险：共享 API 变更：KVCacheConfig 新增属性、KVCacheBlocks.get_block_ids 新增 keyword-only 参数属于向后兼容扩展，但任何对 KVCacheBlocks.get_block_ids 返回元组长度的外部假设都可能受影响，需要依赖全量 CI 回归（本 PR 已跑 412 单测 + NIXL HMA 77 用例）。
  异构 group 属性契约依赖：QSA ring 的排除依赖 kv_cache_spec.prefix_cacheable 在各 spec（CircularBufferSpec、MambaSpec、FullAttentionSpec 等）上的取值正确性；若未来新增 spec 漏设该属性，可能重新落入 divisibility check 崩溃。
  Mamba 校验行为变化：connector.py 的校验从 block_size 比对改为 mamba_cache_mode != "align" 直接拒绝，语义更准确，但可能放行此前因 block_size 恰巧相等而未被拦截的非 align 配置，属于行为面变化。
  分布式一致性依赖：scheduler 与 worker 必须使用同一投影（_store_group_ids vs _kv_cache_groups），PR 通过 prefix_cacheable_groups 单源保证；MultiConnector 混用场景下若子连接器 group 布局不一致，可能导致 store group ID 错位。
  NIXL 等路径需回归验证：本 PR 特意不改 transfer_group_ids，但 KVCacheBlocks.get_block_ids 行为扩展与调度器调用点变化可能间接影响共享路径，NIXL HMA 77 用例已覆盖，长期建议持续关注。

• 影响：用户侧：MooncakeStoreConnector + 混合注意力模型（Qwen3.8-Flash-Next、带 QSA/Mamba 的模型）的启动崩溃被修复；纯 full-attention 用户无行为变化，因为投影退化为全量 transfer 组。
  系统侧：MooncakeStore 的 hash/store/lookup 布局只包含 prefix-cacheable 组，减少无效存储与误命中；QSA ring 仍被 NIXL 传输，P/D 分离场景语义保持。
  团队侧：接口设计讨论（命名、抽象层次、是否移除 select_transfer_block_ids）留下后续演进方向，KVCacheBlocks.get_block_ids(group_ids=...) 成为新的通用投影入口。

• 风险标记：共享缓存 API 变更, 异构 group 属性契约依赖, Mamba 校验行为变化, 分布式一致性依赖, NIXL 路径需回归验证

关联脉络

• PR #56645 [NIXL][PCP][DCP] Expose PCP producer KV shards as transfer ranks: 同为 kv-connector 的 group/rank 投影演进，牵涉 transfer_groups 概念与 connector/scheduler/worker 多文件改造，与本 PR 的「transfer 投影 vs store 投影」分层设计相互补充。
• PR #50388 [Core] Fix ValueError on KV load failure with a hybrid KV cache: 混合 KV 缓存下 scheduler 与 kv-connector 加载失败恢复，与异构 group 的运行时一致性相关，说明混合 KV cache 语义是近期持续修复重点。
• PR #56305 [Attention] Add Triton/FlashInfer composite for multimodal prefix attention: 多模态 prefix attention 与 QSA/复合注意力机制相关，是本 PR 中 QSA ring 场景的上游功能线。
• PR #56715 [Bugfix][PCP][DCP] Respect interleave in indexer KV gather mapping: 同为 KV 索引/group 语义修正（PCP/DCP indexer），说明 group 语义与索引映射的缺陷修复在持续进行。