NCCL（NVIDIA Collective Communications Library）是 NVIDIA 的高性能多 GPU 集合通信库，PyTorch / TensorFlow 分布式训练的通信底座。出问题时优先 NCCL_DEBUG=INFO 定位。
核心能力
- 集合通信：AllReduce（最常用）、Broadcast、Reduce、AllGather、ReduceScatter
- 拓扑感知：自动识别 NVLink、PCIe、InfiniBand 互联结构
- GPU Direct：支持 P2P 与 RDMA，绕过 CPU 直接通信
- 目标：最大化互联带宽，适配万卡级集群
调试与日志
| 变量 | 作用 |
|---|
NCCL_DEBUG=VERSION/INFO/WARN/DEBUG/TRACE | 日志级别。INFO 用于通信异常定位 |
NCCL_DEBUG_SUBSYS=INIT,NET,COLL | 仅打印指定子系统日志 |
NCCL_TOPO_DUMP_FILE=nccl_topo.xml | 导出 GPU/网络拓扑文件 |
网络与接口
| 变量 | 作用 |
|---|
NCCL_SOCKET_IFNAME=eth0,ib0 | 指定网络接口（避开管理网） |
NCCL_IB_DISABLE=1 | 禁用 InfiniBand，回退 TCP |
NCCL_IB_HCA=mlx5_0:1 | 指定 IB 网卡设备与端口 |
NCCL_NET_GDR_LEVEL=2 | 启用 GPU Direct RDMA（0 关闭，2 强开） |
P2P 与共享内存
| 变量 | 作用 |
|---|
NCCL_P2P_DISABLE=1 | 禁用 NVLink/PCIe P2P，强制走内存或网络 |
NCCL_P2P_LEVEL=LOC/NODE/SYS | 控制 P2P 范围 |
NCCL_SHM_DISABLE=1 | 禁用共享内存（跨进程通信回退到网络） |
性能调优
| 变量 | 作用 |
|---|
NCCL_BUFFSIZE=8388608 | 通信缓冲区大小（默认 4 MB），调大可提升大消息带宽 |
NCCL_MIN_NCHANNELS=4 / NCCL_MAX_NCHANNELS=16 | 并行通信通道数（影响小消息并发） |
NCCL_ALGO=Ring | 强制通信算法（Ring/Tree） |
NCCL_LAUNCH_MODE=PARALLEL | 并行启动，多进程多 GPU 时可缓解死锁 |
稳定性
| 变量 | 作用 |
|---|
NCCL_IB_TIMEOUT=20 | IB 超时（默认 17），网络抖动时调高 |
NCCL_ASYNC_ERROR_HANDLING=1 | 异步错误处理，避免训练 hang |
典型用法
# 多节点 IB 训练常用环境
export NCCL_DEBUG=INFO
export NCCL_IB_HCA=mlx5_0
export NCCL_SOCKET_IFNAME=ib0
export NCCL_NET_GDR_LEVEL=2
export NCCL_BUFFSIZE=8MB
torchrun --nproc_per_node=8 train.py
核心原则：默认配置已自动优化；遇到 hang/慢/错时，先开 NCCL_DEBUG=INFO 看通信日志，再针对性调环境变量。