# PR #25521 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[PD] docs: clarify disaggregation IB device formats
- 合并时间：2026-06-02 11:38
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/25521

---

# 执行摘要

- 一句话：更新 IB 设备格式的文档与 CLI 帮助
- 推荐动作：此 PR 是典型的功能文档补全，建议阅读以了解 PD 分解中 IB 设备配置的三种格式。但需注意文档可能超前于实现，建议结合关联 PR #26114 一并审查验证逻辑是否已适配。

# 功能与动机

根据 Issue 评论，PR #12817 新增了用户自定义 RDMA NIC 拓扑支持，但文档未同步更新。近期有用户反馈此文档缺失，因此希望通过更新文档来强调该功能。

# 实现拆解

1. **更新 CLI 帮助文本**：在 `python/sglang/srt/server_args.py` 中，修改 `--disaggregation-ib-device` 参数的 `help` 字符串，从仅描述单设备或逗号分隔列表扩展为包含三种格式：单设备、共享逗号分隔列表、per-GPU JSON 映射、JSON 文件路径。
2. **新增文档小节**：在 `docs_new/docs/advanced_features/pd_disaggregation.mdx` 中新增 "### IB Device Configuration" 小节，列出与 CLI 帮助文本对应的三种格式示例。
3. **无配套代码变更**：此 PR 仅为文档更新，未修改底层验证逻辑 `_validate_ib_devices`。

关键文件：
- `python/sglang/srt/server_args.py`（模块 配置；类别 source；类型 documentation）: 更新了 `--disaggregation-ib-device` 的 CLI 帮助文本，新增格式说明。
- `docs_new/docs/advanced_features/pd_disaggregation.mdx`（模块 文档；类别 other；类型 documentation）: 新增 IB Device Configuration 小节，列出三种格式。

关键符号：未识别


# 评论区精华

- **格式验证冲突**：gemini-code-assist[bot] 指出文档中描述的 JSON 映射和文件路径格式在现有 `_validate_ib_devices` 验证逻辑（期望逗号分隔列表）下会失败，建议同步更新验证代码。zijiexia 也确认这些格式当前不工作。
- **建议单引号包裹**：gemini-code-assist[bot] 建议在文档示例中使用单引号包裹 JSON 字符串，以防止 shell 对大括号的解释。该建议未被采纳，最终文档未加单引号。
- **建议明确 `.json` 扩展名要求**：gemini-code-assist[bot] 建议文档明确说明文件路径需要 `.json` 扩展名（因为后端实现中根据扩展名识别文件），但最终文档未添加此限制。

 - 文档格式与验证逻辑冲突 (correctness): PR 本身未更新验证逻辑，但后续合并的 #26114 可能解决了此问题。
 - 建议用单引号包裹 JSON 字符串 (documentation): 未被采纳，最终文档未加单引号。
 - 建议明确要求 `.json` 文件扩展名 (documentation): 未被采纳，最终文档未提及此限制。

# 风险与影响

- 风险：**文档与实现不一致的风险**：文档中声称支持的 JSON 映射和文件路径格式在现有 `_validate_ib_devices` 验证逻辑中会触发 `ValueError`，用户如果按文档使用这些格式将遇到错误。虽然 PR #26114 合并后可能修复了此问题，但本 PR 本身未包含相应代码更新，若独立查看则存在误导风险。
- 影响：**影响范围**：仅影响文档阅读者和 CLI 帮助使用者。**影响程度**：低，不涉及运行时行为变更，但若格式不可用则会对用户造成困惑。
- 风险标记：文档格式超前于代码验证 , 用户可能尝试未支持格式

# 关联脉络

- PR #12817 [Feature] Add user-defined RDMA NIC topology support: 此 PR 在 #12817 功能基础上补充文档，该功能添加了自定义 RDMA NIC 拓扑但未更新文档。
- PR #26114 Fix validation for JSON and file path formats in disaggregation-ib-device: 在合并时被提及，声称使 JSON 映射和文件路径格式生效，可能修复了验证冲突问题。