# PR #31308 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[HiCache] Remove redundant parameters of build_xxx_stack and others
- 合并时间：2026-07-21 17:54
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/31308

---

# 执行摘要

- 一句话：简化 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 行）。

```python
# 简化后的 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 中发现的参数缺失问题。