# PR #2312 完整报告

- 仓库：`THUDM/slime`
- 标题：docs: remove stale delta NCCL recommendation
- 合并时间：2026-08-24 11:20
- 原文链接：http://prhub.com.cn/THUDM/slime/pull/2312

---

## 执行摘要

PR #2312 是一次双语文档同步：从 external rollout engine 决策表中删除过时的 `--update-weight-mode delta --update-weight-transport nccl` 推荐，改为明确“delta 模式仅支持 disk transport，NCCL 同步请使用 full mode”。改动仅涉及 2 个 Markdown 文件（+4/-2），无运行时影响，属于文档与代码契约的对齐操作，并明确不声称修复 #2209 报告的 grouped-MoE NaN 问题。

## 功能与动机

- 由 #1806 引入的分布式 delta+NCCL updater 已被 #2089 移除，当前参数校验会拒绝 delta + nccl 组合；但中英文决策表仍将这一组合列为推荐项，会引导用户走一条不存在的路径。
- PR body 明确：「This aligns the documentation with the current runtime instead of suggesting a path that no longer exists.」
- 关联 Issue #2209 曾报告 delta+NCCL 在 Qwen3.5-122B grouped-MoE 上导致 NaN/inf 崩溃；PR 特意声明不修复该问题，因为相关代码已从 main 移除，避免读者误解。

## 实现拆解

变更入口是 `docs/en/advanced/external-rollout-engines.md` 与 `docs/zh/advanced/external-rollout-engines.md` 中的“何时使用 external engine”决策表。实施分三步：

1. **删除过时推荐**：英文表移除 `You want to validate delta wire/apply logic inside one datacenter` 对应的 delta + nccl 行；中文表移除 `想验证 delta wire/apply 逻辑，但仍在同一数据中心内` 对应的 delta + nccl 行。该组合正是 #2089 移除、且参数校验拒绝的路径。
2. **写入新契约**：英文表新增 `Delta mode supports disk transport only. Use full mode when syncing weights over NCCL.`；中文表新增 `delta mode 仅支持 disk transport。通过 NCCL 同步权重时请使用 full mode.`，把运行时约束显式固化为文档，替代原推荐行。
3. **同步与验证**：中英文语义保持一致，避免双语内容漂移；作者用 Sphinx 分别构建英文（50 个既有 warning）与中文（55 个既有 warning）并通过，检查生成的 HTML 含新 disk-only 说明，pre-commit 与 `git show --check` 通过。无测试、配置或部署配套改动，因为这是纯文档变更。

### 本次为纯文档改动，无可展示的源码片段。核心变更文本如下：

| 语言 | 删除的推荐行 | 新增的契约说明 |
| --- | --- | --- |
| 英文 | `You want to validate delta wire/apply logic inside one datacenter` → `--update-weight-mode delta --update-weight-transport nccl` | `Delta mode supports disk transport only. Use full mode when syncing weights over NCCL.` |
| 中文 | `想验证 delta wire/apply 逻辑，但仍在同一数据中心内` → `--update-weight-mode delta --update-weight-transport nccl` | `delta mode 仅支持 disk transport。通过 NCCL 同步权重时请使用 full mode.` |

## 评论区精华

本 PR 无任何 review 评论与讨论线程（comments_count 与 review_comments_count 均为 0），合入前由作者在 PR body 中说明验证过程。唯一的隐含澄清是：作者特意区分“删除过时文档建议”与“修复 #2209 崩溃”两件事，避免读者将文档清理误认为对 grouped-MoE 损坏问题的修复。

## 风险与影响

风险极低：

- **运行时零影响**：不改任何源码、参数校验或配置 schema。
- **双语一致性**：中英文同步更新，避免单侧滞后；后续编辑需保持两份文档对齐。
- **未来回归风险**：如果重新引入 delta+NCCL 传输（例如基于 #2209 的修复重开该路径），本页需要再次更新，否则会重新出现 stale 推荐。
- **读者澄清**：文档仍保留 delta 模式的 disk 用法，不会被 #2209 的历史崩溃暗示为“delta 整体不可用”。

影响范围：主要面向使用 external rollout engine 与 `--update-weight-mode` 参数的工程师，减少他们被引导到无效组合的试错成本；对训练系统与团队开发流程无直接影响。

## 关联脉络

本 PR 是 weight sync 演进链路中的一个收尾动作：#1806 引入分布式 delta+NCCL updater → #2089 移除该路径 → #2209 报告其在 grouped-MoE 上的 NaN 崩溃（与该链路的移除原因相关）→ #2312 清理残留的文档推荐。仓库近期还有一批配套的清理与文档对齐 PR（如 #2318、#2317、#2316），体现了团队在功能移除后主动同步测试与文档的习惯。