执行摘要

• 一句话：更新 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 映射和文件路径格式生效，可能修复了验证冲突问题。