NCCL 测试

这些测试用于检查 NCCL 操作的性能和正确性。

构建

要构建测试，只需输入 make 或 make -j。

如果 CUDA 未安装在 /usr/local/cuda 目录下，可以指定 CUDA_HOME。同样地，如果 NCCL 未安装在 /usr 目录下，可以指定 NCCL_HOME。

$ make CUDA_HOME=/path/to/cuda NCCL_HOME=/path/to/nccl

NCCL 测试依赖 MPI 在多个进程甚至多个节点上运行。若希望编译支持 MPI 的测试，则需要设置 MPI=1 并将 MPI_HOME 设置为 MPI 的安装路径。

$ make MPI=1 MPI_HOME=/path/to/mpi CUDA_HOME=/path/to/cuda NCCL_HOME=/path/to/nccl

还可以通过 NAME_SUFFIX 为生成的二进制文件添加后缀。例如，在编译 MPI 版本时，可以使用：

$ make MPI=1 NAME_SUFFIX=_mpi MPI_HOME=/path/to/mpi CUDA_HOME=/path/to/cuda NCCL_HOME=/path/to/nccl

这将生成名为 all_reduce_perf_mpi 等的测试二进制文件。

使用

NCCL 测试可以在多个进程、多线程以及每个线程使用多个 CUDA 设备的情况下运行。进程数量由 MPI 管理，因此不会作为参数传递给测试程序。总的进程数（即 CUDA 设备总数）等于 (进程数) × (线程数) × (每线程 GPU 数)。

快速示例

在单节点上使用 8 个 GPU（-g 8），扫描从 8 字节到 128 MiB（Mebibytes），每次测试大小翻倍（-f 2）：

$ ./build/all_reduce_perf -b 8 -e 128M -f 2 -g 8

在包含 8 个 GPU 的节点上运行 64 个 MPI 进程，总共 64 个 GPU 分布在 8 个节点上。 扫描范围从 8 字节到 32 GiB（Gibibytes），每次测试大小翻倍（-f 2）。 （注意：在这种情况下，nccl-tests 二进制文件必须以 MPI=1 编译）

$ mpirun -np 64 -N 8 ./build/all_reduce_perf -b 8 -e 8G -f 2 -g 1

性能

有关数字的解释，尤其是“busbw”列，请参阅 性能 页面。

参数

所有测试都支持相同的参数集：

• GPU 数量
  • -t,--nthreads <线程数> 每个进程的线程数。默认值：1。
  • -g,--ngpus <每线程 GPU 数> 每个线程使用的 GPU 数量。默认值：1。
• 扫描尺寸
  • -b,--minbytes <最小字节数> 开始扫描的最小尺寸。默认值：32 MiB（Mebibytes）。
  • -e,--maxbytes <最大字节数> 结束扫描的最大尺寸。默认值：32 MiB（Mebibytes）。
  • 增量可以是固定值或乘法因子。两者只能选择其一。
    • -i,--stepbytes <增量字节数> 尺寸之间的固定增量。默认值：1 MiB（Mebibytes）。
    • -f,--stepfactor <增量因子> 尺寸之间的乘法因子。默认值：禁用。
• NCCL 操作参数
  • -o,--op <sum/prod/min/max/avg/all> 指定要执行的归约操作。仅对 Allreduce、Reduce 或 ReduceScatter 等归约操作有效。默认值：Sum。
  • -d,--datatype <nccltype/all> 指定要使用的数据类型。默认值：Float。
  • -r,--root <根/全部> 指定要使用的根。仅适用于具有根的操作，如广播或归约。默认值：0。
• 性能
  • -n,--iters <迭代次数> 迭代次数。默认值：20。
  • -w,--warmup_iters <预热迭代次数> 预热迭代次数（不计时）。默认值：1。
  • -m,--agg_iters <聚合次数> 每次迭代中要聚合的操作次数。默认值：1。
  • -N,--run_cycles <循环次数> 每个循环都运行并打印结果。默认值：1；0=无限。
  • -a,--average <0/1/2/3> 将性能报告为所有进程的平均值（仅限 MPI=1）。<0=Rank0,1=平均,2=最小,3=最大>。默认值：1。
• 测试操作
  • -p,--parallel_init <0/1> 使用线程并行初始化 NCCL。默认值：0。
  • -c,--check <检查迭代次数> 执行指定次数的迭代，每次迭代都检查结果的正确性。对于大量 GPU 而言，这可能会非常耗时。默认值：1。
  • -z,--blocking <0/1/2> 集体阻塞：1=等待完成并同步屏障，2=等待但不同步屏障。默认值：0。
  • -G,--cudagraph <图启动次数> 将迭代捕获为 CUDA 图，并重复播放指定次数。默认值：0。
  • -C,--report_cputime <0/1> 报告 CPU 时间而非延迟。默认值：0。
  • -R,--local_register <0/1/2> 在发送/接收缓冲区上启用本地（1）或对称（2）缓冲区注册。默认值：0。
  • -S,--report_timestamps <0/1> 在每行性能报告中添加时间戳（"%Y-%m-%d %H:%M:%S"）。默认值：0。
  • -J,--output_file <文件> 将 [JSON] 输出写入指定路径。根据后缀推断类型（目前仅支持 json）。
  • -T,--timeout <秒数> 在指定秒数后超时终止测试。默认值：禁用。
  • -M,--memory_report <0/1> 启用内存使用情况报告。默认值：0。
  • -u,--unalign <第一个元素索引> 源缓冲区和目标缓冲区不对齐。默认值：0。

并行运行多个操作

NCCL 测试允许将 GPU 集群划分为若干小组，每组并行执行相同的操作。为了划分 GPU，NCCL 会根据 NCCL_TESTS_SPLIT 环境变量为每个进程计算一个“颜色”，然后具有相同颜色的进程会被分配到同一组。测试开始时，每个 GPU 旁边都会显示其所属的组别。

NCCL_TESTS_SPLIT 的语法如下：<操作><值>。操作可以是 AND、OR、MOD 或 DIV。&、|、% 和 / 符号也受支持。值可以是十进制、十六进制（前缀为 0x）或二进制（前缀为 0b）。

NCCL_TESTS_SPLIT_MASK="<值>" 等同于 NCCL_TESTS_SPLIT="&<值>"。

以下是一些示例：

• NCCL_TESTS_SPLIT="AND 0x7" 或 NCCL_TESTS_SPLIT="MOD 8"：在拥有 8 个 GPU 的系统上，运行 8 个并行操作，每个节点 1 个 GPU（仅通过节点间网络通信）。

• NCCL_TESTS_SPLIT="OR 0x7" 或 NCCL_TESTS_SPLIT="DIV 8"：在拥有 8 个 GPU 的系统上，每个节点运行一个操作，完全在节点内部进行。

• NCCL_TESTS_SPLIT="AND 0x1" 或 NCCL_TESTS_SPLIT="MOD 2"：运行两个操作，每个操作使用间隔的进程。

请注意，报告的带宽是按组计算的，因此要获得所有组使用的总带宽，需将该数值乘以组数。

版权

NCCL 测试采用 BSD 许可证发布。所有源代码及配套文档的版权均属于 NVIDIA CORPORATION，版权所有，保留一切权利。

NCCL Tests 快速上手指南

NCCL Tests 是用于验证 NVIDIA NCCL 库性能与正确性的官方测试工具集，支持单卡、多卡及多节点集群环境。

1. 环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux (推荐 Ubuntu/CentOS)
• 硬件：NVIDIA GPU (建议多卡环境以测试通信性能)
• 前置依赖：
  • CUDA Toolkit：已安装并配置好环境变量。
  • NCCL Library：已安装 libnccl 和 libnccl-dev。
  • MPI (可选)：如需进行多节点或多进程测试，需安装 MPI (如 OpenMPI 或 MPICH)。
  • 编译工具：make, g++。

提示：国内用户可通过阿里云、腾讯云等镜像源加速安装 cuda-toolkit 和 libnccl2 等相关依赖包。

2. 安装步骤

克隆仓库后，进入目录即可编译。默认情况下，工具会尝试在标准路径 (/usr/local/cuda, /usr) 查找依赖。

基础编译（单节点/单机）

如果 CUDA 和 NCCL 安装在非标准路径，请通过环境变量指定：

make CUDA_HOME=/path/to/cuda NCCL_HOME=/path/to/nccl

注：若依赖均在默认路径，直接运行 make 或 make -j 即可。

启用 MPI 支持（多节点/集群）

若需在多节点或多进程环境下运行，必须开启 MPI 支持：

make MPI=1 MPI_HOME=/path/to/mpi CUDA_HOME=/path/to/cuda NCCL_HOME=/path/to/nccl

自定义二进制文件名（可选）

编译时可添加后缀以区分不同版本（例如 MPI 版本）：

make MPI=1 NAME_SUFFIX=_mpi MPI_HOME=/path/to/mpi CUDA_HOME=/path/to/cuda NCCL_HOME=/path/to/nccl

编译成功后，生成的可执行文件将带有 _mpi 后缀，例如 all_reduce_perf_mpi。

3. 基本使用

编译完成后，可执行文件位于 build/ 目录下。以下是两个最常用的场景示例。

场景一：单机多卡测试

在当前节点上使用 8 张 GPU 进行测试，数据大小从 8 Bytes 扫描至 128 MiB，每次翻倍。

./build/all_reduce_perf -b 8 -e 128M -f 2 -g 8

参数说明：

• -g 8: 使用 8 张 GPU。
• -b 8: 起始数据大小为 8 Bytes。
• -e 128M: 结束数据大小为 128 MiB。
• -f 2: 步长因子为 2（即数据量按 2 倍递增）。

场景二：多节点集群测试 (需 MPI)

在 8 个节点上运行，每个节点 8 张 GPU，共 64 张卡。数据大小从 8 Bytes 扫描至 8 GiB。 (注意：此场景必须使用开启了 MPI=1 编译的版本)

mpirun -np 64 -N 8 ./build/all_reduce_perf -b 8 -e 8G -f 2 -g 1

参数说明：

• -np 64: 总共启动 64 个进程。
• -N 8: 每个节点启动 8 个进程。
• -g 1: 每个线程绑定 1 张 GPU（总卡数 = 进程数 × 每线程卡数）。

结果解读

输出结果中的 busbw (Bus Bandwidth) 列是衡量 NCCL 通信性能的关键指标，数值越高代表带宽利用率越好。详细指标说明可参考项目文档 doc/PERFORMANCE.md。