在 PyTorch DDP 中,你通常不会直接调用 NCCL C API。 代码里写的是 torch.distributed.all_reduce(), DDP 内部在 backward 时把梯度 bucket 交给 ProcessGroupNCCL, 后者再把集合通信发到 CUDA stream 上执行。 所以 NCCL 看起来像一个库,但工程上它更像分布式训练的网络数据平面。

AllReduce 的语义

Ring 的直觉很朴素:把所有 rank 排成一个环,每个 rank 只和左右邻居通信, 大 tensor 被切成多块,沿着环一边传一边 reduce。 它的优势是每条链路都能被持续喂满,非常适合大梯度 bucket。 代价是通信要走 2 * (world_size - 1) 个逻辑阶段, rank 越多,小消息延迟越吃亏。

Ring 的执行阶段

Tree AllReduce 可以看成一次 Reduce 加一次 Broadcast: 先沿树把数据规约到根,再从根广播回所有 rank。 树的关键优势是通信阶段数近似随 log2(world_size) 增长, 所以在大规模训练和小/中等消息上,它能显著降低启动延迟。 但单棵树有根节点瓶颈,NCCL 引入的 double binary tree 用两棵互补二叉树把数据拆成两半,让节点负载更均衡。

Ring、Tree、双二叉树对比

如何让 NCCL 选择算法

# 默认:不要手动指定,让 NCCL 基于拓扑、消息大小和架构自动选择
torchrun --nproc_per_node=4 allreduce_probe.py

# 实验:只允许 Ring,观察大 tensor 与小 tensor 行为
NCCL_ALGO=Ring torchrun --nproc_per_node=4 allreduce_probe.py --numel 67108864

# 实验:只允许 Tree,观察日志里的 Trees / algorithm line
NCCL_ALGO=Tree torchrun --nproc_per_node=4 allreduce_probe.py --numel 262144

# NCCL 2.24+ 支持按 collective 指定算法,这里只限定 allreduce
NCCL_ALGO="allreduce:ring" torchrun --nproc_per_node=4 allreduce_probe.py

NCCL 日志不是"报错时再打开"的东西。 你应该在健康环境里先看一次完整 AllReduce 日志,建立基准印象: 正常启动会出现哪些初始化行、拓扑行、channel 行、算法/协议选择行。 之后遇到 hang 或慢训练,才知道哪里不正常。

推荐的日志环境变量

AllReduce probe 脚本

# allreduce_probe.py
import argparse
import os
import time

import torch
import torch.distributed as dist


def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument("--numel", type=int, default=16_777_216)  # 64 MiB fp32
    parser.add_argument("--iters", type=int, default=20)
    parser.add_argument("--warmup", type=int, default=5)
    return parser.parse_args()


def main():
    args = parse_args()
    rank = int(os.environ["RANK"])
    local_rank = int(os.environ["LOCAL_RANK"])
    world_size = int(os.environ["WORLD_SIZE"])

    torch.cuda.set_device(local_rank)
    dist.init_process_group(backend="nccl")

    x = torch.full((args.numel,), fill_value=rank + 1, device="cuda", dtype=torch.float32)
    torch.cuda.synchronize()

    for _ in range(args.warmup):
        dist.all_reduce(x, op=dist.ReduceOp.SUM)
    torch.cuda.synchronize()

    start = time.perf_counter()
    for _ in range(args.iters):
        dist.all_reduce(x, op=dist.ReduceOp.SUM)
    torch.cuda.synchronize()
    elapsed_ms = (time.perf_counter() - start) * 1000 / args.iters

    expected = world_size * (world_size + 1) / 2
    ok = torch.isclose(x[0], torch.tensor(expected, device="cuda"))
    print(f"rank={rank} local_rank={local_rank} world={world_size} ms={elapsed_ms:.3f} ok={bool(ok)}")

    dist.barrier()
    dist.destroy_process_group()


if __name__ == "__main__":
    main()

启动命令

# 单机 4 卡,把每个 rank 日志写到独立文件
NCCL_DEBUG=INFO \
NCCL_DEBUG_SUBSYS=INIT,BOOTSTRAP,GRAPH,TUNING,COLL,ENV \
NCCL_DEBUG_FILE=/tmp/nccl.%h.%p.log \
TORCH_DISTRIBUTED_DEBUG=DETAIL \
torchrun --standalone --nproc_per_node=4 allreduce_probe.py --numel 16777216

# 看日志文件
ls -lh /tmp/nccl.*.log
sed -n '1,180p' /tmp/nccl.$(hostname).*log

日志阅读路线

示例化日志片段怎么标注

# 下面是教学用的结构化片段,真实日志字段会随 NCCL 版本和机器拓扑变化
NCCL INFO Bootstrap : Using eth0:10.0.0.12<0>
NCCL INFO cudaDriverVersion 12080
NCCL INFO NCCL version 2.xx.x+cuda12.x

NCCL INFO Channel 00/04 : 0 1 2 3
NCCL INFO Channel 01/04 : 0 2 1 3
NCCL INFO Trees [0] 1/-1/-1->0->2
NCCL INFO Trees [1] 2/-1/-1->1->3

NCCL INFO AllReduce: opCount 0 sendbuff 0x... recvbuff 0x... count 16777216 datatype 7 op 0 root 0
NCCL INFO 4 coll channels, 4 nvls channels, algo Ring, proto Simple

# 标注思路:
# 1. Bootstrap 说明网络入口选了哪个 interface。
# 2. Channel 行说明每条通信车道的 rank 顺序。
# 3. Trees 行说明 tree 父子关系,可用来判断是否走树算法。
# 4. AllReduce 行确认 count、datatype、op 和最终算法/协议。

NCCL 问题最难的一点是:症状经常只是"卡住"。 但 hang 背后可能是 collective 不一致、rank 到 GPU 映射错、网卡选错、IB 权限/驱动问题、 P2P 不通、某个 rank OOM 后其它 rank 等不到它。 排查时要分层,不要一上来乱设一堆环境变量。

常用变量,但别滥用

最小化二分流程

# 1. 先确认 PyTorch collective 语义没错
TORCH_DISTRIBUTED_DEBUG=DETAIL torchrun --standalone --nproc_per_node=4 allreduce_probe.py

# 2. 开 NCCL INFO,确认初始化、拓扑、算法路径
NCCL_DEBUG=INFO NCCL_DEBUG_SUBSYS=INIT,BOOTSTRAP,GRAPH,TUNING,COLL \
torchrun --standalone --nproc_per_node=4 allreduce_probe.py

# 3. 强制算法做对照,只为实验和定位
NCCL_ALGO=Ring torchrun --standalone --nproc_per_node=4 allreduce_probe.py --numel 16777216
NCCL_ALGO=Tree torchrun --standalone --nproc_per_node=4 allreduce_probe.py --numel 16777216

# 4. 逐层禁用做二分,定位 P2P / SHM / NET 问题。不要把这些变量长期留在线上。
NCCL_P2P_DISABLE=1 torchrun --standalone --nproc_per_node=4 allreduce_probe.py
NCCL_SHM_DISABLE=1 torchrun --standalone --nproc_per_node=4 allreduce_probe.py

今天的实验不是追求某个固定结论,而是训练你的通信直觉: 小消息看延迟,大消息看带宽;Ring 与 Tree 的交叉点会随 GPU、NVLink、PCIe、NIC、NCCL 版本变化。 你要做的是在自己的机器上跑出一张曲线,并把曲线和 NCCL 日志对应起来。

实验矩阵

批量运行脚本

# run_nccl_day16.sh
set -euo pipefail

export NCCL_DEBUG=INFO
export NCCL_DEBUG_SUBSYS=INIT,GRAPH,TUNING,COLL
export NCCL_DEBUG_FILE=/tmp/nccl.%h.%p.log

for algo in DEFAULT Ring Tree; do
  for numel in 262144 4194304 16777216 67108864; do
    if [ "$algo" = "DEFAULT" ]; then
      unset NCCL_ALGO
    else
      export NCCL_ALGO=$algo
    fi

    echo "algo=$algo numel=$numel"
    torchrun --standalone --nproc_per_node=4 allreduce_probe.py --numel $numel --iters 50
  done
done

记录模板

交付物检查清单

1. 为什么 AllReduce 可以等价理解成 ReduceScatter + AllGather?
2. Ring AllReduce 的带宽优势和延迟劣势分别来自哪里?
3. Tree AllReduce 为什么在大规模小消息上更有优势?
4. Double Binary Tree 如何缓解单棵树的根节点瓶颈?
5. NCCL_DEBUG_SUBSYS=GRAPH,TUNING,COLL 分别帮你看什么?
6. 如果多机训练 init 阶段 hang,你会按什么顺序排查?
7. 为什么不建议在生产配置里长期固定 NCCL_ALGO?