执行摘要

• 一句话：修复 EAGLE+SWA 前缀缓存掩码丢失 lookahead 块
• 推荐动作：值得所有关注 vLLM 前缀缓存和推测解码的开发者精读。特别是设计权衡：如何在保留优化收益的同时修复边界情况，以及如何通过共享逻辑确保掩码与查找同步。此外，SpecGroup 的引入为后续多 spec 组管理提供了更清晰的数据结构。

功能与动机

当 EAGLE/MTP 推测解码与 SWA 前缀缓存同时使用时，因为掩码跳过了对齐段边界后的第一个块（即 EAGLE 所需的 lookahead 块），导致 EAGLE 查找无法找到连续缓存块，完全失效。该问题在 #42258 优化引入后暴露，影响所有使用 EAGLE + SWA 的模型（如 DeepSeek-V4）。

实现拆解

1. 提取共享逻辑：在 SlidingWindowManager 中新增 _contiguous_blocks_for_hit 类方法，计算每个对齐段内可用于命中的连续块数（need），被掩码生成和查找逻辑共用。
2. 重写缓存掩码：将 _cache_block_mask 更名为 reachable_block_mask，并改为类方法。当 use_eagle=True 时，在每个对齐段右边界上扩展一个块（即 shift=1），使得 EAGLE 的 lookahead 块能够被缓存。非 EAGLE 组行为不变。
3. 扩展缓存范围：在 HybridKVCacheCoordinator.cache_blocks 中，若当前管理器组属于 EAGLE 组，则将缓存的 token 数扩展一个块长度，确保 lookahead 块确实写入前缀缓存哈希映射。
4. 引入 SpecGroup：新增 SpecGroup NamedTuple，携带 use_eagle 标志，替换原来的 eagle_attn_group_indices 集合，并在混合定点循环中正确传递 drop_eagle_block 参数。
5. 参数重命名：将 find_longest_cache_hit 的 use_eagle 参数重命名为 drop_eagle_block，以清晰区分“该组使用 EAGLE”（管理器属性）与“本次查找是否丢弃最后一块”（每次传递决策）。
6. 测试配套：新增三个回归测试 test_eagle_swa_alignment_caches_extra_block、test_eagle_swa_boundary_caches_post_boundary_block、test_eagle_grouped_swa_siblings_use_same_cache_mask，覆盖 EAGLE+SWA 组合下的边界情况。

关键文件：

• vllm/v1/core/single_type_kv_cache_manager.py（模块 缓存管理器；类别 source；类型 core-logic；符号 _cache_block_mask, reachable_block_mask, _contiguous_blocks_for_hit, find_longest_cache_hit）: 核心 bug 修复：重新设计缓存掩码逻辑，新增共享计算函数，确保 EAGLE lookahead 块不被跳过。
• vllm/v1/core/kv_cache_coordinator.py（模块 协调器；类别 source；类型 core-logic；符号 SpecGroup, HybridKVCacheCoordinator.cache_blocks, HybridKVCacheCoordinator.verify_and_split_kv_cache_groups, find_longest_cache_hit）: 引入 SpecGroup 命名元组，替换 eagle_attn_group_indices，并调整缓存和查找逻辑以支持按组传递 use_eagle。
• tests/v1/core/test_prefix_caching.py（模块 前缀缓存测试；类别 test；类型 test-coverage；符号 test_eagle_swa_alignment_caches_extra_block, test_eagle_swa_boundary_caches_post_boundary_block, test_eagle_grouped_swa_siblings_use_same_cache_mask）: 新增三个回归测试，覆盖 EAGLE+SWA 的关键场景，确保 fix 有效且无回归。
• vllm/distributed/kv_transfer/kv_connector/v1/mooncake/store/coordinator.py（模块 分布式缓存；类别 source；类型 core-logic；符号 _find_hit_blocks）: 跟随主仓库参数重命名（use_eagle -> drop_eagle_block），保持接口一致。
• tests/v1/core/test_single_type_kv_cache_manager.py（模块 缓存管理器测试；类别 test；类型 test-coverage）: 跟随参数重命名调整测试中的参数名，保持测试通过。

关键符号：_contiguous_blocks_for_hit, reachable_block_mask, SpecGroup, HybridKVCacheCoordinator.cache_blocks, find_longest_cache_hit

关键源码片段

vllm/v1/core/kv_cache_coordinator.py

引入 SpecGroup 命名元组，替换 eagle_attn_group_indices，并调整缓存和查找逻辑以支持按组传递 use_eagle。

# vllm/v1/core/kv_cache_coordinator.py
​
class SpecGroup(NamedTuple):
    """表示共享同一 KVCacheSpec 的一组 KV cache 组。
​
    ``use_eagle`` 为 True 当且仅当组内任意成员是 EAGLE/MTP 组。
    同一 spec 的组共享缓存命中查找，因此 EAGLE 最后块丢弃对该组统一。
    """
​
    spec: KVCacheSpec
    group_ids: list[int]
    manager_cls: type[SingleTypeKVCacheManager]
    use_eagle: bool
​
# 在 HybridKVCacheCoordinator 中：
def cache_blocks(
    self,
    request: Request,
    num_tokens: int,
    alignment_tokens: int | None = None,
) -> None:
    # ...
    for group in self.attention_groups:
        if group.use_eagle and alignment_tokens is not None:
            # EAGLE 组需要额外缓存一个 lookahead 块
            effective_num_tokens = num_tokens + alignment_tokens
        else:
            effective_num_tokens = num_tokens
        for gid in group.group_ids:
            self.single_type_managers[gid].cache_blocks(
                request,
                effective_num_tokens,
                alignment_tokens=alignment_tokens,
            )

评论区精华

Review 中主要讨论了 drop_eagle 参数的命名。wzhao18 认为 drop_eagle 不如 use_eagle 直观，ivanium 解释：use_eagle 作为管理器实例属性表示该组是否使用 EAGLE，而 drop_eagle_block 是查找传递中的决策参数，即使在 EAGLE 组中也可能为 False（例如在收敛循环中已经丢弃过）。wzhao18 接受并建议进一步重命名为 drop_eagle_block 并添加注释说明。该建议被采纳。

• 参数命名 drop_eagle 与 use_eagle 的区分 (design): wzhao18 接受解释，并建议进一步重命名为 drop_eagle_block 并添加注释。ivanium 在后续提交中采纳。

风险与影响

• 风险：主要风险在于非 EAGLE 场景下的回归：因为重构了共享逻辑，若 _contiguous_blocks_for_hit 计算有误，可能导致非 EAGLE 的 SWA 缓存行为改变。另外，引入 SpecGroup 替换了 eagle_attn_group_indices，可能影响其他使用该集合的代码路径（如 MooncakeStoreConnector），但 PR 已注明 Mooncake 需后续修复。性能风险较低，因为额外缓存的块仅限每个对齐段一个块，开销可控。
• 影响：影响使用 EAGLE/MTP 推测解码与 SWA（如 DeepSeek-V4）的 v1 引擎用户。修复后 EAGLE 前缀缓存命中恢复正常，显著提升此类场景的生成吞吐。非 EAGLE 用户不受影响。对系统其他部分（如分布式 KV 传输）有轻微 API 调整（参数重命名），但功能等价。
• 风险标记：核心缓存逻辑变更, 与非 EAGLE 路径交互, 掩码与查找同步风险, 分布式连接器需后续适配

关联脉络

• PR #42258 [Core][DSV4] Skip caching SWA blocks that can never serve a prefix-cache hit: 本 PR 修复的 bug 是由 #42258 引入的优化所导致，同时本 PR 保留了其优化收益。
• PR #42784 [Bugfix] Disable SWA cache mask when EAGLE is active: 也是针对同一问题的修复，但通过完全禁用 SWA 缓存掩码，牺牲了 #42258 的优化；本 PR 提供了更精确的修复。PR 描述中提及并比较了两种方案。