# PR #21303 完整报告

- 仓库：`sgl-project/sglang`
- 标题：Fix RDMA device mapping for non-zero GPU indices in disaggregation tests
- 合并时间：2026-03-25 13:56
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/21303

---

# 执行摘要

- 一句话：修复 disaggregation 测试中 RDMA 设备映射错误，避免 CI 失败。
- 推荐动作：对于涉及 disaggregation 测试和 RDMA 配置的工程师，建议精读此 PR。关注 _validate_ib_devices 函数中错误处理的设计决策，以及 _pick_default_pair 中相对索引映射的实现细节，这些对于理解 GPU-RDMA 设备映射逻辑至关重要。

# 功能与动机

在 CI 运行器使用 CUDA_VISIBLE_DEVICES 进行 GPU 隔离（例如 CUDA_VISIBLE_DEVICES=2,3）时，RDMA 设备映射使用绝对 GPU 索引。例如，有两个 RDMA 设备 [mlx5_2, mlx5_3]，GPU 索引 2 映射到 min(2//1, 1) = 1 → mlx5_3 和 GPU 索引 3 也映射到 min(3//1, 1) = 1 → mlx5_3，产生 ValueError: Duplicate IB devices specified: mlx5_3,mlx5_3。这导致测试失败。

# 实现拆解

实现分为两部分：
1. **服务器参数验证 **(python/sglang/srt/server_args.py)：修改 _validate_ib_devices 函数，将重复 IB 设备检查从抛出 ValueError 改为记录警告并自动去重。
2. **测试 fixture 映射 **(python/sglang/test/server_fixtures/disaggregation_fixture.py)：在 _pick_default_pair 函数中引入 base_gpu 变量计算相对 GPU 索引，映射公式从 min(gpu_idx // gpus_per_rdma, n_rdma - 1) 改为 min((gpu_idx - base_gpu) // gpus_per_rdma, n_rdma - 1)，并添加去重输出。

关键文件：
- `python/sglang/srt/server_args.py`（模块 srt/server_args）: 修改了服务器参数验证逻辑，将重复 IB 设备检查从错误改为警告并去重，影响所有使用 IB 设备的配置。
- `python/sglang/test/server_fixtures/disaggregation_fixture.py`（模块 test/fixtures）: 修复了 disaggregation 测试 fixture 中的 GPU 到 RDMA 设备映射逻辑，使用相对索引避免 CI 环境中的错误。

关键符号：_validate_ib_devices, _pick_default_pair


# 评论区精华

review 中主要讨论了两个点：
- **正确性检查**：gemini-code-assist[bot] 建议在 disaggregation_fixture.py 的 _pick_default_pair 函数中添加对空 gpu_indices 的检查，以避免 min() 函数抛出 ValueError。作者 alisonshao 回应称，如果 gpu_indices 为空，循环不会执行，且已有逻辑处理空情况，因此不需要额外检查。
- **去重方法**：reviewer ShangmingCai 建议使用 set 进行去重，但代码中使用了 dict.fromkeys 方法去重并保留顺序，该建议未被明确采纳或拒绝。

 - 空 gpu_indices 列表检查 (correctness): 作者 alisonshao 回应称已有逻辑处理空情况，无需额外检查。
- 去重方法优化 (design): 代码中使用了 dict.fromkeys 去重，该建议未被明确处理。

# 风险与影响

- 风险：风险包括：
 1. **配置错误隐藏**：在 server_args.py 中，将重复设备错误改为警告，可能掩盖用户配置错误，导致运行时问题不易发现。
 2. **映射逻辑边界**：disaggregation_fixture.py 中的相对索引映射依赖于 base_gpu 计算，如果 gpu_indices 列表非连续或异常，可能产生不正确的映射。
 3. **测试覆盖不足**：变更可能引入新的边界情况，需要确保测试覆盖所有可能的 GPU 和 RDMA 设备配置。
- 影响：影响范围：
- **用户**：主要影响测试工程师和 CI 运维人员，disaggregation 测试将更稳定，减少因设备映射错误导致的失败。
- **系统**：提升测试套件在异构 GPU 环境（如使用 CUDA_VISIBLE_DEVICES）中的兼容性。
- **团队**：减少 CI 失败率，提高开发效率，但需注意新警告可能增加日志噪声。
- 风险标记：配置错误隐藏 , 映射边界条件

# 关联脉络

- PR #21271 Fix disaggregation test bootstrap port conflict: 同属修复 disaggregation 测试稳定性的 PR，解决端口冲突问题。