执行摘要

• 一句话：简化 HiCache 构建栈函数，移除冗余参数
• 推荐动作：值得精读，特别是如何通过引入参数对象（CacheInitParams）简化多参数函数的设计模式。对于维护 HiCache 模块的开发者具有参考意义。

功能与动机

在 #27010 中发现 main 分支代码在构建缓存控制器时未传递 pp_group 给 CacheController，根本原因是函数参数过多导致遗漏。本 PR 通过移除冗余参数，使用 CacheInitParams 集中管理上下文参数，降低调用错误风险。

实现拆解

1. 在 hybrid_pool_assembler.py 中，修改 build_kv_only_stack、build_hybrid_swa_stack、build_deepseek_v4_hicache_stack 等函数，移除 page_size、tp_group、attn_cp_group、attn_tp_group、pp_group 等冗余参数，改为从传入的 params: CacheInitParams 对象中读取（如 params.page_size、params.tp_cache_group 等）。
2. 在 hiradix_cache.py 的 HiRadixCache.__init__ 中，移除对 attach_hybrid_dsa_pool_to_hiradix_cache 和 attach_hybrid_minimax_sparse_pool_to_hiradix_cache 调用时额外传入的 attn_cp_group 和 attn_tp_group 参数，因为这些值已在 params 中。
3. 在 hi_mamba_radix_cache.py 的 HiMambaRadixCache.__init__ 中，移除对 attach_hybrid_pool_to_mamba_cache 调用时传入的 attn_cp_group 和 attn_tp_group 参数。
4. 在 unified_radix_cache.py 的 init_hicache 中，移除对 attach_hybrid_pool_to_unified_cache 调用时传入的 attn_cp_group 和 attn_tp_group 参数。
   没有测试文件变更，但作者提供了手动运行 GLM-5.2 和 DSv4 的缓存命中率测试结果验证功能正常。

关键文件：

• python/sglang/srt/mem_cache/hybrid_cache/hybrid_pool_assembler.py（模块 缓存层；类别 source；类型 core-logic；符号 build_kv_only_stack, build_hybrid_swa_stack, build_deepseek_v4_hicache_stack, attach_hybrid_pool_to_unified_cache）: 核心重构文件，移除多个函数（build_kv_only_stack、build_hybrid_swa_stack、build_deepseek_v4_hicache_stack 等）的冗余参数，使用 CacheInitParams 统一获取分布式上下文和页面大小，大幅简化函数签名（-142 行）。
• python/sglang/srt/mem_cache/hiradix_cache.py（模块 缓存层；类别 source；类型 core-logic；符号 HiRadixCache.init）: 移除了对 attach_hybrid_dsa_pool_to_hiradix_cache 和 attach_hybrid_minimax_sparse_pool_to_hiradix_cache 调用时多余的 attn_cp_group 和 attn_tp_group 参数，因为这些值现在由内部从 params 获取。
• python/sglang/srt/mem_cache/hi_mamba_radix_cache.py（模块 缓存层；类别 source；类型 core-logic；符号 HiMambaRadixCache.init）: 移除对 attach_hybrid_pool_to_mamba_cache 调用时额外的 attn_cp_group 和 attn_tp_group 参数。
• python/sglang/srt/mem_cache/unified_radix_cache.py（模块 缓存层；类别 source；类型 core-logic；符号 UnifiedRadixCache.init_hicache）: 移除 init_hicache 中对 attach_hybrid_pool_to_unified_cache 调用时多余的 attn_cp_group 和 attn_tp_group 参数。

关键符号：build_kv_only_stack, build_hybrid_swa_stack, build_deepseek_v4_hicache_stack, attach_hybrid_pool_to_unified_cache, attach_hybrid_pool_to_mamba_cache, attach_hybrid_dsa_pool_to_hiradix_cache, attach_hybrid_minimax_sparse_pool_to_hiradix_cache, HiRadixCache.init, HiMambaRadixCache.init, UnifiedRadixCache.init_hicache

关键源码片段

python/sglang/srt/mem_cache/hybrid_cache/hybrid_pool_assembler.py

核心重构文件，移除多个函数（build_kv_only_stack、build_hybrid_swa_stack、build_deepseek_v4_hicache_stack 等）的冗余参数，使用 CacheInitParams 统一获取分布式上下文和页面大小，大幅简化函数签名（-142 行）。

# 简化后的 build_kv_only_stack：不再接收 page_size、tp_group 等独立参数，
# 全部从 params 对象获取。
def build_kv_only_stack(
    *,
    params: CacheInitParams, # 通过 params 获取 page_size、tp_group 等
    server_args: ServerArgs,
    kv_pool: Any,
    full_layer_mapping: dict[int, int],
    load_cache_event,
    storage_backend: Optional[str],
    use_mla: bool,
    override_kv_cache_dim: Optional[int] = None,
    prefetch_threshold: int = 256,
    model_name: Optional[str] = None,
    storage_backend_extra_config: Optional[dict] = None,
    enable_storage_metrics: bool = False,
) -> tuple[HostPoolGroup, HybridCacheController]:
    transfer_layer_num = len(full_layer_mapping)
    # 之前需要独立 page_size 参数，现在使用 params.page_size
    kv_host_pool = build_kv_host_pool(
        kv_pool=kv_pool,
        page_size=params.page_size,
        server_args=server_args,
        use_mla=use_mla,
        override_kv_cache_dim=override_kv_cache_dim,
    )
    entries = [
        build_pool_entry(
            name=PoolName.KV,
            host_pool=kv_host_pool,
            device_pool=kv_pool,
            layer_mapping=full_layer_mapping,
            transfer_layer_num=transfer_layer_num,
            is_anchor=True,
        )
    ]
    host_pool_group = HostPoolGroup(entries)
    # 之前需要独立 tp_group、attn_cp_group、attn_tp_group、pp_group，
    # 现在全部从 params 的相应属性获取
    cache_controller = HybridCacheController(
        params.token_to_kv_pool_allocator,
        host_pool_group,
        params.page_size,
        params.tp_cache_group,
        load_cache_event=load_cache_event,
        attn_cp_group=params.attn_cp_cache_group,
        attn_tp_group=params.attn_tp_cache_group,
        pp_group=params.pp_cache_group,
        write_policy=server_args.hicache_write_policy,
        io_backend=server_args.hicache_io_backend,
        storage_backend=storage_backend,
        prefetch_threshold=prefetch_threshold,
        model_name=model_name,
        storage_backend_extra_config=storage_backend_extra_config,
        transfer_layer_num=transfer_layer_num,
        enable_storage_metrics=enable_storage_metrics,
    )
    return host_pool_group, cache_controller

评论区精华

主要讨论来自 gemini-code-assist[bot] 的两个评论，指出 hiradix_cache.py 中对 attach_hybrid_dsa_pool_to_hiradix_cache 和 attach_hybrid_minimax_sparse_pool_to_hiradix_cache 的调用可能缺少必需的 extra_config 参数。但作者 stepinto 回复澄清，实际调用中已在 extra_config=extra_config 传入，bot 的审查使用了过期快照。最终无实质性争议，评审者 hzh0425 批准合并。

• extra_config 参数是否丢失 (correctness): 作者 stepinto 回应实际调用中已包含 extra_config=extra_config，bot 使用了过期的 diff 快照。问题已澄清，无需修改。

风险与影响

• 风险：风险较低。仅为参数封装重构，无逻辑变更。但需确认所有调用路径均使用正确的参数来源。hiradix_cache.py 中的 DSA 和 MiniMaxSparse 分支的调用在重构后可能依赖 extra_config 参数的存在，但作者确认已传递。由于未变更测试，若其他缓存类型分支（如 DSA、MiniMaxSparse）的缓存控制器构造参数有差异，可能引入兼容性问题。但通过手动测试覆盖了主要场景。
• 影响：影响范围限于 HiCache 子系统内的函数签名和调用点。开发者在调用 build_xxx_stack、attach_hybrid_pool_to_unified_cache 等函数时不再需要传递大量分布式上下文参数，只需传入 params 对象即可，降低了使用门槛和出错概率。对系统运行时无性能影响。
• 风险标记：无新增测试覆盖, 低频分支兼容性（DSA、MiniMaxSparse）

关联脉络

• PR #27010 Undisclosed: 本 PR 的动机和修复来源于 #27010 中发现的参数缺失问题。