执行摘要

• 一句话：提取 ModelRunner 中六个叶子辅助函数到独立模块
• 推荐动作：建议阅读此 PR 的提交序列，学习"机械可验证"（mechanically provable）的安全重构步骤：先预处理调用点，再移动代码，最后更新导入。该方法适用于任何需要从大对象中提取职责的场景，可作为团队重构规范参考。

功能与动机

继续拆分庞大且职责过重的 ModelRunner 类，将纯工具性质的静态方法移到与其职责匹配的模块中，减少单文件复杂度、促进代码复用，并为后续组件化奠定基础。PR body 的提交链明确遵循了"预处理（转换为 @staticmethod 并调整调用点）→ 移动（cut+paste）→ 后处理（更新导入路径）"的安全重构步骤。

实现拆解

1. 预处理每个目标方法：在每个方法前将其转换为 @staticmethod，并调整同文件内调用点为类限定形式（如 self.init_cublas() → ModelRunner.init_cublas()），确保提取后调用链不中断。

2. 逐函数移动：将每个函数从 ModelRunner 剪切粘贴到目标模块：

   • init_cublas → python/sglang/srt/utils/common.py
   • apply_torch_tp → python/sglang/srt/layers/model_parallel.py
   • init_threads_binding → python/sglang/srt/utils/numa_utils.py
   • prealloc_symmetric_memory_pool → python/sglang/srt/distributed/device_communicators/pynccl_allocator.py
   • resolve_language_model → python/sglang/srt/model_loader/utils.py
   • _build_step_span_name 原地重命名为 build_step_span_name，再移动到 utils/profile_utils.py

3. 内联 _build_model_config：该函数仅转发到 ModelConfig.from_server_args，直接在两处调用点内联函数调用，并删除该私有方法。

4. 更新导入关系：在 model_runner.py 中删除旧的局部导入并添加模块级导入（如 from sglang.srt.layers import model_parallel），其余模块根据需要补充缺失的导入。

5. 保留包装方法：对于 init_threads_binding 和 apply_torch_tp，在 ModelRunner 中保留同名的包装方法，内部调用已移动到模块的函数（通过模块导入路由），确保外围调用点不变。

关键文件：

• python/sglang/srt/model_executor/model_runner.py（模块 核心调度；类别 source；类型 data-contract；符号 resolve_language_model, _build_model_config, init_cublas, prealloc_symmetric_memory_pool）: 核心变更文件，移除 6 个函数并更新导入，减少代码量 109 行，体现了整个 PR 的入口与出口。
• python/sglang/srt/utils/numa_utils.py（模块 工具函数；类别 source；类型 core-logic；符号 init_threads_binding）: 接收了 init_threads_binding 函数，新增 41 行核心 NUMA 绑定逻辑，增强该模块的工具性。
• python/sglang/srt/distributed/device_communicators/pynccl_allocator.py（模块 通信器；类别 source；类型 core-logic；符号 prealloc_symmetric_memory_pool）: 接收了 prealloc_symmetric_memory_pool 函数，集中管理对称内存池预分配逻辑。
• python/sglang/srt/layers/model_parallel.py（模块 并行层；类别 source；类型 data-contract；符号 apply_torch_tp）: 接收了 apply_torch_tp 函数，丰富了该模块的 TP 封装能力。
• python/sglang/srt/model_loader/utils.py（模块 模型加载；类别 source；类型 data-contract；符号 resolve_language_model）: 接收了 resolve_language_model，统一模型语言模型子模块的解析逻辑。
• python/sglang/srt/utils/profile_utils.py（模块 性能分析；类别 source；类型 core-logic；符号 build_step_span_name）: 接收了 build_step_span_name，用于 profiling span 命名。
• python/sglang/srt/utils/common.py（模块 工具函数；类别 source；类型 core-logic；符号 init_cublas）: 接收了 init_cublas，统一 cuBLAS 初始化。
• python/sglang/srt/layers/quantization/fp4_kv_cache_quant_method.py（模块 量化层；类别 source；类型 dependency-wiring）: 导入调整：将依赖从 model_runner.py 迁移到新模块，属于基础设施适配。

关键符号：init_cublas, apply_torch_tp, init_threads_binding, prealloc_symmetric_memory_pool, resolve_language_model, build_step_span_name

关键源码片段

python/sglang/srt/utils/numa_utils.py

接收了 init_threads_binding 函数，新增 41 行核心 NUMA 绑定逻辑，增强该模块的工具性。

# python/sglang/srt/utils/numa_utils.py (head)
​
def init_threads_binding(
    *,
    tp_rank: int,
    tp_size: int,
) -> str:
    """
    根据 TP rank 和 size 计算当前进程应绑定的 CPU 核集合（通过环境变量 SGLANG_CPU_OMP_THREADS_BIND）。
    返回一个 CPU ID 列表字符串（如 "0-31"），用于设置 OMP 线程亲和性。
    """
    omp_cpuids = os.environ.get("SGLANG_CPU_OMP_THREADS_BIND", "all")
    cpu_ids_by_node = get_cpu_ids_by_node()
    n_numa_node = len(cpu_ids_by_node)
​
    if omp_cpuids == "all":
        # 默认行为：每个 TP rank 绑定一个完整的 NUMA 节点
        assert tp_size <= n_numa_node, (
            f"tp_size {tp_size} 不能大于 NUMA 节点数 {n_numa_node}；"
            "如需覆盖请设置 SGLANG_CPU_OMP_THREADS_BIND 环境变量"
        )
        if tp_size < n_numa_node:
            logger.warning(
                f"机器有 {n_numa_node} 个 NUMA 节点，但 tp_size 仅为 {tp_size}，"
                "将只使用前几个节点"
            )
        local_omp_cpuid = cpu_ids_by_node[tp_rank]
    else:
        # 用户显式指定，按 | 分割，每个 TP rank 对应一段
        threads_bind_list = omp_cpuids.split("|")
        assert tp_size == len(threads_bind_list), (
            f"SGLANG_CPU_OMP_THREADS_BIND 配置必须与 TP size ({tp_size}) 一致"
        )
        local_omp_cpuid = threads_bind_list[tp_rank]
        if tp_size > n_numa_node:
            logger.warning(
                f"TP size ({tp_size}) 大于 NUMA 节点数 ({n_numa_node})，"
                "需谨慎设置 max-total-tokens 以避免 OOM"
            )
​
    return local_omp_cpuid

python/sglang/srt/distributed/device_communicators/pynccl_allocator.py

接收了 prealloc_symmetric_memory_pool 函数，集中管理对称内存池预分配逻辑。

# python/sglang/srt/distributed/device_communicators/pynccl_allocator.py (head)
​
def prealloc_symmetric_memory_pool(
    *,
    is_draft_worker: bool,
    enable_symm_mem: bool,
    device: str,
    forward_stream: torch.cuda.Stream,
):
    """
    在确定性上下文中预分配一大块对称内存，
    避免 PyTorch 内存池在 OOM 场景下的碎片问题。
    只在实际 worker 且启用对称内存时执行。
    """
    if (
        is_draft_worker
        or not enable_symm_mem
        or envs.SGLANG_SYMM_MEM_PREALLOC_GB_SIZE.get() <= 0
    ):
        return
​
    from sglang.srt.distributed import get_tp_group
​
    # 分配必须在一个 CUDA stream 上进行，这里复用 forward stream
    with torch.get_device_module(device).stream(forward_stream):
        logger.info(
            f"预分配对称内存池 {envs.SGLANG_SYMM_MEM_PREALLOC_GB_SIZE.get()} GiB"
        )
        with use_symmetric_memory(get_tp_group()):
            # 实际触发分配的是这个空的 uint8 tensor
            torch.empty(
                (envs.SGLANG_SYMM_MEM_PREALLOC_GB_SIZE.get() * 1024 * 1024 * 1024,),
                dtype=torch.uint8,
                device=device,
            )

评论区精华

本 PR 没有收到任何 Review 评论，整个合并过程由作者基于机械可验证的提交链完成。相关决策已在同系列其他 PR 讨论中达成一致。

• 暂无高价值评论线程

风险与影响

• 风险：
  1. 导入遗漏：某些未在变更列表中的文件可能通过 self 调用了被提取的方法，若未更新会导致 AttributeError。本次变更已通过预处理阶段将所有内部调用点改为类限定形式，后续又改为模块导入，风险较低。
  2. 内联 _build_model_config：内联后两个调用点直接依赖 ModelConfig.from_server_args，若此构造函数签名发生变化需同步修改两处，增加维护成本。但由于该函数本是薄转发，影响可控。
  3. 跨后端兼容性：其他硬件后端（如 MLX、NPU）的 ModelRunner 子类也可能调用这些方法，本次未修改这些文件。通过检查调用链（如 build_step_span_name 在 profiling 中使用）确认未产生断裂。
     - 影响：用户/功能：无功能变化，用户无感知。系统：ModelRunner 的 import 依赖有所变化（减少了对 torch.nn、ForwardMode 的直接导入），未来新增辅助函数更容易放入对应模块。团队：代码结构更清晰，各工具模块可独立测试和复用，降低后续重构的冲突概率。
     - 风险标记：导入变更遗漏, 内联函数维护双点, 跨后端兼容需验证

关联脉络

• PR #31155 Extract load_model helpers into a load_model_utils module: 同一批 ModelRunner 重构系列，提取模型加载辅助函数到独立模块，与本 PR 采用相同的提取策略。
• PR #31158 Extract small single-function helpers into modules: 同样将 ModelRunner 中单函数辅助方法提取到模块，步骤类似，共同组成 ModelRunner 拆分系列。
• PR #31167 Extract attention-backend setup into a module: 虽然提取的是注意力后端设置，但属于同一重构流水线，依赖相同的模块设计原则。