执行摘要

• 一句话：提取 KV 缓存池构建逻辑至 KVCacheConfigurator，删除 mixin
• 推荐动作：值得精读，尤其是大规模的机械提取方法和模块解耦思路；合并前需修复 _PoolSizes 的 msgspec 问题；后续应补充各架构 pool 构建的单独测试。

功能与动机

将 KV 缓存配置逻辑从庞大的 ModelRunner 中分离，使每个池构建函数可独立测试和验证，并为后续进一步模块化做好准备。引用 PR body: 'Stage req-pool branches for certifiable extraction' 等。

实现拆解

1. 准备阶段：消除 walrus 绑定（如 config := self.mambaish_config 改为直接使用 self.mambaish_config）、内联局部变量（如 max_spec_draft_tokens 直接引用 self.server_args.max_speculative_num_draft_tokens），使每个架构分支成为可独立提取的代码块。
2. 提取 pool builder 方法：将 _init_pools 中的每个架构分支（MHA、MLA、DSA、FP4、Hybrid、DSV4、Ascend 等）提取为独立的 _build_* 方法（超过 20 个），如 _build_mha_kv_pool、_build_mla_kv_pool 等，涉及 kv_cache_configurator.py。
3. 引入 _PoolSizes 数据类：提取 _derive_pool_sizes 方法，将原本分散的 9 个池大小参数封装为 _PoolSizes 数据类，作为 _init_pools 的单一参数传递，简化方法签名。
4. 溶解 init_memory_pool：将 ModelRunnerKVCacheMixin.init_memory_pool 内联到 ModelRunner.alloc_memory_pool 中，直接调用 self.kv_cache_configurator.configure(...) 并展开结果赋值。
5. 删除空壳 mixin：移除 ModelRunnerKVCacheMixin 文件和继承关系，更新 model_runner.py 的导入；同时调整 pool_configurator.py 中 DefaultPoolConfigurator 等类的构造器参数从 ModelRunner 改为 KVCacheConfigurator。
6. 测试配套：在 test_pool_configurator.py 中为模拟的 ModelRunner 补充 layer_info、ps、pp_group、spec_aux_config 等字段，适配新的依赖接口。

关键文件：

• python/sglang/srt/mem_cache/kv_cache_configurator.py（模块 KV缓存配置；类别 source；类型 core-logic；符号 _PoolSizes, layer_info, post_init, _derive_pool_sizes）: 核心变更文件，集中了所有 pool 构建方法提取、_PoolSizes 数据类引入和 post_init 派生架构配置。
• python/sglang/srt/model_executor/pool_configurator.py（模块 池配置器；类别 source；类型 data-contract；符号 init, _compute_cell_size, is_applicable）: 修改 DefaultPoolConfigurator 等类的构造器从接受 ModelRunner 改为 KVCacheConfigurator，解耦依赖。
• python/sglang/srt/model_executor/model_runner_kv_cache_mixin.py（模块 废弃Mixin；类别 source；类型 deletion；符号 ModelRunnerKVCacheMixin, init_memory_pool）: 整个文件被删除，所有功能已迁移至 KVCacheConfigurator 和 ModelRunner。
• python/sglang/srt/model_executor/model_runner.py（模块 模型运行器；类别 source；类型 data-contract；符号 ModelRunner）: 移除对 ModelRunnerKVCacheMixin 的继承和导入，将 init_memory_pool 内联，并在 alloc_memory_pool 中直接调用 KVCacheConfigurator.configure。
• test/registered/unit/model_executor/test_pool_configurator.py（模块 池配置测试；类别 test；类型 test-coverage）: 适配测试：为 Mock ModelRunner 添加 layer_info、ps、spec_aux_config 等字段，支持新的 pool_configurator 接口。

关键符号：_derive_pool_sizes, _init_pools, configure, post_init, _compute_cell_size, init_memory_pool, alloc_memory_pool

关键源码片段

python/sglang/srt/mem_cache/kv_cache_configurator.py

核心变更文件，集中了所有 pool 构建方法提取、_PoolSizes 数据类引入和 post_init 派生架构配置。

# kv_cache_configurator.py (head) - _PoolSizes 与 KVCacheConfigurator.__post_init__
​
# 警告：使用 msgspec.Struct 包含 torch.dtype 字段会导致导入时 TypeError，
# 应改用 @dataclass（参见 review 评论）。
class _PoolSizes(msgspec.Struct, frozen=True, kw_only=True):
    """封装所有池大小参数的数据类"""
    max_total_num_tokens: int
    max_running_requests: int
    full_max_total_num_tokens: Optional[int]
    swa_max_total_num_tokens: Optional[int]
    c4_max_total_num_tokens: int
    c128_max_total_num_tokens: int
    c4_state_pool_size: int
    c128_state_pool_size: int
    c4_state_dtype: Optional[torch.dtype] # 高风险：msgspec 不支持 torch.dtype
    c128_state_dtype: Optional[torch.dtype]
​
@dataclass(slots=True, kw_only=True)
class KVCacheConfigurator:
    # ... 字段省略 ...
    # 由 __post_init__ 派生的字段
    mambaish_config: Optional[Any] = field(init=False)
    hybrid_gdn_config: Optional[Any] = field(init=False)
​
    def __post_init__(self) -> None:
        """派生架构配置，避免构造器参数爆炸"""
        self.mambaish_config = mambaish_config(self.model_config)
        self.hybrid_gdn_config = hybrid_gdn_config(self.model_config)
​
    def _derive_pool_sizes(self, ...) -> _PoolSizes:
        # 计算最大 tokens、请求数、状态池大小等，返回 _PoolSizes 实例
        ...

python/sglang/srt/model_executor/pool_configurator.py

修改 DefaultPoolConfigurator 等类的构造器从接受 ModelRunner 改为 KVCacheConfigurator，解耦依赖。

# pool_configurator.py (head) - DefaultPoolConfigurator 构造器变更
​
class DefaultPoolConfigurator(MemoryPoolConfigurator):
    """Configurator for standard models: MHA, MLA, DSA, FP4."""
​
    def __init__(self, kvc: KVCacheConfigurator):
        # 参数从 mr 改为 kvc，解耦依赖
        if mambaish := mambaish_config(kvc.model_config):
            effective_layer_ids = [
                i
                for i in mambaish.full_attention_layer_ids
                if kvc.layer_info.start_layer <= i < kvc.layer_info.end_layer
            ]
            num_layers = len(effective_layer_ids)
        else:
            num_layers = kvc.layer_info.num_effective_layers
​
        self._cell_size = self._compute_cell_size(kvc, num_layers)
​
        # EAGLE/STANDALONE 缩放 cell_size
        if (
            kvc.spec_algorithm.is_eagle() or kvc.spec_algorithm.is_standalone()
        ) and not kvc.is_draft_worker:
            eagle_draft_num_layers = kvc.spec_aux_config.eagle_draft_num_layers
            if (
                eagle_draft_num_layers is not None
                and int(eagle_draft_num_layers) > 0
                and int(num_layers) > 0
            ):
                self._cell_size = int(
                    self._cell_size
                    * (1 + int(eagle_draft_num_layers) / int(num_layers))
                )
        # DFLASH/DSPARK 缩放类似
        ...

评论区精华

Review 评论（gemini-code-assist[bot]）指出 _PoolSizes 使用 msgspec.Struct 包含 torch.dtype 字段会导致 TypeError（msgspec 不支持任意第三方类型），建议改用标准 @dataclass。该问题在合并时尚未修复，属于已知待修复 bug。

• _PoolSizes 使用 msgspec.Struct 导致 torch.dtype 无法序列化 (correctness): 建议改用 @dataclass，但 PR 已合并，尚未修复，属于已知 bug。

风险与影响

• 风险：主要风险：_PoolSizes 使用 msgspec.Struct 导致导入崩溃（高优先级，见 review 评论）；大量机械提取可能引入回归，需验证各架构分支行为不变；pool_configurator 接口变动影响所有调用方（目前仅 ModelRunner 一处调用）。
• 影响：对用户无影响（零功能变化）；对开发者，代码模块化提升可维护性，但需注意 _PoolSizes 的类型错误；测试仅覆盖 DefaultPoolConfigurator，其他架构分支的 pool 构建缺少独立测试。
• 风险标记：msgspec 类型错误, 核心路径重构, 接口依赖变动

关联脉络

• PR #31169 Split initialize() into orchestration helpers: 同属于 ModelRunner 解耦重构系列，逐步拆分 initialize() 方法。
• PR #31168 Extract cuda-graph setup into a module: 将 CUDA graph 捕获逻辑提取为模块，同样涉及 ModelRunner 解耦。
• PR #31167 Extract attention-backend setup into a module: 将注意力后端设置提取为模块，与 PR#31163 同属 ModelRunner 重构波次。
• PR #31166 Narrow component dependencies to injected fields instead of ModelRunner: 解耦组件对 ModelRunner 的依赖，为后续模块提取铺路。
• PR #31165 Drop ModelRunner's duplicated parallel-degree fields and read them via self.ps: 移除 ModelRunner 中重复字段，统一通过 ps 访问，与当前 PR 的清理目标一致。