oam-tools HCCL Test 集合通信性能测试工具命令行参数全解析【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools在昇腾多卡、多机分布式训练场景中集合通信AllReduce、AllGather、Broadcast 等算子的性能往往直接决定通信耗时与整体训练效率。oam-tools 仓库内置的 HCCL Test 工具通过mpirun拉起多进程、对各类 HCCL 集合通信算子做带宽与耗时压测其命令行参数覆盖了 MPI 启动层MPICH / Open MPI与 HCCL Test 工具本体两个层面。本文以仓库文档 docs/zh/hccl_test/cmdline_options_desc.md 为主线逐一讲解每类参数的含义、默认值与约束并结合 src/hccl_test/common/src/hccl_test_common.cc 等源码说明参数解析、默认值计算与合法性校验的底层实现帮助你在单机到大规模集群环境中正确配置并执行性能测试。一、命令格式MPI 启动参数与 HCCL Test 工具参数两段式结构HCCL Test 的执行命令由mpirun及其参数、./bin/executable_file可执行文件及其参数两部分拼接而成。安装 MPICH 的场景mpirun [-f hostfile] -n number ./bin/executable_file [-p npus] [-b minbytes] [-e maxbytes] [-f incfactor] [-o operator] [-r root] [-d datatype] [-z 0/1] [-n iters_count] [-w warmup_iters_count] [-c 0/1]安装 Open MPI 的场景mpirun [--prefix mpi_install_path] [-hostfile hostfile] -n number -x env [--allow-run-as-root] [--mca key value] ./bin/executable_file [-p npus] [-b minbytes] [-e maxbytes] [-f incfactor] [-o operator] [-r root] [-d datatype] [-z 0/1] [-n iters_count] [-w warmup_iters_count] [-c 0/1]两个约定需要记住mpirun之后跟随的是MPI 命令相关参数决定在哪些节点上拉起多少进程、环境变量如何传递./bin/executable_file之后跟随的是HCCL Test 工具相关参数决定测什么算子、数据量、迭代次数、是否校验等。从源码结构看工具进程启动后先调用MPI_Init再依次执行命令行解析parse_cmd_line、MPI 进程信息获取get_mpi_proc、参数合法性校验check_cmd_line、设备初始化device_init与测试执行start_test完整调用链见 hccl_test_main.cc。因此MPI 参数决定了 rank 总数与进程分布HCCL Test 参数决定了每个 rank 内部的通信行为。配套的完整执行流程环境变量配置、Hostfile 模板、结果输出解读可参见 工具执行参数取值约束可参见 规格约束。二、MPICH 命令参数文档中仅列出 MPICH 的常见参数更多参数请查阅 MPICH 官方文档-f hostfile可选Hostfile 节点列表文件。单机场景下无需配置此文件多机场景下必须配置。可配置为 Hostfile 文件的绝对路径或相对于当前执行命令的相对路径。-n number必选需要启动的NPU 总数即节点数量 * 每个节点上参与训练的 NPU 个数。从源码实现看-n启动的进程数直接决定了通信域规模get_mpi_proc通过MPI_Comm_size/MPI_Comm_rank获取全局 rank 总数proc_size与当前进程编号proc_rank并以此作为 HCCL 通信域的rank_size/rank_id见 hccl_test_common.cc。因此-n必须与 Hostfile 中各节点进程数之和一致且是后文-r root取值范围、校验能力上限如归约类算子的卡数限制的直接依据。多机场景下 MPICH 会默认将当前节点的环境变量同步到其他节点若各节点环境变量存在差异官方建议将环境变量写入执行脚本再传给mpirun详见 工具执行 第 4 步的run.sh示例。三、Open MPI 命令参数Open MPI 的常见参数说明如下--prefix mpi_install_path可选配置 Open MPI 的安装路径。一般单机场景下无需配置此参数多机场景下需要配置否则可能会出现无法获取 MPI 库文件的问题。-hostfile hostfile可选指定 Hostfile 节点列表文件。单机场景下无需配置此文件多机场景下需要配置。可配置为绝对路径或相对于当前执行命令的相对路径。-n number必选设置需要启动的 NPU 总数即节点数量 * 每个节点上参与训练的 NPU 个数。-x env必选指定需要传递给远程节点的环境变量名称。Open MPI 不会像 MPICH 那样自动同步全部环境变量必须用-x显式列出例如-x LD_LIBRARY_PATH -x HCCL_SOCKET_IFNAME -x HCCL_BUFFSIZE这是两种 MPI 实现最易踩坑的差异之一。--allow-run-as-root可选允许 mpirun 使用 root 用户执行。--mca key value可选设置 MCAMPI Component Architecture参数用于在运行时加载 Open MPI 的各类组件模块。常用的命令有--mca btl_tcp_if_include nic_name使用指定网卡进行节点间通信例如--mca btl_tcp_if_include eth0--mca opal_set_max_sys_limits 1让 Open MPI 运行时的系统限制文件描述符数量等沿用系统的ulimit配置避免进程因资源限制出问题。当集群中卡的数量较多时建议增加此配置。一个多机 Open MPI 的完整示例摘自 工具执行mpirun --prefix /usr/local/openmpi -hostfile hostfile \ -x ASCEND_HOME_PATH -x LD_LIBRARY_PATH \ -x HCCL_SOCKET_FAMILY -x HCCL_SOCKET_IFNAME -x HCCL_CONNECT_TIMEOUT -x HCCL_BUFFSIZE \ --allow-run-as-root --mca btl_tcp_if_include eth0 --mca opal_set_max_sys_limits 1 \ -n 16 ./bin/all_reduce_test -p 16 -b 8K -e 64M -i 0 -o sum -d fp32 -w 3 -n 3注意其中-x传递的环境变量HCCL_SOCKET_IFNAME、HCCL_BUFFSIZE等是 HCCL 通信域初始化的关键配置配置方法可参见 工具执行 第 2 步。四、HCCL Test 工具参数详解4.1 可执行文件选择要压测的集合通信算子./bin/executable_file必选集合通信性能测试工具的执行命令executable_file为支持的测试命令。HCCL Test 工具支持的测试命令包括broadcast_test、all_gather_test、all_gatherv_test、reduce_test、all_reduce_test、scatter_test、reduce_scatter_test、reduce_scatterv_test、alltoall_test、alltoallv_test、alltoallvc_test。各测试命令在不同产品上的支持情况以对应通信算子接口的实际支持能力为准。从源码结构看这些命令与 src/hccl_test/opbase_test/ 目录下的实现文件一一对应如 hccl_allreduce_rootinfo_test.cc、hccl_brocast_rootinfo_test.cc 等每个可执行文件对应一种算子的测试用例构建规则见 src/hccl_test/CMakeLists.txt。4.2 设备与根节点-p npus 或 --npus npus可选单个计算节点上参与训练的 NPU 个数。默认为当前节点的 NPU 总数若单个节点上参与的 NPU 个数小于节点 NPU 总数此参数为必填项。工具会按照该参数启动相应数量的 Device。源码中npus初始值为-1hccl_test_common.h当未显式配置-p时get_mpi_proc会将npus回退为本机aclrtGetDeviceCount返回的 Device 总数hccl_test_common.cc。此外Device 的映射规则为dev_id proc_rank % npus如果设置了环境变量HCCL_TEST_USE_DEVS如export HCCL_TEST_USE_DEVS4,5,6,7则改用指定的 Device ID 列表按轮询方式分配hccl_test_common.cc且-p取值会被校验必须落在[1, dev_count]区间内见 check_cmd_line。-r root 或 --root root可选执行broadcast_test、reduce_test、scatter_test时需要通过此参数指定根节点的 Device ID。取值范围[0, 实际Device数量-1]默认值为 0。源码中root_rank默认值为 0并在check_cmd_line中校验0 root_rank rank_size越界会直接报错退出hccl_test_common.cc。4.3 数据量与增量方式-b / -e / -i / -f这是决定每轮迭代测试数据大小的参数组四者联动-b minbytes 或 --minbytes minbytes可选测试数据大小的起始值最小值。默认值64M单位支持 K、M、G。-e maxbytes 或 --maxbytes maxbytes可选测试数据大小的结束值最大值。默认值64M单位支持 K、M、G。当-e等于-b时每次迭代按固定数据量测试当-e大于-b时需要设置数据增量类型-i与-f二选一配置即可。-i incsize 或 --stepbytes incsize可选数据增量类型为步长方式单位 Bytes。例如配置为 100则每次增量步长为 100 Bytes配置值仅为数字无需带单位。默认开启-i增量步长方式默认步长计算方式为(测试数据大小的结束值 - 测试数据大小的起始值) / 10当-i取值为 0 时按照-b定义的起始数据量持续测试。说明HCCL Test 工具执行时会对部分算子的-b、-e、-i所输入的数据量进行地址对齐或 rank size 倍数的微调以达到更优性能。-f incfactor 或 --stepfactor incfactor可选数据增量类型为乘法因子方式要求因子大于 1.0。配置示例原文档-b 100M -e 400M -i 0按照起始值 100MB 持续测试-b 100M -e 400M -i 500以 100MB 为起始值、每步增长 500 Bytes 的步长测试直至结束-b 100M -e 400M -f 2起始 100MB、结束 400MB、乘法因子 2则每次迭代分别取 100MB、200MB、400MB 的数据进行测试。源码佐证单位解析parsesize函数将K/k、M/m、G/g后缀分别按 1024 的幂展开hccl_test_common.cc这也解释了为什么文档中单位是 K/M/G 但内部全部换算成 Bytes。默认步长check_data_count中定义了defaultStepFactor 10用户未配置-i且-e -b时step_bytes (max_bytes - min_bytes) / 10若-e -b且未配置-i步长被强制置为 1 以防死循环hccl_test_common.cc。rank size 对齐当算子需要 ranksize 对齐时need_ranksize_alignment工具会把min_bytes、max_bytes对齐到rank_size * 512的倍数超过 16MB 的BUF_ALGIN_LINE阈值后并把步长向上取整对齐到rank_size的倍数hccl_test_common.cc。常量BUF_ALGIN_SIZE 512、BUF_ALGIN_LINE 16 * 1024 * 1024定义于 hccl_test_common.h。这正是文档所说“对数据量进行地址对齐或 rank size 倍数微调”的实现。冲突处理-f与-i同时配置时会告警并优先启用-f-f取值必须大于 1.0否则报错hccl_test_common.cc。4.4 归约操作与数据类型-o operator 或 --op operator可选Reduce 相关执行命令的操作类型包含sum、prod、max、min默认值为 sum。Reduce 相关的执行命令有all_reduce_test、reduce_scatter_test、reduce_scatterv_test、reduce_test。-d datatype 或 --datatype datatype可选HCCL Test 支持的数据类型默认值为 fp32。支持int8、uint8、int16、uint16、int32、uint32、int64、uint64、fp16、fp32、fp64、bfp16、fp8e5m2、fp8e4m3、fp8e8m0、hif8。各测试命令在不同产品上支持的数据类型以对应通信算子接口的实际支持能力为准。源码佐证HcclTest成员op_type初始化为HCCL_REDUCE_SUM、dtype初始化为HCCL_DATA_TYPE_FP32hccl_test_common.h与文档声明的默认值一致。-o经get_hccl_op_from_str映射为 HCCL 归约枚举-d经get_hccl_dtype_from_str映射为数据类型枚举两者若映射失败会在校验阶段报错并提示使用-h/--helphccl_test_common.cc。数据类型与卡数规模相关的数据校验上限例如乘/加操作在不同数据类型下的最大支持卡数可参见 工具执行 中的“结果说明”部分。4.5 零拷贝与对称内存-z 与 -m-z 0/1 或 --zero_copy 0/1可选是否开启零拷贝功能。单算子模式下输入输出 buffer 动态变化HCCL 会使用中间 buffer 中转完成集合通信引入额外的内存拷贝开销零拷贝功能直接对业务传入的内存进行操作从而降低拷贝开销、提升性能。0默认值不开启1开启。说明“零拷贝”为试用功能后续可能存在变更暂不支持应用于生产环境。零拷贝功能生效约束条件仅支持 Atlas A3 训练系列产品 / Atlas A3 推理系列产品仅支持执行reduce_scatter_test、all_gather_test、all_reduce_test、broadcast_test命令仅支持通信算法的编排展开位置在 AI CPU 的场景。-m 0/1 或 --symmetric_memory 0/1可选是否开启对称内存功能。作用与零拷贝类似——降低中间 buffer 拷贝开销、直接操作业务内存以提升性能。0默认值不开启1开启。对称内存功能生效约束条件仅支持 Ascend 950PR / Ascend 950DT、Atlas A3 训练系列产品 / Atlas A3 推理系列产品仅支持通信算子展开模式为 AI CPU 的场景展开模式由环境变量HCCL_OP_EXPANSION_MODE控制针对 Ascend 950PR / Ascend 950DT仅支持超节点内通信仅支持执行reduce_scatter_test、all_gather_test、all_reduce_test、alltoall_test、alltoallvc_test、broadcast_test仅支持 URMA 通信场景针对 Atlas A3 系列仅支持超节点内通信仅支持执行reduce_scatter_test、all_gather_test、all_reduce_test、alltoall_test仅支持超节点内 AI Server 间使用 HCCS 链路进行 SDMA 通信的场景不支持使用 RoCE 进行 RDMA 通信的场景即不支持设置HCCL_INTER_HCCS_DISABLE为 “TRUE”单机场景该环境变量无效仅支持对称组网每个 server 内卡数相同。注不支持零拷贝和对称内存功能同时开启。源码佐证参数解析时-z写入enable_zero_copy、-m写入enable_symmetric_memoryhccl_test_common.cc两个布尔成员定义于 hccl_test_common.h。check_cmd_line中显式校验二者互斥同时开启会直接报错退出Error: Zero-copy and symmetric memory cannot be enabled simultaneously.hccl_test_common.cc与文档的“注”完全对应。对称内存的物理内存注册路径可见register_symmetric_memory/deregister_symmetric_memory与symmetric_handle、symmetric_memory_size等成员hccl_test_common.h说明其实现依赖预注册的物理内存句柄。从源码的选项表构建逻辑看build_longoptshccl_test_common.cc910_95 平台分支没有zero_copy与nslb短选项而是提供accelerator-a选项其他平台则有-z、-s而无-a。这与文档中按产品分节描述-z/-m/-a适用平台的口径一致。4.6 加速模式-a仅 Ascend 950PR / Ascend 950DT-a HcclAccelerator 或 --accelerator HcclAccelerator可选该参数仅支持 Ascend 950PR / Ascend 950DT用于设置加速模式default使用默认自适应加速模式会根据组网、数据量等情况自动选择合适的模式aicpu_ts使用 Device 侧的 AI CPU 计算单元加速aiv使用 Device 侧的 Vector Core 计算单元加速大数据量情况下可能会回退到其他加速模式ccu_ms使用 CCU MSMemory Slice模式加速。Ascend 950PR 不支持此配置ccu_sched使用 CCU 调度模式加速host_ts不支持此配置aiv_only使用 Device 侧的 AI Core 计算单元加速相较于aiv加速模式不会发生回退情况。注该配置的优先级高于环境变量HCCL_OP_EXPANSION_MODE。源码佐证parse_cmd_line中存在一段默认值逻辑——在 910_95 平台且未设置HCCL_OP_EXPANSION_MODE环境变量时accelerator_config被默认置为 6代码注释标明即CCU_SCHED模式hccl_test_common.cc。此外-a的取值与-t仅 Device 侧计时存在组合约束当-t 1且加速模式为aicpu_ts时check_only_device_exec_time会直接报错hccl_test_common.cc对应 help 输出中 “not support aicpu_ts” 的提示。4.7 迭代、预热、仅 Device 侧计时与结果校验-s 0/1 或 --nslb 0/1可选是否启用 NSLB-DPNetwork Scale Load Balance - Data Plane数据面网络级负载均衡功能。0默认值不启用1启用。-n iters_count 或 --iters iters_count可选迭代次数默认值为 20。-w warmup_iters_count 或 --warmup_iters warmup_iters_count可选预热迭代次数。此参数不参与性能统计仅影响工具执行耗时默认值10。说明由于前几轮迭代可能存在影响性能测试的操作例如首轮迭代的 socket 建链操作等建议将前几轮迭代设置为预热迭代不进入性能统计。-t 或 --onlydevicetime可选将通信算子在 Host 侧的软件耗时与 kernel 加载耗时排除在通信执行耗时之外仅统计 Device 侧的执行时间即影响 HCCL Test 执行耗时的关键部分。0默认值不开启统计通信算子执行的全部耗时1开启仅统计 Device 侧执行耗时。开启该功能时需注意仅支持通信算法的编排展开位置为 Device 侧的 Vector Core 或 CCUHCCL_BUFFSIZE的配置值需要大于 100MB否则不生效-w与-n参数取值不能大于 100。-c 0/1 或 --check 0/1可选是否开启集合通信操作结果正确性校验。0不开启校验1默认值开启校验不输出详细错误信息2开启校验并输出详细错误信息。说明大规模集群场景下开启结果校验会使 HCCL Test 工具的执行耗时增加。源码佐证默认值成员变量一目了然iters 20、warmup_iters 10、check 1hccl_test_common.h与文档声明完全一致。check_cmd_line对迭代/预热/校验参数做了硬性约束-w、-n不能为负-c只能取 0/1/2-r必须落在[0, rank_size-1]hccl_test_common.cc。-t的约束由check_only_device_exec_time实现-t只允许 0/1开启时-w、-n不得超过 100否则报错hccl_test_common.cc。-t与HCCL_BUFFSIZE的联动是文档未展开、源码中可直接确认的细节当-t 1但环境变量HCCL_BUFFSIZE 100MB时工具会打印告警并自动把-t重置为 0hccl_test_common.cc——即文档所说“否则不生效”的具体行为。HCCL_BUFFSIZE未设置时内部默认值为 200MBhccl_test_common.cc。从set_env_resource可以看到工具在未显式设置HCCL_OP_RETRY_ENABLE时会自动注入L0:0, L1:0, L2:0关闭通信算子重执行以保证测试行为的可复现性hccl_test_common.cc。校验-c的结果会体现在工具输出的check_result列success / failed / NULL中各字段含义及归约类算子溢出导致无法校验的卡数上限表参见 工具执行 的“结果说明”。五、参数速查表参数长选项默认值说明-b--minbytes64M测试数据起始值单位 K/M/G-e--maxbytes64M测试数据结束值单位 K/M/G-i--stepbytes(e-b)/10增量步长Bytes0 表示按-b持续测试-f--stepfactor—增量乘法因子须大于 1.0与-i同配时优先生效-n--iters20参与统计的迭代次数-w--warmup_iters10预热迭代次数不参与性能统计-o--opsum归约操作sum / prod / max / min-d--datatypefp32数据类型共 16 种含 fp8 系列与 hif8-r--root0broadcast / reduce / scatter 的根节点 Device ID-p--npus本机 NPU 总数单节点参与训练的 NPU 个数-c--check1结果校验0 关闭 / 1 开启 / 2 开启并输出详细信息-z--zero_copy0零拷贝试用功能与-m互斥-m--symmetric_memory0对称内存与-z互斥-s--nslb0启用 NSLB-DP 数据面网络级负载均衡-t--onlydevicetime0仅统计 Device 侧执行耗时要求 HCCL_BUFFSIZE100MB-n/-w≤100-a--acceleratordefault加速模式仅 Ascend 950PR/950DT优先级高于 HCCL_OP_EXPANSION_MODE-h--help—打印帮助信息-a与-z/-s按平台互斥出现910_95 平台选项表包含accelerator其他平台包含zero_copy、nslb见 hccl_test_common.cc 中按IsSupport910_95()分支构造的getopt_long选项串。六、典型执行示例与输出解读单机 8 卡 AllReduce 压测MPICH 场景摘自 工具执行mpirun -n 8 ./bin/all_reduce_test -b 8K -e 64M -f 2 -d fp32 -o sum -p 8-b 8K -e 64M -f 2数据量从 8KB 起按因子 2 翻倍直至 64MB共 14 个数据点-p 8本节点 8 个 NPU 全部参与不指定-i时走默认步长逻辑但因指定了-f乘法因子优先生效。多机 2 节点 16 卡示例mpirun -f hostfile -n 16 ./bin/all_reduce_test -p 8 -b 8K -e 64M -f 2 -d fp32 -o sum工具按数据量逐行输出统计结果字段包括data_size单 NPU 参与通信的数据量Bytes、avg_time算子执行耗时us、alg_bandwidth算法带宽 通信数据量 / 耗时GB/s、check_result校验标识success / failed / NULL。check_result为 NULL 的两种情况-c 0未开启校验或算子结果溢出超出可精确表达范围导致无法校验。更多常见执行问题可参考 常见问题。七、参数行为在源码中的完整链路综合上述分析一个 HCCL Test 参数从命令行到生效的链路是解析parse_cmd_line用getopt_long按平台分支构造短/长选项串o:d:b:e:i:f:r:n:w:c:p:z:s:t:m:a:h的子集逐选项交给parse_opt写入HcclTest成员变量hccl_test_common.ccrank 与 Device 绑定get_mpi_proc将全局 MPI rank 映射为 HCCL rank并按proc_rank % npus或HCCL_TEST_USE_DEVS列表确定本进程使用的 Devicehccl_test_common.cc校验check_cmd_line串联check_data_count数据量与增量合法性、rank size 对齐、各枚举合法性、-p范围、-r范围、-c范围、-t组合约束、零拷贝/对称内存互斥等全部规则hccl_test_common.cc环境变量联动get_env_resource读取HCCL_TEST_PROFILING、HCCL_TEST_PROFILING_PATH、HCCL_BUFFSIZE并启动 profiling-t与HCCL_BUFFSIZE的不匹配在此被降级处理hccl_test_common.cc执行start_test按data_size逐个数据点执行warmup_iters轮预热 iters轮正式迭代-t 1时通过start_profile_device_time_if_needed/end_profile_device_time_if_needed仅统计 Device 侧耗时接口定义见 hccl_test_common.h。工具入口、参数校验、默认值、对齐策略均可以在 src/hccl_test/common/src/ 下对照阅读每个算子测试用例的行为差异体现在 src/hccl_test/opbase_test/ 中对应文件对init_send_recv_size_by_data、hccl_op_base_test等虚函数的实现。参考参数说明本文主线docs/zh/hccl_test/cmdline_options_desc.md工具执行环境变量、Hostfile、示例与输出解读docs/zh/hccl_test/execution.md规格约束docs/zh/hccl_test/restrictions.md工具介绍docs/zh/hccl_test/introduction.md安装与编译docs/zh/hccl_test/inst_and_compile.md核心实现hccl_test_main.cc、hccl_test_common.cc、hccl_test_common.h算子测试用例src/hccl_test/opbase_test/默认 Hostfile 模板src/hccl_test/hostfile【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 oam-tools HCCL Test 集合通信性能测试工具命令行参数全解析
oam-tools HCCL Test 集合通信性能测试工具命令行参数全解析【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools在昇腾多卡、多机分布式训练场景中集合通信AllReduce、AllGather、Broadcast 等算子的性能往往直接决定通信耗时与整体训练效率。oam-tools 仓库内置的 HCCL Test 工具通过mpirun拉起多进程、对各类 HCCL 集合通信算子做带宽与耗时压测其命令行参数覆盖了 MPI 启动层MPICH / Open MPI与 HCCL Test 工具本体两个层面。本文以仓库文档 docs/zh/hccl_test/cmdline_options_desc.md 为主线逐一讲解每类参数的含义、默认值与约束并结合 src/hccl_test/common/src/hccl_test_common.cc 等源码说明参数解析、默认值计算与合法性校验的底层实现帮助你在单机到大规模集群环境中正确配置并执行性能测试。一、命令格式MPI 启动参数与 HCCL Test 工具参数两段式结构HCCL Test 的执行命令由mpirun及其参数、./bin/executable_file可执行文件及其参数两部分拼接而成。安装 MPICH 的场景mpirun [-f hostfile] -n number ./bin/executable_file [-p npus] [-b minbytes] [-e maxbytes] [-f incfactor] [-o operator] [-r root] [-d datatype] [-z 0/1] [-n iters_count] [-w warmup_iters_count] [-c 0/1]安装 Open MPI 的场景mpirun [--prefix mpi_install_path] [-hostfile hostfile] -n number -x env [--allow-run-as-root] [--mca key value] ./bin/executable_file [-p npus] [-b minbytes] [-e maxbytes] [-f incfactor] [-o operator] [-r root] [-d datatype] [-z 0/1] [-n iters_count] [-w warmup_iters_count] [-c 0/1]两个约定需要记住mpirun之后跟随的是MPI 命令相关参数决定在哪些节点上拉起多少进程、环境变量如何传递./bin/executable_file之后跟随的是HCCL Test 工具相关参数决定测什么算子、数据量、迭代次数、是否校验等。从源码结构看工具进程启动后先调用MPI_Init再依次执行命令行解析parse_cmd_line、MPI 进程信息获取get_mpi_proc、参数合法性校验check_cmd_line、设备初始化device_init与测试执行start_test完整调用链见 hccl_test_main.cc。因此MPI 参数决定了 rank 总数与进程分布HCCL Test 参数决定了每个 rank 内部的通信行为。配套的完整执行流程环境变量配置、Hostfile 模板、结果输出解读可参见 工具执行参数取值约束可参见 规格约束。二、MPICH 命令参数文档中仅列出 MPICH 的常见参数更多参数请查阅 MPICH 官方文档-f hostfile可选Hostfile 节点列表文件。单机场景下无需配置此文件多机场景下必须配置。可配置为 Hostfile 文件的绝对路径或相对于当前执行命令的相对路径。-n number必选需要启动的NPU 总数即节点数量 * 每个节点上参与训练的 NPU 个数。从源码实现看-n启动的进程数直接决定了通信域规模get_mpi_proc通过MPI_Comm_size/MPI_Comm_rank获取全局 rank 总数proc_size与当前进程编号proc_rank并以此作为 HCCL 通信域的rank_size/rank_id见 hccl_test_common.cc。因此-n必须与 Hostfile 中各节点进程数之和一致且是后文-r root取值范围、校验能力上限如归约类算子的卡数限制的直接依据。多机场景下 MPICH 会默认将当前节点的环境变量同步到其他节点若各节点环境变量存在差异官方建议将环境变量写入执行脚本再传给mpirun详见 工具执行 第 4 步的run.sh示例。三、Open MPI 命令参数Open MPI 的常见参数说明如下--prefix mpi_install_path可选配置 Open MPI 的安装路径。一般单机场景下无需配置此参数多机场景下需要配置否则可能会出现无法获取 MPI 库文件的问题。-hostfile hostfile可选指定 Hostfile 节点列表文件。单机场景下无需配置此文件多机场景下需要配置。可配置为绝对路径或相对于当前执行命令的相对路径。-n number必选设置需要启动的 NPU 总数即节点数量 * 每个节点上参与训练的 NPU 个数。-x env必选指定需要传递给远程节点的环境变量名称。Open MPI 不会像 MPICH 那样自动同步全部环境变量必须用-x显式列出例如-x LD_LIBRARY_PATH -x HCCL_SOCKET_IFNAME -x HCCL_BUFFSIZE这是两种 MPI 实现最易踩坑的差异之一。--allow-run-as-root可选允许 mpirun 使用 root 用户执行。--mca key value可选设置 MCAMPI Component Architecture参数用于在运行时加载 Open MPI 的各类组件模块。常用的命令有--mca btl_tcp_if_include nic_name使用指定网卡进行节点间通信例如--mca btl_tcp_if_include eth0--mca opal_set_max_sys_limits 1让 Open MPI 运行时的系统限制文件描述符数量等沿用系统的ulimit配置避免进程因资源限制出问题。当集群中卡的数量较多时建议增加此配置。一个多机 Open MPI 的完整示例摘自 工具执行mpirun --prefix /usr/local/openmpi -hostfile hostfile \ -x ASCEND_HOME_PATH -x LD_LIBRARY_PATH \ -x HCCL_SOCKET_FAMILY -x HCCL_SOCKET_IFNAME -x HCCL_CONNECT_TIMEOUT -x HCCL_BUFFSIZE \ --allow-run-as-root --mca btl_tcp_if_include eth0 --mca opal_set_max_sys_limits 1 \ -n 16 ./bin/all_reduce_test -p 16 -b 8K -e 64M -i 0 -o sum -d fp32 -w 3 -n 3注意其中-x传递的环境变量HCCL_SOCKET_IFNAME、HCCL_BUFFSIZE等是 HCCL 通信域初始化的关键配置配置方法可参见 工具执行 第 2 步。四、HCCL Test 工具参数详解4.1 可执行文件选择要压测的集合通信算子./bin/executable_file必选集合通信性能测试工具的执行命令executable_file为支持的测试命令。HCCL Test 工具支持的测试命令包括broadcast_test、all_gather_test、all_gatherv_test、reduce_test、all_reduce_test、scatter_test、reduce_scatter_test、reduce_scatterv_test、alltoall_test、alltoallv_test、alltoallvc_test。各测试命令在不同产品上的支持情况以对应通信算子接口的实际支持能力为准。从源码结构看这些命令与 src/hccl_test/opbase_test/ 目录下的实现文件一一对应如 hccl_allreduce_rootinfo_test.cc、hccl_brocast_rootinfo_test.cc 等每个可执行文件对应一种算子的测试用例构建规则见 src/hccl_test/CMakeLists.txt。4.2 设备与根节点-p npus 或 --npus npus可选单个计算节点上参与训练的 NPU 个数。默认为当前节点的 NPU 总数若单个节点上参与的 NPU 个数小于节点 NPU 总数此参数为必填项。工具会按照该参数启动相应数量的 Device。源码中npus初始值为-1hccl_test_common.h当未显式配置-p时get_mpi_proc会将npus回退为本机aclrtGetDeviceCount返回的 Device 总数hccl_test_common.cc。此外Device 的映射规则为dev_id proc_rank % npus如果设置了环境变量HCCL_TEST_USE_DEVS如export HCCL_TEST_USE_DEVS4,5,6,7则改用指定的 Device ID 列表按轮询方式分配hccl_test_common.cc且-p取值会被校验必须落在[1, dev_count]区间内见 check_cmd_line。-r root 或 --root root可选执行broadcast_test、reduce_test、scatter_test时需要通过此参数指定根节点的 Device ID。取值范围[0, 实际Device数量-1]默认值为 0。源码中root_rank默认值为 0并在check_cmd_line中校验0 root_rank rank_size越界会直接报错退出hccl_test_common.cc。4.3 数据量与增量方式-b / -e / -i / -f这是决定每轮迭代测试数据大小的参数组四者联动-b minbytes 或 --minbytes minbytes可选测试数据大小的起始值最小值。默认值64M单位支持 K、M、G。-e maxbytes 或 --maxbytes maxbytes可选测试数据大小的结束值最大值。默认值64M单位支持 K、M、G。当-e等于-b时每次迭代按固定数据量测试当-e大于-b时需要设置数据增量类型-i与-f二选一配置即可。-i incsize 或 --stepbytes incsize可选数据增量类型为步长方式单位 Bytes。例如配置为 100则每次增量步长为 100 Bytes配置值仅为数字无需带单位。默认开启-i增量步长方式默认步长计算方式为(测试数据大小的结束值 - 测试数据大小的起始值) / 10当-i取值为 0 时按照-b定义的起始数据量持续测试。说明HCCL Test 工具执行时会对部分算子的-b、-e、-i所输入的数据量进行地址对齐或 rank size 倍数的微调以达到更优性能。-f incfactor 或 --stepfactor incfactor可选数据增量类型为乘法因子方式要求因子大于 1.0。配置示例原文档-b 100M -e 400M -i 0按照起始值 100MB 持续测试-b 100M -e 400M -i 500以 100MB 为起始值、每步增长 500 Bytes 的步长测试直至结束-b 100M -e 400M -f 2起始 100MB、结束 400MB、乘法因子 2则每次迭代分别取 100MB、200MB、400MB 的数据进行测试。源码佐证单位解析parsesize函数将K/k、M/m、G/g后缀分别按 1024 的幂展开hccl_test_common.cc这也解释了为什么文档中单位是 K/M/G 但内部全部换算成 Bytes。默认步长check_data_count中定义了defaultStepFactor 10用户未配置-i且-e -b时step_bytes (max_bytes - min_bytes) / 10若-e -b且未配置-i步长被强制置为 1 以防死循环hccl_test_common.cc。rank size 对齐当算子需要 ranksize 对齐时need_ranksize_alignment工具会把min_bytes、max_bytes对齐到rank_size * 512的倍数超过 16MB 的BUF_ALGIN_LINE阈值后并把步长向上取整对齐到rank_size的倍数hccl_test_common.cc。常量BUF_ALGIN_SIZE 512、BUF_ALGIN_LINE 16 * 1024 * 1024定义于 hccl_test_common.h。这正是文档所说“对数据量进行地址对齐或 rank size 倍数微调”的实现。冲突处理-f与-i同时配置时会告警并优先启用-f-f取值必须大于 1.0否则报错hccl_test_common.cc。4.4 归约操作与数据类型-o operator 或 --op operator可选Reduce 相关执行命令的操作类型包含sum、prod、max、min默认值为 sum。Reduce 相关的执行命令有all_reduce_test、reduce_scatter_test、reduce_scatterv_test、reduce_test。-d datatype 或 --datatype datatype可选HCCL Test 支持的数据类型默认值为 fp32。支持int8、uint8、int16、uint16、int32、uint32、int64、uint64、fp16、fp32、fp64、bfp16、fp8e5m2、fp8e4m3、fp8e8m0、hif8。各测试命令在不同产品上支持的数据类型以对应通信算子接口的实际支持能力为准。源码佐证HcclTest成员op_type初始化为HCCL_REDUCE_SUM、dtype初始化为HCCL_DATA_TYPE_FP32hccl_test_common.h与文档声明的默认值一致。-o经get_hccl_op_from_str映射为 HCCL 归约枚举-d经get_hccl_dtype_from_str映射为数据类型枚举两者若映射失败会在校验阶段报错并提示使用-h/--helphccl_test_common.cc。数据类型与卡数规模相关的数据校验上限例如乘/加操作在不同数据类型下的最大支持卡数可参见 工具执行 中的“结果说明”部分。4.5 零拷贝与对称内存-z 与 -m-z 0/1 或 --zero_copy 0/1可选是否开启零拷贝功能。单算子模式下输入输出 buffer 动态变化HCCL 会使用中间 buffer 中转完成集合通信引入额外的内存拷贝开销零拷贝功能直接对业务传入的内存进行操作从而降低拷贝开销、提升性能。0默认值不开启1开启。说明“零拷贝”为试用功能后续可能存在变更暂不支持应用于生产环境。零拷贝功能生效约束条件仅支持 Atlas A3 训练系列产品 / Atlas A3 推理系列产品仅支持执行reduce_scatter_test、all_gather_test、all_reduce_test、broadcast_test命令仅支持通信算法的编排展开位置在 AI CPU 的场景。-m 0/1 或 --symmetric_memory 0/1可选是否开启对称内存功能。作用与零拷贝类似——降低中间 buffer 拷贝开销、直接操作业务内存以提升性能。0默认值不开启1开启。对称内存功能生效约束条件仅支持 Ascend 950PR / Ascend 950DT、Atlas A3 训练系列产品 / Atlas A3 推理系列产品仅支持通信算子展开模式为 AI CPU 的场景展开模式由环境变量HCCL_OP_EXPANSION_MODE控制针对 Ascend 950PR / Ascend 950DT仅支持超节点内通信仅支持执行reduce_scatter_test、all_gather_test、all_reduce_test、alltoall_test、alltoallvc_test、broadcast_test仅支持 URMA 通信场景针对 Atlas A3 系列仅支持超节点内通信仅支持执行reduce_scatter_test、all_gather_test、all_reduce_test、alltoall_test仅支持超节点内 AI Server 间使用 HCCS 链路进行 SDMA 通信的场景不支持使用 RoCE 进行 RDMA 通信的场景即不支持设置HCCL_INTER_HCCS_DISABLE为 “TRUE”单机场景该环境变量无效仅支持对称组网每个 server 内卡数相同。注不支持零拷贝和对称内存功能同时开启。源码佐证参数解析时-z写入enable_zero_copy、-m写入enable_symmetric_memoryhccl_test_common.cc两个布尔成员定义于 hccl_test_common.h。check_cmd_line中显式校验二者互斥同时开启会直接报错退出Error: Zero-copy and symmetric memory cannot be enabled simultaneously.hccl_test_common.cc与文档的“注”完全对应。对称内存的物理内存注册路径可见register_symmetric_memory/deregister_symmetric_memory与symmetric_handle、symmetric_memory_size等成员hccl_test_common.h说明其实现依赖预注册的物理内存句柄。从源码的选项表构建逻辑看build_longoptshccl_test_common.cc910_95 平台分支没有zero_copy与nslb短选项而是提供accelerator-a选项其他平台则有-z、-s而无-a。这与文档中按产品分节描述-z/-m/-a适用平台的口径一致。4.6 加速模式-a仅 Ascend 950PR / Ascend 950DT-a HcclAccelerator 或 --accelerator HcclAccelerator可选该参数仅支持 Ascend 950PR / Ascend 950DT用于设置加速模式default使用默认自适应加速模式会根据组网、数据量等情况自动选择合适的模式aicpu_ts使用 Device 侧的 AI CPU 计算单元加速aiv使用 Device 侧的 Vector Core 计算单元加速大数据量情况下可能会回退到其他加速模式ccu_ms使用 CCU MSMemory Slice模式加速。Ascend 950PR 不支持此配置ccu_sched使用 CCU 调度模式加速host_ts不支持此配置aiv_only使用 Device 侧的 AI Core 计算单元加速相较于aiv加速模式不会发生回退情况。注该配置的优先级高于环境变量HCCL_OP_EXPANSION_MODE。源码佐证parse_cmd_line中存在一段默认值逻辑——在 910_95 平台且未设置HCCL_OP_EXPANSION_MODE环境变量时accelerator_config被默认置为 6代码注释标明即CCU_SCHED模式hccl_test_common.cc。此外-a的取值与-t仅 Device 侧计时存在组合约束当-t 1且加速模式为aicpu_ts时check_only_device_exec_time会直接报错hccl_test_common.cc对应 help 输出中 “not support aicpu_ts” 的提示。4.7 迭代、预热、仅 Device 侧计时与结果校验-s 0/1 或 --nslb 0/1可选是否启用 NSLB-DPNetwork Scale Load Balance - Data Plane数据面网络级负载均衡功能。0默认值不启用1启用。-n iters_count 或 --iters iters_count可选迭代次数默认值为 20。-w warmup_iters_count 或 --warmup_iters warmup_iters_count可选预热迭代次数。此参数不参与性能统计仅影响工具执行耗时默认值10。说明由于前几轮迭代可能存在影响性能测试的操作例如首轮迭代的 socket 建链操作等建议将前几轮迭代设置为预热迭代不进入性能统计。-t 或 --onlydevicetime可选将通信算子在 Host 侧的软件耗时与 kernel 加载耗时排除在通信执行耗时之外仅统计 Device 侧的执行时间即影响 HCCL Test 执行耗时的关键部分。0默认值不开启统计通信算子执行的全部耗时1开启仅统计 Device 侧执行耗时。开启该功能时需注意仅支持通信算法的编排展开位置为 Device 侧的 Vector Core 或 CCUHCCL_BUFFSIZE的配置值需要大于 100MB否则不生效-w与-n参数取值不能大于 100。-c 0/1 或 --check 0/1可选是否开启集合通信操作结果正确性校验。0不开启校验1默认值开启校验不输出详细错误信息2开启校验并输出详细错误信息。说明大规模集群场景下开启结果校验会使 HCCL Test 工具的执行耗时增加。源码佐证默认值成员变量一目了然iters 20、warmup_iters 10、check 1hccl_test_common.h与文档声明完全一致。check_cmd_line对迭代/预热/校验参数做了硬性约束-w、-n不能为负-c只能取 0/1/2-r必须落在[0, rank_size-1]hccl_test_common.cc。-t的约束由check_only_device_exec_time实现-t只允许 0/1开启时-w、-n不得超过 100否则报错hccl_test_common.cc。-t与HCCL_BUFFSIZE的联动是文档未展开、源码中可直接确认的细节当-t 1但环境变量HCCL_BUFFSIZE 100MB时工具会打印告警并自动把-t重置为 0hccl_test_common.cc——即文档所说“否则不生效”的具体行为。HCCL_BUFFSIZE未设置时内部默认值为 200MBhccl_test_common.cc。从set_env_resource可以看到工具在未显式设置HCCL_OP_RETRY_ENABLE时会自动注入L0:0, L1:0, L2:0关闭通信算子重执行以保证测试行为的可复现性hccl_test_common.cc。校验-c的结果会体现在工具输出的check_result列success / failed / NULL中各字段含义及归约类算子溢出导致无法校验的卡数上限表参见 工具执行 的“结果说明”。五、参数速查表参数长选项默认值说明-b--minbytes64M测试数据起始值单位 K/M/G-e--maxbytes64M测试数据结束值单位 K/M/G-i--stepbytes(e-b)/10增量步长Bytes0 表示按-b持续测试-f--stepfactor—增量乘法因子须大于 1.0与-i同配时优先生效-n--iters20参与统计的迭代次数-w--warmup_iters10预热迭代次数不参与性能统计-o--opsum归约操作sum / prod / max / min-d--datatypefp32数据类型共 16 种含 fp8 系列与 hif8-r--root0broadcast / reduce / scatter 的根节点 Device ID-p--npus本机 NPU 总数单节点参与训练的 NPU 个数-c--check1结果校验0 关闭 / 1 开启 / 2 开启并输出详细信息-z--zero_copy0零拷贝试用功能与-m互斥-m--symmetric_memory0对称内存与-z互斥-s--nslb0启用 NSLB-DP 数据面网络级负载均衡-t--onlydevicetime0仅统计 Device 侧执行耗时要求 HCCL_BUFFSIZE100MB-n/-w≤100-a--acceleratordefault加速模式仅 Ascend 950PR/950DT优先级高于 HCCL_OP_EXPANSION_MODE-h--help—打印帮助信息-a与-z/-s按平台互斥出现910_95 平台选项表包含accelerator其他平台包含zero_copy、nslb见 hccl_test_common.cc 中按IsSupport910_95()分支构造的getopt_long选项串。六、典型执行示例与输出解读单机 8 卡 AllReduce 压测MPICH 场景摘自 工具执行mpirun -n 8 ./bin/all_reduce_test -b 8K -e 64M -f 2 -d fp32 -o sum -p 8-b 8K -e 64M -f 2数据量从 8KB 起按因子 2 翻倍直至 64MB共 14 个数据点-p 8本节点 8 个 NPU 全部参与不指定-i时走默认步长逻辑但因指定了-f乘法因子优先生效。多机 2 节点 16 卡示例mpirun -f hostfile -n 16 ./bin/all_reduce_test -p 8 -b 8K -e 64M -f 2 -d fp32 -o sum工具按数据量逐行输出统计结果字段包括data_size单 NPU 参与通信的数据量Bytes、avg_time算子执行耗时us、alg_bandwidth算法带宽 通信数据量 / 耗时GB/s、check_result校验标识success / failed / NULL。check_result为 NULL 的两种情况-c 0未开启校验或算子结果溢出超出可精确表达范围导致无法校验。更多常见执行问题可参考 常见问题。七、参数行为在源码中的完整链路综合上述分析一个 HCCL Test 参数从命令行到生效的链路是解析parse_cmd_line用getopt_long按平台分支构造短/长选项串o:d:b:e:i:f:r:n:w:c:p:z:s:t:m:a:h的子集逐选项交给parse_opt写入HcclTest成员变量hccl_test_common.ccrank 与 Device 绑定get_mpi_proc将全局 MPI rank 映射为 HCCL rank并按proc_rank % npus或HCCL_TEST_USE_DEVS列表确定本进程使用的 Devicehccl_test_common.cc校验check_cmd_line串联check_data_count数据量与增量合法性、rank size 对齐、各枚举合法性、-p范围、-r范围、-c范围、-t组合约束、零拷贝/对称内存互斥等全部规则hccl_test_common.cc环境变量联动get_env_resource读取HCCL_TEST_PROFILING、HCCL_TEST_PROFILING_PATH、HCCL_BUFFSIZE并启动 profiling-t与HCCL_BUFFSIZE的不匹配在此被降级处理hccl_test_common.cc执行start_test按data_size逐个数据点执行warmup_iters轮预热 iters轮正式迭代-t 1时通过start_profile_device_time_if_needed/end_profile_device_time_if_needed仅统计 Device 侧耗时接口定义见 hccl_test_common.h。工具入口、参数校验、默认值、对齐策略均可以在 src/hccl_test/common/src/ 下对照阅读每个算子测试用例的行为差异体现在 src/hccl_test/opbase_test/ 中对应文件对init_send_recv_size_by_data、hccl_op_base_test等虚函数的实现。参考参数说明本文主线docs/zh/hccl_test/cmdline_options_desc.md工具执行环境变量、Hostfile、示例与输出解读docs/zh/hccl_test/execution.md规格约束docs/zh/hccl_test/restrictions.md工具介绍docs/zh/hccl_test/introduction.md安装与编译docs/zh/hccl_test/inst_and_compile.md核心实现hccl_test_main.cc、hccl_test_common.cc、hccl_test_common.h算子测试用例src/hccl_test/opbase_test/默认 Hostfile 模板src/hccl_test/hostfile【免费下载链接】oam-tools本项目为开发者提供故障定位工具包含故障信息收集软硬件信息展示AI core error报错分析等能力提升故障问题定位效率文档可在昇腾社区搜索“故障处理简介”选择社区版。项目地址: https://gitcode.com/cann/oam-tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考