【RCCL】RCCL工具

工具/脚本主要集中在 tools/，另外 NPKit 是 RCCL 内建的性能跟踪能力

概览

NPKit

• NPKit 文档与开关说明：rccl-usage-tips.rst
• NPKit 头文件：rccl\src\include\npkit
• NPKit trace 生成脚本：npkit_trace_generator.py
• NPKit trace 分析脚本：npkit_trace_analysis.py

调试/可视化

• RCCL Replayer：rccl\tools\rccl_replayer
• Topology Visualizer：rccl\tools\TopoVisual
• Topology Explorer：rccl\tools\topo_expl
• 编译时间线分析：rccl\tools\time-trace
• 内置拓扑映射：rccl\tools\built-in-topo

基准/测试/示例

• GraphBench：rccl\tools\GraphBench
• JitterBench：rccl\tools\JitterBench
• P2P latency test：rccl\tools\p2p-latency-test
• RCCL prim test：rccl\tools\rccl-prim-test
• EmptyKernelTest：rccl\tools\EmptyKernelTest
• HelloRccl：rccl\tools\HelloRccl
• IB test：rccl\tools\ib-test
• PyTorch all-reduce bench：rccl\tools\scripts\pytorch-all-reduce
• TransferBench（外部仓库指向）：rccl\tools\TransferBench

MSCCL 算法

• MSCCL algorithms：rccl\tools\msccl-algorithms
• MSCCL unit-test algorithms：rccl\tools\msccl-unit-test-algorithms

插件

• RDMA/SHARP plugins：rccl\tools\rccl-rdma-sharp-plugins-508-rccl-rdma-sharp-plugins-v8

说明

NPKit

1.NPKit 是什么？

NPKit (Networking Profiling Kit)是专为高性能集合通信库（Collective Communication Libraries, CCLs）设计的性能分析（Profiling）框架。由微软开发，最初主要用于优化其内部的 MSCCL 库，但现已扩展支持业界主流的NVIDIA NCCL和AMD RCCL。

简单来说，NPKit 就像是一个安装在 RCCL 内部的“黑匣子”或“高速摄像机”，能够以极低的开销记录通信操作内部极其细微的执行过程。

• 定位：它是一个轻量级的插桩（Instrumentation）工具集，通常以补丁（Patch）或源码修改的形式集成到 RCCL 中。
• 核心功能：允许开发者在 RCCL 的关键路径（特别是那些巨大的 GPU Kernel 内部）插入自定义的性能分析事件（Events）。
• 输出形式：它将收集到的事件数据生成标准的Chrome Trace Event格式文件。这意味着你可以直接在 Google Chrome 浏览器的chrome://tracing界面中打开这些文件，看到一个直观的时间轴视图。
• 支持对象：除了 AMD RCCL，它还支持 NVIDIA NCCL 和 Microsoft MSCCL。

2.为什么需要 NPKit？（解决什么痛点）

A. 传统工具的局限性（“黑盒”问题）

• 粒度太粗：常用的系统级工具（如nsys,roctx,perf）通常只能看到 RCCL 函数调用的开始和结束（例如rcclAllReduce耗时 5ms）。
• 无法洞察内部：它们无法告诉你这 5ms 具体花在了哪里。是数据传输慢？是 GPU Kernel 启动延迟？还是某个特定的微操作（Micro-kernel）效率低下？对于 RCCL 这种高度优化的库，其内部逻辑非常复杂，外部工具很难穿透。

B. NPKit 带来的核心价值

1. 内核级细粒度观测 (Kernel-Level Visibility)：
   RCCL 的许多操作是由巨大的 CUDA/HIP Kernel 完成的。NPKit 可以直接在这些 Kernel 内部打点，记录下每一个微小步骤（如数据分片、寄存器传输、共享内存同步等）的开始和结束时间。这让开发者能看到通信原语内部的“微观世界”。
2. 极低的重叠开销 (Low Overhead)：
   性能分析工具必须不能显著拖慢程序。NPKit 设计得非常轻量，使用高效的缓冲机制记录时间戳，确保在开启 profiling 时，对 RCCL 本身性能的影响最小化，从而获得真实的性能数据。
3. 统一的时间轴可视化 (Unified Timeline)：
   生成的 Chrome Trace 文件可以将 CPU 端的调度、RCCL 的内部逻辑、以及底层的 GPU Kernel 执行全部放在同一个时间轴上。

• • 场景举例：你可以清晰地看到 CPU 发起通信请求后，GPU 何时真正开始工作，中间是否有空闲等待（Gap），或者多个 GPU 之间的通信是否存在不同步（Straggler 问题）。

1. 辅助算法与拓扑优化：
   对于 RCCL 的开发者或高级用户，NPKit 是验证新通信算法（如新的 Ring 算法、Tree 算法）或针对特定硬件拓扑（如 AMD Infinity Fabric）进行优化的必备工具。没有它，优化工作往往只能靠猜或看宏观统计数据。

3. 总结

把 RCCL 比作一辆F1赛车：

• 普通监控工具只能告诉你“这辆车跑完一圈用了多少秒”。
• NPKit则能告诉你“在第三个弯道的入弯阶段，左后轮胎的抓地力在第 3.5 秒到 3.8 秒之间出现了微小的波动，导致速度下降了 0.2%”。

4. NPKit 用法

有关全自动使用示例，可参考 RCCL 的 NPKit 示例工作流 https://github.com/microsoft/NPKit/tree/main/rccl_samples。

RCCL 集成了NPKit性能分析框架 https://github.com/microsoft/npkit，

编译开启：

编译开启 NPKit 的 RCCL，可在 cmake 命令中添加参数：-DNPKIT_FLAGS="-DENABLE_NPKIT -DENABLE_NPKIT_..."

运行开启：

开启 NPKit 的 RCCL，需设置环境变量NPKIT_DUMP_DIR指定事件保存目录。

结果分析：

NPKit 采集结果，可使用脚本 npkit_trace_generator.py 分析https://github.com/microsoft/NPKit/blob/main/rccl_samples/npkit_trace_generator.py

注意事项

NPKit 仅支持采集 GPU 上非重叠的事件。

NPKit 每个进程仅支持一块 GPU。

• NPKit trace 生成脚本：npkit_trace_generator.py
• NPKit trace 分析脚本：npkit_trace_analysis.py

MSCCL/MSCCL++

MSCCL (Microsoft Collective Communication Library)和MSCCL++是由微软开发的一套高性能集合通信框架，旨在解决大规模分布式 AI 训练（特别是大语言模型）中的通信瓶颈问题。

1.MSCCL 是什么？

• 定义：MSCCL 是一个开源的集合通信库框架。
• 核心特性：

• • 可编程性：传统的 CCL（如 NCCL/RCCL）只提供固定的几种算法（如 Ring, Tree, Collnet）。MSCCL 允许开发者编写自定义的通信原语（Primitives），甚至针对特定的网络拓扑（如 Azure 的特定交换机架构）设计全新的算法。
  • 细粒度控制：它能精确控制数据在 GPU 显存、片上缓存（Shared Memory/LDS）、寄存器以及网络接口卡（NIC）之间的流动路径。
  • 跨平台支持：虽然起源于微软内部，但它已开源并支持 NVIDIA GPU (CUDA) 和 AMD GPU (ROCm/HIP)。在 AMD 生态中，MSCCL 常作为 RCCL 的强力补充或替代后端。

2.MSCCL++ 是什么？

• 定义：MSCCL++ 是 MSCCL 的下一代演进版本（有时也被称为 MSCCL 的 C++ 原生实现或高级抽象层）。
• 主要改进：

• • 纯 C++ 模板元编程：早期的 MSCCL 可能依赖特定的 DSL（领域特定语言）或脚本。MSCCL++ 利用现代 C++ 的模板元编程能力，让开发者直接用 C++ 代码描述通信逻辑。
  • 即时编译与优化：MSCCL++ 能够在运行时或加载时根据当前的硬件拓扑（Topology）和消息大小，即时生成高度优化的机器码（Kernel），消除了通用库为了兼容性而牺牲的性能开销。
  • 更复杂的流水线：它特别擅长处理复杂的通信 - 计算重叠（Overlap）和多流流水线，这对于隐藏大模型训练中的通信延迟至关重要。

3.为什么需要 MSCCL / MSCCL++？（解决什么痛点）

A. 突破“通用算法”的性能天花板

• 痛点：RCCL/NCCL 必须适配所有可能的硬件拓扑（从单机 8 卡到万卡集群）。因此，它们只能提供几种“万能”但非“最优”的算法（如标准的 Ring AllReduce）。
• MSCCL 方案：在特定的超级计算机架构（如 Azure NDv5 系列，使用 InfiniBand 或 RoCE 特定连接）上，标准的 Ring 算法可能不是最快的。MSCCL 允许微软工程师针对其特定的物理连线拓扑设计专属算法（例如跳过某些交换机跳数，或利用特定的 NVLink/NVSwitch 路径），从而榨干硬件的每一分带宽。

• • 案例：在某些特定拓扑下，MSCCL 定制的算法比标准 RCCL 快 20%-40%。

B. 应对大模型训练的“长尾延迟”

• 痛点：随着模型变大，通信模式变得极其复杂。通用的库难以处理非标准的通信模式（如 MoE 模型中的稀疏专家路由通信，或 3D 并行中的特殊数据切分）。
• MSCCL++ 方案：通过 C++ 编程，开发者可以精确控制每个数据包的发送时机和路径，实现极致的通信 - 计算重叠。它可以把原本串行的操作强行拆解并流水线化，掩盖网络延迟。

C. 快速适配新硬件与新协议

• 痛点：当新的网络技术（如 Ultra Ethernet Consortium, UEC）或新的 GPU 互联技术出现时，修改底层的 RCCL/NCCL 源码并等待官方发布新版本周期很长。
• MSCCL++ 方案：由于它是上层抽象且可编程的，开发者可以在不修改底层驱动的情况下，通过重写 MSCCL++ 的算法逻辑来快速适配新协议，验证新想法。

D. 填补 AMD ROCm 生态的算法空白

• 痛点：相比 NVIDIA 成熟的 NCCL，AMD 的 RCCL 在某些极端规模或特殊拓扑下的算法丰富度 historically 稍弱。
• MSCCL 方案：微软将 MSCCL 开源并移植到 ROCm 后，AMD 用户可以直接利用微软经过超大规模集群验证的高级通信算法，瞬间提升 RCCL 在特定场景下的性能表现。现在 ROCm 栈中经常能看到RCCL调用MSCCL后端来处理关键路径。

4.总结：RCCL、NPKit 、MSCCL三者的关系

如果把集合通信比作物流运输：

1. RCCL / NCCL像是标准的快递公司（如 FedEx/UPS）：

• • 提供标准的运输服务（Ring, Tree）。
  • 优点是通用、稳定、开箱即用。
  • 缺点是路线固定，无法为你的特殊货物定制最优路径。

1. NPKit像是物流追踪器：

• • 它不运货，只负责告诉你货在哪里卡住了，哪个环节慢了。

1. MSCCL / MSCCL++像是自建车队的调度系统：

• • 当你拥有成千上万辆车（万卡集群）且货物极其贵重（大模型训练）时，标准快递太慢或太贵。
  • 你使用 MSCCL++自己编写调度算法，根据实时的路况（网络拥塞）和车辆位置（GPU 拓扑），规划出独一无二的行驶路线。
  • 它能做到标准快递做不到的极致效率，但需要你（或微软这样的专家）具备极高的编程和优化能力。

NPKit VS MSCCL

1. 核心定位不同

5. MSCCL 用法

MSCCL 使用 XML 文件配置不同架构下的各类集合通信算法。

用户提供对应的 XML 文件后，RCCL 集合通信即可使用这些算法。

XML 文件中定义了核函数要执行的收发操作与归约操作序列。

5.1. 开启

MSCCL 在AMD Instinct™MI300X加速器上默认开启。

在其他平台上，可通过设置RCCL_MSCCL_FORCE_ENABLE=1强制开启。

默认情况下，只有每个进程对应唯一通信秩（rank）时才会使用 MSCCL。如需在多线程或单进程场景下取消该限制，可设置：RCCL_MSCCL_ENABLE_SINGLE_PROCESS=1。

对于特定大小的消息，RCCL 的 allreduce 和 allgather 可使用高效的 MSCCL++ 通信核。只要平台支持 MSCCL，就同时支持 MSCCL++。如需在 RCCL 任务中启用 MSCCL++，设置环境变量：

5.2. 启用

在 RCCL 任务中启用 MSCCL++

设置环境变量：RCCL_MSCCLPP_ENABLE=1

启用 MSCCL++ 的消息大小阈值

可使用环境变量RCCL_MSCCLPP_THRESHOLD，默认值为 1MB。 设置后，所有小于等于该阈值的消息都会使用 MSCCL++ 核。

5.3. 限制

使用 MSCCL++ 时有以下限制，不满足则会自动回退到 MSCCL 或原生 RCCL：

• 消息大小必须是 32 字节的非零整数倍
• 不支持hipMallocManaged分配的内存
• Allreduce 仅支持float16、int32、uint32、float32、bfloat16数据类型
• Allreduce 仅支持求和（sum）操作

5.4. 启用点对点传输

如需在采用 PCIe 连接的 GPU 服务器上开启点对点访问，设置 HSA 环境变量：

HSA_FORCE_FINE_GRAIN_PCIE=1

该功能要求 GPU 支持点对点访问，同时支持完整的大 BAR 寻址能力。

在 MI300X 上使用少于 8 张卡时提升性能

======================================

在配备 8 张 MI300X 的系统中，卡与卡之间通过专用 XGMI 链路形成全连接拓扑。

当使用全部 8 张卡时，集合通信能跑出理想性能；但使用少于 8 张卡时，带宽利用率会明显下降。

如果你的业务需要在 8 卡 MI300X 系统上使用少于 8 张卡，可以通过设置运行时变量NCCL_MIN_NCHANNELS增加通信通道数，例如：

export NCCL_MIN_NCHANNELS=32

增加通道数有助于提升性能，但也会提高集合通信的 GPU 占用。

此外，RCCL 已在 8 卡 MI300X 系统中对少量卡场景预设了更高通道数：

• 2 张卡时默认使用 32 个通道
• 4 张卡时默认使用 24 个通道

下面按你给的分组，基于仓库里的 README/脚本/源码给出可确认的用法。没有文档的我会明确说明，只依据源码/Makefile 推断到哪里。

调试/可视化

RCCL Replayer（d:\code\rccl\tools\rccl_replayer）
用途：回放 RCCL 日志，定位/复现 collective 问题。
用法（来自d:\code\rccl\tools\rccl_replayer\README.md）：

cd d:\code\rccl\tools\rccl_replayer MPI_DIR=/path/to/mpi make # 收集日志（每 rank 一个） NCCL_DEBUG=INFO NCCL_DEBUG_SUBSYS=COLL NCCL_DEBUG_FILE=some_name_here.%h.%p.log # 合并日志 cat some_name_here_*.log > some_name_here.log # 回放 mpirun -np <numProcesses> ./rcclReplayer </path/to/logfile> <numGpusPerMpiRank>

Topology Visualizer（d:\code\rccl\tools\TopoVisual）
用途：从 RCCL 日志/模拟输出提取拓扑并可视化。
用法（来自d:\code\rccl\tools\TopoVisual\README.md）：

# 先用 RCCL 日志收集拓扑信息 mpirun -np 4 -host host1,host2,host3,host4 \ -env HSA_FORCE_FINE_GRAIN_PCIE 1 -env NCCL_DEBUG INFO -env NCCL_DEBUG_SUBSYS INIT,GRAPH \ ~/rccl-tests/build/all_reduce_perf -b 8 -e 128M -f 2 -g 8 | tee ~/4_nodes.log # 生成可视化 ./topo_visual.sh -i 4_nodes.log

依赖：gawk、graphviz。

Topology Explorer（d:\code\rccl\tools\topo_expl）
用途：模拟/探索拓扑模型输出（TopoVisual 也支持读取其输出）。
用法（来自d:\code\rccl\tools\topo_expl\topo_expl.cpp）：

cd d:\code\rccl\tools\topo_expl make ./topo_expl -m model_id [-n numNodes=1]

如果没给-m，程序会打印可用的model_id列表。

编译时间线分析（d:\code\rccl\tools\time-trace）
用途：基于.ninja_log生成编译时间线图。
用法（来自d:\code\rccl\tools\time-trace\rccl-TimeTrace.sh）：

# 脚本默认读取 ../../build/release/.ninja_log bash rccl-TimeTrace.sh

脚本会安装pandas/plotly，并生成time_trace.log，调用time_trace_generator.py画图。
核心脚本：d:\code\rccl\tools\time-trace\time_trace_generator.py

内置拓扑映射（d:\code\rccl\tools\built-in-topo）
用途：包含内置拓扑映射 XML（topo_mapping_default.xml），无独立可执行程序。

基准/测试/示例

GraphBench（d:\code\rccl\tools\GraphBench）
用途：RCCL + HIP Graph 示例/基准。
用法（来自d:\code\rccl\tools\GraphBench\Makefile）：

cd d:\code\rccl\tools\GraphBench make # 运行（开启 HIP graph） RCCL_ENABLE_HIPGRAPH=1 LD_LIBRARY_PATH=..\..\build\release .\GraphBench

也可用make test或make testInfo（后者会加NCCL_DEBUG=INFO）。

JitterBench（d:\code\rccl\tools\JitterBench）
用途：测量 launch/时钟抖动等。
构建（d:\code\rccl\tools\JitterBench\Makefile）：

cd d:\code\rccl\tools\JitterBench make

运行参数（源码d:\code\rccl\tools\JitterBench\JitterBench.cpp）：

./JitterBench <NUM_BLOCKS> <BLOCKSIZE> <NUM_UPDATERS> <USE_NUMA> <NUM_ITERATIONS> <NUM_WARMUPS> <SLEEP_USEC>

也可用环境变量覆盖同名配置：NUM_BLOCKS、BLOCKSIZE、NUM_UPDATERS、USE_NUMA、NUM_ITERATIONS、NUM_WARMUPS、SLEEP_USEC。
示例扫参脚本：d:\code\rccl\tools\JitterBench\runSweep.sh

P2P latency test（d:\code\rccl\tools\p2p-latency-test）
用途：测量 GPU 间 P2P 延迟。
脚本示例（d:\code\rccl\tools\p2p-latency-test\build_and_run.sh）：

make export HSA_FORCE_FINE_GRAIN_PCIE=1 ./p2p_latency_test 0 1 ./p2p_latency_test 1 0 ./ll_latency_test 0 1 ./ll_latency_test 1 0

RCCL prim test（d:\code\rccl\tools\rccl-prim-test）
用途：测试 RCCL 原语性能。
构建：d:\code\rccl\tools\rccl-prim-test\Makefile
用法（源码中-h输出，d:\code\rccl\tools\rccl-prim-test\rccl_prim_test.cpp）：

./rccl_prim_test -w num_workgroups -p copy|localcopy|doublecopy|doublecopylocal|reduce|reducecopy|all \ -i iterations -n bytes -r "0 1 2 3|3 2 1 0"

EmptyKernelTest（d:\code\rccl\tools\EmptyKernelTest）
用途：空核 launch 基准。
构建（d:\code\rccl\tools\EmptyKernelTest\Makefile）：

cd d:\code\rccl\tools\EmptyKernelTest make

生成EmptyKernelTest（或检测到 nvcc 时生成EmptyKernelTestCuda），直接运行即可。

HelloRccl（d:\code\rccl\tools\HelloRccl）
用途：RCCL 最小示例。
构建（d:\code\rccl\tools\HelloRccl\Makefile）：

cd d:\code\rccl\tools\HelloRccl make

用法（源码d:\code\rccl\tools\HelloRccl\HelloRccl.cpp）：

单进程：./HelloRccl numRanks 多进程：NCCL_COMM_ID=host:port ./HelloRccl numRanks rank

示例脚本：d:\code\rccl\tools\HelloRccl\runTest.sh

IB test（d:\code\rccl\tools\ib-test）
用途：IB/RDMA 通道测试。
构建（d:\code\rccl\tools\ib-test\Makefile）：

cd d:\code\rccl\tools\ib-test make

参数来自源码解析（d:\code\rccl\tools\ib-test\ib_test.cpp）：

• -g <gpu>选择 GPU
• -c <channels>通道数
• -i <iters>迭代次数
• -r <0/1>GDR read
• -w <0/1>GDR write
• -n <numa>绑定 NUMA 节点
• -d <ip>作为发送端，目标 IP
• -p <port>与-d配合指定端口
  未带-d时进入接收模式。

PyTorch all-reduce bench（d:\code\rccl\tools\scripts\pytorch-all-reduce）
用途：gpt-fast all-reduce 小基准。
用法（d:\code\rccl\tools\scripts\pytorch-all-reduce\README.md）：

torchrun --nproc_per_node=8 all_reduce.py ENABLE_INTRA_NODE_COMM=1 torchrun --nproc_per_node=8 python3 all_reduce.py ENABLE_INTRA_NODE_COMM=1 bash trace_runs.sh

TransferBench（d:\code\rccl\tools\TransferBench）
本仓库只是指向外部项目，README 指向ROCm/TransferBench。
本仓库内的使用说明在d:\code\rccl\docs\how-to\troubleshooting-rccl.rst，示例流程：

git clone https://github.com/ROCm/TransferBench.git cd TransferBench make USE_FINE_GRAIN=1 GFX_UNROLL=2 ./TransferBench a2a 64M 8

MSCCL 算法

MSCCL algorithms（d:\code\rccl\tools\msccl-algorithms）
MSCCL unit-test algorithms（d:\code\rccl\tools\msccl-unit-test-algorithms）
这些目录是 MSCCL 算法 XML 文件集合，本身不是可执行工具。
RCCL/MSCCL 会根据配置选择并使用这些 XML，说明见d:\code\rccl\docs\how-to\rccl-usage-tips.rst的 “MSCCL/MSCCL++” 小节。

如果你希望我把某个工具的完整参数说明整理成更详细的“使用手册”，告诉我工具名即可。