执行摘要

• 一句话：提取环境变量计算函数并移除默认参数，为推理引擎工作器规范铺路。
• 推荐动作：该 PR 值得精读，因为它清晰地展示了如何在一个大型代码库中进行安全的、逐步的重构：先提取公共逻辑，然后收紧接口契约。对于希望了解如何为“推理引擎工作器规范”（#2006）做准备的工程师尤其有参考价值。设计决策聚焦于单一职责和显式优于隐式。

功能与动机

作为 #1837 大型重构追踪 Issue 的一部分，需要统一推理引擎的启动和配置逻辑。当前环境变量设置与服务器参数计算存在重复且耦合，提取函数和移除默认值是为了理清职责边界，为后续引入“推理引擎工作器规范”（specs_inference_engine）扫清障碍。

实现拆解

1. 提取核心逻辑：在 miles/ray/specs/inference.py 中新增 compute_inference_engine_env_vars 函数。该函数整合了设置 SGLang 进程所需的所有环境变量，包括禁用特定 CUDA 设备、配置内存优化、调试选项等。这个新函数从 miles.ray.utils 和 miles.utils.dumper_utils 引入了必要的依赖。
2. 替换内联实现：修改 miles/ray/rollout/server_cell.py 中的 launch_sglang_ray_actor 函数。移除了原先直接构造 env_vars 字典的大量代码，改为调用上一步提取的 compute_inference_engine_env_vars 函数。这消除了代码重复，使得环境变量管理更集中、可维护。
3. 强化接口契约：修改 miles/backends/sglang_utils/sglang_engine.py 中的 _compute_server_args 函数，移除了 disaggregation_bootstrap_port、engine_info_bootstrap_port、sglang_overrides 和 num_gpus_per_engine 四个参数的默认值（= None）。这迫使所有调用者必须显式提供这些参数，防止因默认值而导致的配置错误或隐式行为。
4. 配套变更：由于提取了公共函数，server_cell.py 中移除了不再直接使用的 import os、from miles.ray.utils import NOSET_VISIBLE_DEVICES_ENV_VARS_LIST 和 from miles.utils import dumper_utils 三个导入语句。inference.py 则新增了对应的导入。

关键文件：

• miles/ray/specs/inference.py（模块 启动规范；类别 source；类型 core-logic；符号 compute_inference_engine_env_vars）: 包含本次 PR 的核心产出：新提取的 compute_inference_engine_env_vars 函数，该函数集中管理推理引擎的环境变量配置，是后续 specs_inference_engine 实现的基础。
• miles/ray/rollout/server_cell.py（模块 服务单元；类别 source；类型 dependency-wiring）: 作为环境变量计算的消费方，从内联逻辑改为调用新提取的函数，展示了重构的典型模式——消除重复代码。
• miles/backends/sglang_utils/sglang_engine.py（模块 推理后端；类别 source；类型 core-logic；符号 _compute_server_args）: 移除了 _compute_server_args 部分参数的默认值，强化了函数接口契约，是本次重构的配套改动。

关键符号：compute_inference_engine_env_vars

关键源码片段

miles/ray/specs/inference.py

包含本次 PR 的核心产出：新提取的 compute_inference_engine_env_vars 函数，该函数集中管理推理引擎的环境变量配置，是后续 specs_inference_engine 实现的基础。

def compute_inference_engine_env_vars(args) -> dict[str, str]:
    # 合并需要禁用可见设备的环境变量列表
    env_vars = {name: "1" for name in NOSET_VISIBLE_DEVICES_ENV_VARS_LIST} | {
        # 从环境变量读取值，若不存在则使用默认值
        key: os.environ.get(key, default_val)
        for key, default_val in {
            # DeepEP/NVSHMEM 的内部 NCCL 与我们的 NCCL 冲突，并在 CUDA 图下挂起
            "NVSHMEM_DISABLE_NCCL": "1",
            "SGLANG_JIT_DEEPGEMM_PRECOMPILE": "false",
            "SGLANG_DG_CACHE_DIR_PER_PROCESS": "1",
            "SGLANG_ENABLE_TP_MEMORY_INBALANCE_CHECK": "false",
            "SGLANG_MEMORY_SAVER_CUDA_GRAPH": "true",
            # 根据是否共置及引擎 GPU 数决定是否启用自定义 all-reduce
            "SGLANG_OPT_USE_CUSTOM_ALL_REDUCE_V2": (
                "0" if args.colocate and args.rollout_num_gpus_per_engine > 1 else "1"
            ),
            "SGLANG_BATCH_INVARIANT_OPS_ENABLE_MM_FALLBACK_VARIANT": "true",
            "SGLANG_ENABLE_HEALTH_ENDPOINT_GENERATION": "false",
            "SGLANG_ENABLE_STRICT_MEM_CHECK_DURING_IDLE": "false",
        }.items()
    }
    # 合并 dumper 工具提供的额外环境变量
    env_vars.update(dumper_utils.get_sglang_env(args))
    return env_vars

miles/ray/rollout/server_cell.py

作为环境变量计算的消费方，从内联逻辑改为调用新提取的函数，展示了重构的典型模式——消除重复代码。

import ray
from ray.util.scheduling_strategies import PlacementGroupSchedulingStrategy
# 从新的规范模块导入提取出的函数
from miles.ray.specs.inference import compute_inference_engine_env_vars
​
​
def launch_sglang_ray_actor(
    *,
    args: Any,
    pg: Any,
    gpu_index: int,
) -> ray.actor.ActorHandle:
    pg, reordered_bundle_indices, _ = pg
​
    # ... 调度策略计算 ...
​
    # 直接调用集中管理的函数获取环境变量，替代原先的长段内联逻辑
    env_vars = compute_inference_engine_env_vars(args)
​
    RolloutRayActor = ray.remote(CommandActor)
    return RolloutRayActor.options(
        num_cpus=num_cpus,
        num_gpus=num_gpus,
        scheduling_strategy=scheduling_strategy,
        runtime_env={
            "env_vars": env_vars,
        },
    ).remote()

评论区精华

只有 guapisolo 的一条评审评论，确认了本次 PR 暴露的一个导入缺失问题（miles.rollout.session.ports）将在后续的 PR#2006 中被修复，这在 PR 链条上下文中是可接受的。结论明确：LGTM in stack context，即在整个重构序列中评估通过。没有发现其他争议或未解决的疑虑。

• 导入缺失与修复顺序 (design): 在 PR 链条（Stack）的上下文中评审，该问题在预期中且将被解决，因此 LGTM。

风险与影响

• 风险：
  1. 回归风险：低。这是一个纯粹的代码重构（提取函数、移除默认值），逻辑行为完全平移。但需确保所有调用方已适配新的接口签名（无默认值）。
  2. 配置一致性风险：中低。将环境变量配置集中后，若后续修改 compute_inference_engine_env_vars 中的任何值，会影响所有使用 SGLang 后端的推理引擎进程。这是期望的行为，但修改时需谨慎。
  3. 依赖链风险：低。server_cell.py 新增了对 inference.py 的依赖，但这是合理的职责划分。评审已确认 inference.py 的另一个新依赖将在同系列 PR 中处理。
     - 影响：本次变更直接影响 miles 系统启动 SGLang 推理引擎的流程。通过消除代码重复和强化接口，提升了代码的可维护性和健壮性。它为后续的架构重构（如统一 CommandWorkerSpec 规范）铺平了道路，间接影响所有使用 SGLang 后端的训练和推理场景。对最终用户无直接功能影响。
     - 风险标记：重构引入新函数, 依赖链调整

关联脉络

• PR #2006 Launch inference engines through the inference engine worker spec: 本 PR 提取的 compute_inference_engine_env_vars 是 PR#2006 实现统一推理引擎工作器规范 (specs_inference_engine) 的直接依赖和准备步骤。
• PR #2048 Rename PortAllocator internals and pass the actor positionally: 同属 #1837 追踪的重构系列，后续对端口分配器的改进，与本 PR 的接口强化（移除默认值）属于同一代码质量提升方向。
• PR #2005 Derive the engine api key from the model config: 同时期（#2005, #2006, #2004）对 sglang_engine.py 和 inference.py 进行的系列重构的一部分，旨在清理和统一推理引擎的配置和启动逻辑。