执行摘要

• 一句话：多节点禁用 Custom AR v2
• 推荐动作：该 PR 变更安全且设计合理，值得合入。reviewer 建议集中管理环境变量的思路值得推广。阅读者可以重点关注 _handle_environment_variables 中条件判断的位置（放在 CUDA graph 之前）和日志级别选择（warning）。

功能与动机

Custom All-Reduce v2 使用 IPC handle，仅支持单节点内通信；在多节点部署时如果启用会失败。PR body 明确说明：“Not supported in nodes > 1, it will fail.” 该修复确保多节点环境自动禁用 v2，回落至兼容的多节点路径。

实现拆解

1. 在 ServerArgs._handle_environment_variables 中新增强制禁用逻辑（python/sglang/srt/server_args.py）：在方法末尾、设置 CUDA graph 相关环境变量之前，插入检查 self.nnodes > 1 且 SGLANG_OPT_USE_CUSTOM_ALL_REDUCE_V2 已被设置时，打印警告日志并强制置为 "0"。该改动确保在所有其他环境变量处理完毕后、全局生效前拦截 v2 选项。
2. 更新 dispatch_custom_allreduce 的文档注释（python/sglang/srt/distributed/device_communicators/custom_all_reduce.py）：在函数 docstring 末尾追加说明“Note: ServerArgs._handle_environment_variables forces this env to "0" when nnodes > 1 since custom AR is intra-node only.”，明确记录此行为，帮助后续开发者理解回落机制。
3. 无测试配套变更：本 PR 仅涉及日志与条件判断，未引入新测试。依赖现有 CI 验证多节点场景下的回落正确性。

关键文件：

• python/sglang/srt/server_args.py（模块 服务参数；类别 source；类型 core-logic；符号 _handle_environment_variables）: 核心修改文件：在 _handle_environment_variables 中新增 nnodes > 1 时强制禁用 SGLANG_OPT_USE_CUSTOM_ALL_REDUCE_V2 的逻辑。
• python/sglang/srt/distributed/device_communicators/custom_all_reduce.py（模块 分布式通信；类别 source；类型 configuration；符号 dispatch_custom_allreduce）: 文档注释更新：在 dispatch_custom_allreduce 的 docstring 中记录 server_args 中的禁用行为。

关键符号：_handle_environment_variables, dispatch_custom_allreduce

关键源码片段

python/sglang/srt/server_args.py

核心修改文件：在 _handle_environment_variables 中新增 nnodes > 1 时强制禁用 SGLANG_OPT_USE_CUSTOM_ALL_REDUCE_V2 的逻辑。

# python/sglang/srt/server_args.py
# 在 _handle_environment_variables 方法末尾添加以下逻辑：
# Custom all-reduce v2 uses IPC handles and is intra-node only. Force-disable
# on multi-node so the dispatch falls back to the legacy CustomAllreduce path.
if self.nnodes > 1 and envs.SGLANG_OPT_USE_CUSTOM_ALL_REDUCE_V2.get():
    if envs.SGLANG_OPT_USE_CUSTOM_ALL_REDUCE_V2.is_set():
        logger.warning(
            "Disabling SGLANG_OPT_USE_CUSTOM_ALL_REDUCE_V2 because nnodes=%d "
            "(custom all-reduce v2 is intra-node only).",
            self.nnodes,
        )
    envs.SGLANG_OPT_USE_CUSTOM_ALL_REDUCE_V2.set("0")

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

文档注释更新：在 dispatch_custom_allreduce 的 docstring 中记录 server_args 中的禁用行为。

# python/sglang/srt/distributed/device_communicators/custom_all_reduce.py
# 在 dispatch_custom_allreduce 的 docstring 末尾追加说明：
def dispatch_custom_allreduce():
    """Return the CustomAllreduce class to use (aiter on ROCm if enabled).
​
    On AMD with 1-stage AR enabled, use sglang's CustomAllreduce.
    Otherwise use AiterCustomAllreduce if available.
​
    On CUDA, the JIT-compiled v2 implementation is used by default.
    Set SGLANG_OPT_USE_CUSTOM_ALL_REDUCE_V2=0 to fall back to the legacy CustomAllreduce.
    Note: ``ServerArgs._handle_environment_variables`` forces this env to "0" when
    ``nnodes > 1`` since custom AR is intra-node only.
    """
    # ... function body unchanged ...

评论区精华

Review 讨论中，ch-wan 提出“let’s manage it in _handle_environment_variables”，建议将禁用逻辑集中到环境变量处理方法中，而非分散在其他位置。作者采纳该建议，最终实现符合 reviewer 的设计偏好。

• 禁用逻辑放置位置 (design): 作者采纳建议，最终实现在 _handle_environment_variables 中处理。

风险与影响

• 风险：风险较低。变动仅在 nnodes > 1 时改变环境变量的值，且该值原本由用户手动或默认设置。强制禁用后，v2 相关路径不会执行，回落至 Legacy CustomAllreduce（该路径已支持多节点）。主要风险为：若 Legacy CustomAllreduce 在多节点场景下也存在未发现的问题，则本修复并不能完全解决通信故障；但这是原有降级路径，不在本 PR 范围内。
• 影响：影响范围：多节点部署场景（nnodes > 1）。用户不再需要手动设置 SGLANG_OPT_USE_CUSTOM_ALL_REDUCE_V2=0，系统自动禁用 v2 并给出警告。单节点用户不受影响。团队维护成本极低，仅在 server_args.py 和 custom_all_reduce.py 中各添加数行。
• 风险标记：缺少测试覆盖

关联脉络

• PR #24720 disable the combination of --enable-two-batch-overlap and --enforce-s…: 同属 server_args.py 中的环境变量兼容性检查，均采用 handle* 方法拦截不合法组合。