简介NCCL 测试工具nccl-tests是一套面向 CUDA 开发者和分布式训练工程师的 NVIDIA 集合通信库性能与正确性验证源码包适合评估多 GPU 通信效率、调试集群通信瓶颈以及确认集合通信结果是否正确。资源共 15 个文件以 7 个 CUDA 源文件.cu为核心配合头文件、Makefile 构建脚本、说明文档与许可证文件压缩包仅 27KB整体轻量、便于按需裁剪。测试内容涵盖 all_reduce、all_gather、broadcast、reduce_scatter 等常用集合通信算子可跨多进程、多线程以及每线程多个 CUDA 设备运行开启 MPI 支持后还能进一步扩展至多节点环境模拟真实分布式训练集群的通信压力。已有 4609 人浏览学习。读者拿到源码后可自行指定 CUDA_HOME、NCCL_HOME 等路径进行编译快速得到各操作的带宽、延迟与正确性比对结果并通过 PERFORMANCE.md 了解测试设计思路与性能分析方法便于后续做基准对比或集成到自身测试流程中。1. 先搞懂 nccl-tests 到底在测什么带宽、延迟与集群健康度分布式训练或者推理集群跑起来之后经常遇到一种尴尬模型吞吐上不去日志里全是 NCCL 的报错但你分不清到底是卡的内存带宽不够还是节点间的网络在拖后腿。nccl-tests 就是用来回答这个问题的。它是随 NCCL 一起维护的基准测试套件源码仓库里每一个*_perf程序都对应一个 NCCL 集合通信原语比如 allreduce、broadcast、allgather、reduce-scatter 和 sendrecv。你只要把典型负载的消息大小、GPU 数量和节点拓扑喂进去它就能输出一份稳定的带宽和延迟报告让你把瓶颈定位到「卡」还是「网」。这个工具最适合三种人一是做分布式训练平台的同学需要给上层业务一个硬件基线二是算法工程师训练变慢时想快速判断是不是通信的锅三是搞 HPC 和 GPU 集群运维的一线人员换卡、换交换机、改拓扑之后需要一套可复现的验收手段。很多人把它当成一个压测工具但它真正的价值是给你一张「这张卡、这块网卡、这套拓扑组合在一起通信底线在哪」的体检报告。2. 编译并跑通最小测试从 clone 到第一份 allreduce 报告2.1 拿到源码并完成编译最少需要 CUDA 和编译器nccl-tests 的源码结构很简单每个测试程序就是一个独立的小型可执行文件依赖 NCCL 头文件和运行时库做编译。常见做法是先把仓库克隆到本地然后直接用 make 构建。以下是我在一台装有 CUDA toolkit 的 Ubuntu 机器上跑通的最小步骤# 把仓库克隆到本地然后进入目录 git clone https://github.com/NVIDIA/nccl-tests.git cd nccl-tests # 指定 CUDA 路径启用 MPI 支持8 个并行编译任务 make CUDA_HOME/usr/local/cuda MPI1 -j8CUDA_HOME告诉编译脚本去哪里找nvcc和 CUDA 运行时头文件如果你的 CUDA 装在其他位置比如/opt/cuda就把这个路径换掉。MPI1是可选的加上之后 nccl-tests 能通过 mpirun 跨节点启动多进程测试如果只是想先跑单机MPI0也可以但后面要做多节点对比时还是建议装 openmpi 并开启 MPI 支持。如果编译报错说找不到mpi.h说明系统里没有 MPI 开发头文件apt install libopenmpi-dev装完再重新 make 就行。编译完成后build目录下会出现一堆可执行文件all_reduce_perf是我们最常用的一个。我一般会先跑一遍./build/all_reduce_perf --help确认当前版本支持哪些参数因为不同版本之间参数行为有细微差别尤其是消息大小上下限。2.2 最小可复现命令单机双卡 all_reduce_perf跑通最小测试的第二步是找到一个「参数完整但不过度」的命令。所谓不过度是指不要一开始就上几十个参数否则出了问题你根本不知道是哪个参数导致的。以下命令是我做单机双卡通信体检时的起点./build/all_reduce_perf -b 128 -e 128M -f 2 -g 2 -n 100 -w 25拆开看这几个参数-b 128表示起始消息大小是 128 字节-e 128M表示最终消息大小是 128MB-f 2表示每次翻倍增长-g 2表示使用 2 个 GPU-n 100表示每个消息大小跑 100 次迭代-w 25表示正式计时前先做 25 次预热。预热之所以重要是因为 NCCL 首次通信会初始化拓扑、分配缓冲这些开销不该算进正式成绩里。实际运行时你可以通过CUDA_VISIBLE_DEVICES0,1指定具体用哪两张物理卡这样在多卡机器上可以避开被其他进程占用的 GPU。跑完会输出一张结果表每一行对应一个消息大小包含 time、algbw、busbw 三列关键数据。我在拿到新机器或者更新驱动后都会先跑这个命令存一份基线后面再做的任何优化都拿这份基线做参照。2.3 读懂第一份输出别只看 Algbw要盯 Busbw先看这张表格里最常见的几列很多人第一次跑完容易盯错指标列名含义关注价值Size消息大小字节决定你测的是延迟区间还是带宽区间Time平均耗时微秒小消息看它延迟敏感场景的直接指标Algbw算法带宽GB/s消息大小除以时间直观但不反映拓扑效率Busbw总线带宽GB/s按 NCCL 通信模式折算后的总线利用率最能反映真实效率Algbw的算法就是把 Size 除以 Time看起来「传输速度」不错但 allreduce 这类操作在通信过程中数据要在 GPU 之间多次经过实际总线压力比单纯除一下大得多。Busbw是在 Algbw 基础上按 NCCL 的通信模型折算出来的对 allreduce 来说它大致相当于考虑了每个 rank 都要从总线上读写数据的那份开销。所以当你看到Algbw很高但Busbw只有它的一半时往往不是网络不行而是通信模式本身就是这样的不必惊慌反过来如果Busbw明显低于同型号机器在同样拓扑下的正常水平才说明有问题。我习惯在看输出时把Busbw作为第一指标Time作为第二指标。大消息下 busbw 接近理论带宽上限说明通信路径健康小消息下 Time 稳定说明协议和拓扑没有异常波动。理解了这两列才谈得上把参数调到你的真实负载上去。3. 把参数调到能反映真实负载消息大小、GPU 数量与协议选择3.1 消息大小怎么选小消息看延迟大消息看带宽中间区间的坑最深消息大小决定了你测的是「延迟」还是「带宽」。128 字节到 64KB 这个区间通信时间主要由握手、同步和协议开销组成这时候你要关注的是 Time而不是 bandwdith从 1MB 往上数据传输时间才逐渐主导Busbw 开始有了实际意义。做基线测试时我一般不会只测一组大小而是用-b 8 -e 4G -f 2这样从 8 字节一路翻倍到 4GB 的扫描。这样跑完一张表你能同时看到小消息延迟和大消息带宽的全貌。但这里有个坑不是每个负载都需要扫到 4GB。如果你的业务是推理场景比如大模型各层之间的同步消息体量通常只有几百 KB 到几 MB扫到 128M 到 256M 就足够了再往上只是浪费时间。反过来如果是训练场景梯度同步的单个张量往往在 MB 到 GB 级别那就要把-e调到足够大至少要覆盖模型单层梯度的大小。有个经验值把-e设为模型单卡显存的三分之一左右基本能覆盖最坏情况。跑完之后看曲线趋势如果某个大小点突然掉得很厉害多半是算法或协议在这个区间做了切换比如从 Ring 切到 Tree或者协议从 LL 切到了 Simple。3.2 GPU 数量与放置用 -g 和拓扑信息预判真实性能-g参数决定参与通信的 GPU 数量这个数量必须和你的实际负载一致。你拿 2 卡测出来的 busbw不能直接外推到 8 卡甚至 16 卡因为拓扑结构完全不同。在单机内GPU 之间的连接可能是 NVLink、PCIe 交换机也可能要跨 CPU socket做测试之前要先看一眼卡之间的拓扑nvidia-smi topo -m这条命令会输出一张矩阵标明每对 GPU 之间是 NVLink、PIX、PXB 还是 SYS 连接。如果是 NVLinkbusbw 跑到很高是正常的如果是 SYS也就是跨 CPU socket 通信性能会明显掉一截这不是 NCCL 的问题是物理拓扑决定的。你跑 nccl-tests 之前先对拓扑有个预判后面看到数据就不会误判成软件故障。当需要模拟多节点但手上只有一台机器时有一种常见做法是把物理 GPU 用CUDA_VISIBLE_DEVICES隔开让 NCCL 以为它们在跨节点通信虽然这不完全等价于真实网络但可以用来验证通信代码和协议选择是否正确。此外-t控制每个进程内的线程数一般保持默认即可调大线程数并不会自动提升带宽反而可能因为争抢硬件资源让结果变差。3.3 用环境变量干预协议与算法NCCL_PROTO、NCCL_ALGO 怎么用NCCL 在底层有多个协议实现LLLow Latency用 4 字节数据携带控制信息延迟低但带宽利用率打折LL128 是对 LL 的改进在 NVLink 全互联的拓扑下表现很好Simple 是默认协议带宽利用率高但延迟稍大。算法层面则有 Ring 和 Tree 两种主要模式Ring 在单机小规模下表现好Tree 在跨节点大规模下能摊薄带宽压力。这些协议和算法平时是 NCCL 自动选择的但你可以通过环境变量强制指定来观察差异# 对比 LL 协议下小消息的延迟表现 NCCL_PROTOLL ./build/all_reduce_perf -b 64 -e 64K -f 2 -g 8 -n 200 # 对比 Simple 协议下同一区间的表现 NCCL_PROTOSimple ./build/all_reduce_perf -b 64 -e 64K -f 2 -g 8 -n 200跑这两组命令时重点看从小到大的每一行 Time 和 busbw。如果 LL 在小消息区间明显占优而 Simple 在 32KB 以上开始反超你就知道自己的负载落在哪边该不该手动指定协议。做这类对比时有一个容易忽略的点-n迭代次数要加大小消息单次耗时太短噪声影响很大我一般会设 200 次以上-w预热次数也要保留不然第一次调用初始化会污染时间数据。需要提醒的是环境变量强制指定协议只是测试手段生产环境最好还是让 NCCL 自动选择除非你用 nccl-tests 拿到了非常明确的对比数据否则手动指定往往会导致某些消息大小下性能劣化。像 llama.cpp 这类推理框架的多卡实现对通信延迟极其敏感很多人一上来就开 LL结果在稍大消息段反而变慢这种问题用上面的对比命令一眼就能看出来。4. 多节点与多机集群跑出可信数据需要满足哪些前提4.1 多节点最小配置hostfile、NCCL_SOCKET_IFNAME 和共享文件系统单机测试跑通只是第一步真正有价值的多节点测试需要先确认三件事所有节点安装的 NCCL 版本一致、二进制文件在所有节点可访问、网络接口选择正确。版本不一致会导致协议协商失败表现就是跑起来报版本不匹配二进制文件可以通过共享存储解决或者手动复制到每个节点网络接口选择则完全靠环境变量来定。以下是我在一套双机 InfiniBand 环境下的启动命令mpirun --hostfile hosts -np 16 \ -x LD_LIBRARY_PATH \ -x NCCL_SOCKET_IFNAMEib0 \ ./build/all_reduce_perf -b 1M -e 128M -f 2 -g 8 -n 50hosts文件里写两行节点 IP 或者主机名-np 16表示总共 16 个进程对应两台机器各 8 个 GPU。-x LD_LIBRARY_PATH把本机的动态库路径传给远端进程这一步很容易漏如果漏了远端进程会报找不到 libnccl.so。NCCL_SOCKET_IFNAMEib0告诉 NCCL 使用哪个网络接口做通信在多网卡机器上不指定的话NCCL 可能选到管理网口导致跨节点带宽惨不忍睹但看起来又没有报错。如果你用的是 TCP 网络而不是 InfiniBand把NCCL_SOCKET_IFNAME指向对应的以太网接口名即可。跑的时候我第一次会带着NCCL_DEBUGINFO从输出里找到类似NET/IB或NET/Socket的行确认 NCCL 实际走了哪条路径。很多时候多节点性能不对根本原因是 NCCL 走了不期望的网口而不是网卡本身不行。4.2 判定网络瓶颈busbw 与网卡规格怎么对账多节点测试的意义在于用数据回答「网络是不是瓶颈」这个问题。我一般会做三组测试单机 8 卡、双机各 8 卡走 InfiniBand、双机各 8 卡强制走 TCP。三组数据放在一起对比问题通常就很清晰测试场景预期 busbw如果实际远低于预期单机 8 卡NVLink 互联接近 NVLink 理论带宽查 GPU 拓扑和 NCCL 版本双机 16 卡IB 互联接近 IB 单端口带宽查网口选择、GDR、MTU双机 16 卡TCP 互联接近 TCP 大包吞吐上限查连接数、缓冲区、中断绑定所谓「对账」就是把实测 busbw 和硬件规格做个除法。比如单端口 InfiniBand 理论带宽是 400Gbps折合 50GB/s但实际应用层能跑到 40GB/s 就算不错了如果你只跑到 10GB/s那就要往软件配置方向查。TCP 环境下跨节点 allreduce 的 busbw 还会受 TCP 单流带宽限制影响常见做法是开启多个连接NCCL 在 TCP 下默认会开多条连接但你要确认系统连接数限制没有卡住它。有一点要特别强调busbw 对不上号的时候不要第一时间怪网卡或交换机。先看 NCCL_DEBUGINFO 的日志里有没有警告再确认网卡固件、驱动版本和 NCCL 的兼容性。我遇到过好多次最后查出来是网卡驱动没更新导致的丢包重传而不是带宽不够。4.3 可复现性保障NCCL_DEBUG、缓冲区和多次取中位数多节点测试最怕的是结果不可复现。第一次跑出来 20GB/s第二次变成 8GB/s这种数据没法做依据。为了保证可复现性我一般会做三件事固定运行参数、锁定 GPU 频率、多次运行取中位数。# 锁定 GPU 频率为 1530MHz减少动态调频带来的抖动 nvidia-smi -lgc 1530 # 关闭可能干扰测量的后台进程然后跑测试 NCCL_DEBUGWARN ./build/all_reduce_perf -b 8 -e 256M -f 2 -g 8 -n 200 -w 50nvidia-smi -lgc会把 GPU 核心频率锁住否则不同批次的功耗和温度变化会影响通信时间。NCCL_DEBUGWARN只输出警告不影响性能但能帮你发现隐藏的异常比如某次通信超时重试。缓冲区大小也可以用NCCL_BUFFSIZE调整在大消息场景下适当调大减少缓冲区分配次数对稳定输出有帮助。多次运行取中位数而不是平均值因为第一次跑通常包含额外的初始化开销平均值会被这些离群值拉偏。我会把同一命令跑 3 到 5 次取中间值记录到基线表里。做任何系统调优之后都用同一个命令再跑一遍数据之间的比较才有说服力。5. 避坑与排查nccl-tests 运行中最常见的 5 个问题5.1 编译阶段报错找不到 mpi.h先分清是缺 MPI 还是 CUDA 路径不对现象在make MPI1时直接报fatal error: mpi.h: No such file or directory看起来像是系统没配好。原因这类报错九成是 MPI 开发头文件没装而不是代码问题。MPI1只是告诉编译器去系统搜索 MPI 头文件如果系统里只有 mpirun 没有 libopenmpi-dev头文件是不存在的。解决先跑which mpirun和dpkg -l | grep openmpi确认 MPI 是否完整安装。缺头文件就装apt install libopenmpi-dev如果 CUDA 路径也不对会报找不到cuda_runtime.h而不是 mpi.h所以看到 mpi.h 相关报错先不要怀疑 CUDA。只想快速验证测试流程的话make MPI0也能在单机下跑通但多节点测试前还是把 MPI 配好。5.2 单机直接跑就报 out of memory八成是显存被占或消息太大现象all_reduce_perf -b 1 -e 8G -f 2跑了一段时间后突然报Cuda runtime error: out of memory。原因这是最容易被忽视的一个。nccl-tests 要为每个消息大小分配通信缓冲区而且 NCCL 内部还要预留协议需要的辅助空间。当-e 8G这种大消息扫到后面两张卡上需要同时容纳消息本体和通信缓冲显存不够就崩了。解决先nvidia-smi看显存占用确认没有别的进程占着。然后缩小-e到 256M 或 1G 再跑。如果业务确实需要测 4GB 以上的大消息就用NCCL_BUFFSIZE手动控制缓冲大小并确保每张卡至少有消息大小的三五倍空闲显存。日常体检扫到 1GB 其实已经能覆盖绝大多数训练场景了。5.3 多节点跑的时候日志里全是 NET/IB timeout现象双机 InfiniBand 环境执行all_reduce_perfNCCL_DEBUGINFO输出中反复出现NET/IB ... timeout或者通信失败重试测试无法正常完成。原因常见的直接原因有三个网卡选错NCCL 用了一个不在期望链路上的 IB 设备IB 的 GID 索引不对导致数据包路由失败GDRGPU Direct RDMA配置不完整数据多走了一次主存拷贝。解决先用ibstat判断哪些 IB 设备可用然后显式指定NCCL_IB_HCAmlx5_0 NCCL_IB_GID_INDEX3 mpirun -np 16 --hostfile hosts ./build/all_reduce_perf -b 1M -e 128M -f 2 -g 8 -n 50NCCL_IB_HCA限定具体 IB 设备NCCL_IB_GID_INDEX用来选 GID 索引具体值在不同的子网配置下不一样需要试。如果确认是驱动或 GDR 问题可以先NCCL_IB_DISABLE1退回 TCP 网络跑通流程但这只是定位手段不是最终方案TCP 的带宽通常远低于 IB。5.4 同一命令前后两次测出来的 busbw 差一大截现象间隔几分钟跑完全相同的命令第一次 busbw 是 30GB/s第二次只有 18GB/s波动超过 30%。原因最常见的是 GPU 动态频率和温度变化其次是后台进程占用网络带宽或 CPU 中断导致抖动还有可能是消息缓冲区首次分配和后续重用的差异。解决执行nvidia-smi -lgc锁定 GPU 频率把其他占用网络和显存的任务排空。然后把-n从 100 提到 300-w从 25 提到 50增加采样量。跑完不要只记一个值多跑三四次取中位数。如果仍然跳来跳去打开NCCL_DEBUGINFO看是否有超时重传的痕迹有的话按 5.3 的方式排查网络配置。5.5 在容器里跑总是找不到设备或者性能异常低现象Docker 容器里执行./build/all_reduce_perf -g 2报找不到可用的 CUDA 设备或者能跑起来但 busbw 比宿主机低一半以上。原因容器没挂载 GPU 设备或者挂载了但没有传递NVIDIA_VISIBLE_DEVICES环境变量更隐蔽的是容器内缺少 NCCL 依赖的 IPC 相关挂载导致 NCCL 在容器里不能使用共享内存和 NVLink 的 IPC 通信退化了通信路径。解决用docker run --gpus all启动容器并确保宿主机和容器内的 NCCL 版本一致。跑测试前在容器内执行nvidia-smi确认能看到全部 GPU然后用NCCL_DEBUGINFO跑一遍看日志里是否出现NET/IB或IPC相关行如果发现原本应该走 NVLink 的路径变成了 socket再对比宿主机同样的命令就能确认是容器隔离导致的性能退化。6. 进阶验证技巧用 LL/LL128 协议校准小消息区间再对齐 llama.cpp 负载最后一层讲一个我实际用过的验证技巧用 nccl-tests 帮 llama.cpp 这类推理框架校准协议的适用区间。这类负载的特点是同步频繁、消息量不大通信延迟直接影响 token 生成速度。很多人拿到这类场景第一反应是开启 LL 协议但 LL 并不是所有小消息大小下都最优它只是延迟更低带宽利用率却可能更差。操作上我建议做一次小消息区间的双协议对比而不是直接改框架配置# 默认协议下的小消息延迟 ./build/all_reduce_perf -b 64 -e 1M -f 2 -g 8 -n 300 -w 50 # LL 协议下同样区间的延迟 NCCL_PROTOLL ./build/all_reduce_perf -b 64 -e 1M -f 2 -g 8 -n 300 -w 50跑完后把两组的 Time 列放在一起看。如果 LL 在 64 字节到 64KB 区间全面占优那 llama.cpp 这类负载值得在代码或启动参数里打开 LL 相关选项如果只是 8KB 以下占优那就要考虑收益是否值得改动。还有一种更常见的结果LL 在小消息胜出但从某个大小开始 Simple 反超这时你要判断模型通信单个张量平均落在哪一边而不是只看峰值。我自己的教训是曾经在一套 8 卡机器上想当然地为推理负载开启 LL结果吞吐反而下降后来用上面的对比命令一看模型的同步消息大多落在 256KB 到 1MB 区间正是 Simple 协议的地盘。从那以后我每次调协议之前都先用 nccl-tests 把这套负载的消息分布扫一遍再决定改不改配置。希望这个技巧能帮你在调协议参数时少走一次弯路。本文还有配套的精品资源点击获取