# 多节点 NCCL 交接计划 2026-05-23

## 当前一句话结论

当前 2 机 8 卡 NCCL 已经排除旧 NCCL、GDR disabled、HCA 选择错误、SSH/mpirun launch、明显链路错误等问题；剩余差距集中在 **硬件 rail 数量是否与 PDF 等价**、**NCCL net plugin / SHARP 是否缺失**、以及 **alltoall 在当前跨 Leaf 网络下的图策略/交换路径效率**。

## 已经验证的事实

| 事实 | 当前证据 |
|---|---|
| 两台机器可用于 NCCL 的 400G IB rail 是 4 条 | `mlx5_0,mlx5_1,mlx5_6,mlx5_7` 均为 `400 Gb/sec (4X NDR)` |
| 其他 HCA 不等价 | `mlx5_4/5` 为 100G IB，`mlx5_2/8` 为 25G Ethernet，`mlx5_3/9` DOWN |
| NCCL 2.27.7 GDR 可用 | GRAPH/NET 日志中 GDR enabled |
| allreduce 已接近当前 4 rail 物理上限 | 最新 PDF matrix 2x8 为 `353.85 GB/s busbw`，反推 `188.72 GB/s algbw`，接近 4 x 400G 的 `200 GB/s` 单向原始带宽 |
| alltoall PXN disabled 后 rail 均衡但仍低 | 最新 PDF matrix 2x8 为 `36.83 GB/s busbw`，每条 rail 约 `19-20 GB/s` |
| 正式 PDF matrix 已复跑 | `reports_multinode_nccl_pdf_matrix_20260523_113803.md`，所有 case 正确性通过；除 2x2 allreduce 外，性能阈值仍 FAIL |
| 原始 artifacts 已归档 | `/root/test_gpu_scripts/reports/multinode_nccl_pdf_matrix_20260523_113803_artifacts`，每个 case 有完整 `cmd/stdout/stderr/json` |
| 没看到硬错误 | 未见 discard、RoCE retrans、slow restart、packet sequence error 等增长 |
| 当前缺外部 NCCL 网络组件 | 未找到 `libnccl-net*.so*` / `libsharp*.so*`，未见 SHARP/HCOLL 包 |

## PDF 目标与当前物理能力的冲突

PDF 2 机 16 GPU allreduce 目标是：

```text
491.84 GB/s busbw
```

16 ranks allreduce 换算关系：

```text
busbw = algbw * 1.875
```

因此 PDF 目标反推：

```text
491.84 / 1.875 = 262.31 GB/s algbw
```

当前每节点 4 条 400G rail 的理论单向原始带宽：

```text
4 * 400Gb/s / 8 = 200 GB/s
```

所以如果 PDF 环境有更多有效 400G rail，或启用了 SHARP/NCCL net plugin，而当前环境没有，则当前节点不应直接按 PDF 2x8 目标判定。

## 决策树

### A. 如果验收坚持 PDF 原始阈值

必须先证明当前环境与 PDF 等价：

1. 每节点是否有 8 条 400G IB rail 可用？
2. PDF 命令中的 HCA 在参考环境里是否全部是 400G IB ACTIVE？
3. PDF 环境是否启用了 SHARP / NCCL net plugin / HCOLL / UCX plugin？
4. 当前跨 Leaf 交换网络策略是否与 PDF 环境一致？

如果任一答案是否定或未知，应先补齐硬件/软件/网络环境再复测，不应继续靠 NCCL 小参数追 `491.84/76.54 GB/s`。

### B. 如果验收按当前硬件形态重新定标

建议把当前 2x8 allreduce 的可解释目标按 4 x 400G rail 物理能力重新评估：

- allreduce 当前 `353.85 GB/s busbw`，反推 `188.72 GB/s algbw`，接近 `200 GB/s` 单向原始上限。
- alltoall 当前 `36.83 GB/s` 仍偏低，需要作为独立问题继续排查。

## 最新 PDF matrix 结果

| Topology | AllReduce | AllReduce Target | AllToAll | AllToAll Target |
|---|---:|---:|---:|---:|
| 2 nodes x 1 GPU | `47.29` | `48.90` | `24.85` | `27.25` |
| 2 nodes x 2 GPUs | `137.16` | `136.93` | `47.76` | `54.41` |
| 2 nodes x 4 GPUs | `335.07` | `335.48` | `72.74` | `73.73` |
| 2 nodes x 8 GPUs | `353.85` | `491.84` | `36.83` | `76.54` |

所有 case 的 return code 为 `0`，NCCL `Out of bounds values` 为 `0 OK`。因此本轮 FAIL 是性能阈值失败，不是 NCCL 正确性或启动链路失败。

### C. 如果要继续优化 alltoall

不要继续盲扫以下参数：

- `NCCL_IB_QPS_PER_CONNECTION`
- `NCCL_IB_SPLIT_DATA_ON_QPS`
- `NCCL_NCHANNELS_PER_NET_PEER`
- `NCCL_BUFFSIZE`
- `NCCL_P2P_NET_CHUNKSIZE`
- `NCCL_IB_AR_THRESHOLD`

已有 sweep 表明它们没有稳定正收益，部分明显负向。

优先做：

1. 补齐并验证 `libnccl-net.so` / SHARP 环境。
2. 让网络侧查跨 Leaf ECMP / adaptive routing / congestion control / credit wait。
3. 用 `scripts/multinode_nccl_deep_diagnose.sh graph` 对比启用 plugin 前后的 NCCL graph。
4. 如有等价 8 rail 节点，迁移同一脚本复测，确认 allreduce 物理上限是否抬升。

## 给网络/硬件/环境侧的问题

请直接确认下面这些问题：

1. 这两台机器是否本来应该有 8 条 400G IB rail？如果是，为什么当前只有 4 条？
2. `mlx5_4/5` 当前只有 100G，是配置、线缆、模块、交换机端口还是硬件限制？
3. `mlx5_2/8` 为什么是 Ethernet 25G？是否预期不参与 IB NCCL？
4. `mlx5_3/9` DOWN 是否符合预期？
5. PDF 参考环境是否安装了 SHARP、HCOLL 或 NCCL net plugin？
6. 当前交换机是否开启 adaptive routing，并且对 alltoall 这种多点到多点流量友好？
7. 当前跨 Leaf 路径是否存在 ECMP hash 不均、PFC/credit wait、拥塞控制参数差异？

## 后续复跑命令

### 轻量检查

```bash
cd /root/test_gpu_scripts
bash scripts/multinode_nccl_deep_diagnose.sh preflight
```

### 单节点环境等价性快照

```bash
cd /root/test_gpu_scripts
bash scripts/nccl_environment_snapshot.sh reports/nccl_environment_snapshot_$(hostname)_$(date +%Y%m%d_%H%M%S).md
```

### 单节点 H100 原始 all 报告

```bash
cd /root/test_gpu_scripts
bash scripts/run_h100_single_node_all.sh
```

### 多机多卡 PDF 矩阵

```bash
cd /root/test_gpu_scripts
bash scripts/run_multinode_nccl_pdf_matrix.sh
```

### 完整深度诊断

```bash
cd /root/test_gpu_scripts
OUT_DIR=/root/test_gpu_scripts/reports/nccl_deep_diag_$(date +%Y%m%d_%H%M%S) \
  bash scripts/multinode_nccl_deep_diagnose.sh all
```

### 启用新 NCCL plugin / SHARP 后的最小复核

```bash
cd /root/test_gpu_scripts
OUT_DIR=/root/test_gpu_scripts/reports/nccl_deep_diag_plugin_check_$(date +%Y%m%d_%H%M%S) \
  bash scripts/multinode_nccl_deep_diagnose.sh graph
```

复核重点：

- `plugin_missing` 是否消失或明显减少。
- NCCL 日志是否出现外部 net plugin。
- alltoall graph 中 `P2P/CUMEM`、`NET/IB/*/GDRDMA`、`channel_edge_lines` 是否变化。
- alltoall busbw 是否突破 `36-37 GB/s` 平台。

## 关键文件

| 文件 | 用途 |
|---|---|
| `reports_multinode_nccl_diagnosis_20260523.md` | 总诊断报告 |
| `reports_multinode_nccl_pdf_matrix_20260523_112247.md` | 上一次多机多卡 PDF matrix 原始报告 |
| `reports_multinode_nccl_pdf_matrix_20260523_113803.md` | 最新带 artifacts 的多机多卡 PDF matrix 原始报告 |
| `reports_multinode_nccl_pdf_matrix_run_20260523.md` | 最新多机多卡 PDF matrix 中文摘要 |
| `reports_multinode_nccl_pdf_matrix_artifacts_manifest_20260523_113803.md` | 最新 artifacts manifest 和 checksum |
| `reports_multinode_nccl_deep_diagnose_run_20260523.md` | 本轮深度复跑结果 |
| `reports_multinode_nccl_environment_gap_20260523.md` | 硬件/软件环境等价性缺口 |
| `reports_multinode_nccl_counter_probe_20260523.md` | RDMA rail/counter 证据 |
| `reports_multinode_nccl_alltoall_tuning_20260523.md` | alltoall 参数 sweep 和结论 |
| `docs/multinode_nccl_deep_diagnose_runbook.md` | 诊断脚本 runbook |
| `scripts/multinode_nccl_deep_diagnose.sh` | 可复跑诊断脚本 |
| `scripts/nccl_environment_snapshot.sh` | 单节点 HCA/plugin/topo 快照脚本 |
| `scripts/run_h100_single_node_all.sh` | 单节点原始 `test all` 报告入口 |
| `scripts/run_multinode_nccl_pdf_matrix.sh` | 多机多卡 PDF 矩阵报告入口；复跑时额外归档每个 case 的完整 `cmd/stdout/stderr/json` |
| `configs/multinode_nccl_nccl227_pdf_matrix.yaml` | 多机多卡 PDF 矩阵配置 |

## 当前建议

当前不建议继续把精力放在 NCCL 环境变量微调上。更高价值的动作是：

1. 确认 PDF 参考环境的 rail 数量、速率和 SHARP/plugin 状态。
2. 补齐或明确排除 NCCL net plugin / SHARP。
3. 让网络侧针对 alltoall 多点通信模式查跨 Leaf 路径和拥塞策略。
4. 如果硬件不等价，调整验收阈值或换等价节点重测。