NCCL 全称是 NVIDIA Collective Communications Library（NVIDIA 集合通信库）。

它是什么

NCCL 是 NVIDIA 专门为 GPU 集群 设计的高性能通信库，用于在多个 GPU 之间高效传输数据。它是分布式深度学习训练的基础设施之一。

核心作用

在分布式训练中，模型或数据被拆分到多张 GPU 上，训练过程中需要频繁地在 GPU 之间同步梯度、参数等数据。NCCL 提供了标准的集合通信原语来实现这些同步操作：

操作	含义
AllReduce	所有 GPU 的数据求和/平均后，结果同步到每张卡（最常用，用于梯度同步）
AllGather	每张卡收集其他所有卡的数据
Broadcast	一张卡的数据广播给所有卡
Reduce	所有数据归约到某一张卡
Send/Recv	点对点通信

为什么重要

• 专为 GPU 优化：充分利用 NVLink、PCIe 等高速互联带宽
• 与深度学习框架集成：PyTorch、TensorFlow、MXNet 等都默认使用 NCCL 作为后端进行分布式训练（torch.distributed 的 nccl backend）
• 多机多卡支持：不仅支持单机多卡，也支持跨节点的多机通信

常见场景

当你在 PyTorch 中这样写时：

torch.distributed.init_process_group(backend='nccl')

就是在告诉 PyTorch：使用 NCCL 作为 GPU 之间的通信后端。

如果报错 NCCL error 或 NCCL timeout，通常意味着 GPU 之间的通信出了问题（比如网络不通、NCCL 版本不匹配、显存不足等）。

NCCL 最常用的环境变量，按使用场景分类：

1. 调试与日志

环境变量	说明	常用值
NCCL_DEBUG	开启调试日志输出	INFO / WARN / TRACE
NCCL_DEBUG_FILE	将日志输出到文件（支持 %h 主机名、%p PID）	/tmp/nccl.%h.%p.log
NCCL_DEBUG_SUBSYS	只输出特定子系统的日志	ALL / INIT / GRAPH / NET / COLL

# 示例：查看 NCCL 初始化过程和设备拓扑
export NCCL_DEBUG=INFO
export NCCL_DEBUG_SUBSYS=INIT,GRAPH

---

2. 网络与通信方式

环境变量	说明	常用值
NCCL_IB_DISABLE	禁用 InfiniBand，强制使用 TCP/IP	1（禁用）
NCCL_SOCKET_IFNAME	指定 NCCL 使用的网络接口	eth0 / bond0 / ib0
NCCL_P2P_DISABLE	禁用 GPU 点对点（P2P）通信	1（禁用）
NCCL_SHM_DISABLE	禁用共享内存（shm）传输	1（禁用）
NCCL_NET_GDR_LEVEL	控制 GPU Direct RDMA 级别	0~5（默认自动检测）
NCCL_CROSS_NIC	允许跨网卡通信	0 / 1

# 示例：没有 IB 网卡时，强制走以太网
export NCCL_IB_DISABLE=1
export NCCL_SOCKET_IFNAME=eth0

# 示例：P2P 出问题时的临时规避
export NCCL_P2P_DISABLE=1

---

3. 算法与性能调优

环境变量	说明	常用值
NCCL_ALGO	强制指定集合通信算法	RING / TREE / COLLNET / NVLS
NCCL_TREE_THRESHOLD	设置切换到 Tree 算法的数据量阈值（字节）	默认自动
NCCL_LL_THRESHOLD	设置低延迟（LL）算法的数据量阈值	默认自动
NCCL_BUFFSIZE	设置通信缓冲区大小（字节）	默认 4MB
NCCL_MIN_NCHANNELS / NCCL_MAX_NCHANNELS	控制通信通道数	数字

# 示例：强制使用 Ring 算法（某些场景下更稳定）
export NCCL_ALGO=RING

# 示例：增加通道数以提升带宽利用率
export NCCL_MIN_NCHANNELS=4

---

4. 超时与容错

环境变量	说明	常用值
NCCL_BLOCKING_WAIT	设置为阻塞等待模式（方便定位 hang）	1
NCCL_ASYNC_ERROR_HANDLING	异步错误处理方式	0（忽略）/ 1（终止）/ 2（清理后终止）
NCCL_TIMEOUT	设置通信超时时间（秒）	默认无限制

# 示例：训练 hang 住时，开启阻塞等待方便定位
export NCCL_BLOCKING_WAIT=1

---

5. 拓扑与亲和性

环境变量	说明	常用值
NCCL_P2P_LEVEL	控制 P2P 使用的级别	NVL / PIX / PXB / SYS
NCCL_IGNORE_CPU_AFFINITY	忽略 CPU 亲和性设置	1
NCCL_TOPO_FILE	指定自定义拓扑文件路径	文件路径

---

6. 其他实用变量

环境变量	说明
NCCL_NSOCKS_PERTHREAD	每个线程的 socket 数量，调大可能提升网络吞吐
NCCL_NET	指定使用的网络插件（如 IB、Socket）
NCCL_COMM_ID	手动指定通信 ID（多机初始化用）

---

快速排查模板

如果 NCCL 报错或训练 hang 住，通常这样排查：

# 1. 先看 NCCL 在用什么设备和网络
export NCCL_DEBUG=INFO
export NCCL_DEBUG_SUBSYS=INIT,GRAPH,NET

# 2. 如果多机不通，检查网络接口
export NCCL_SOCKET_IFNAME=你的实际网卡名
export NCCL_IB_DISABLE=1   # 如果没有 IB 网卡

# 3. 如果 P2P 报错，临时禁用
export NCCL_P2P_DISABLE=1
export NCCL_SHM_DISABLE=1