Back to Details

hccl-test

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

HCCL Performance Test

HCCL性能测试

HCCL性能测试工具用于测试HCCL（Huawei Collective Communication Library）集合通信的功能正确性以及性能。
HCCL性能测试工具用于测试HCCL（Huawei Collective Communication Library）集合通信的功能正确性以及性能。

Overview

概述

  • 适用场景：分布式训练场景下的集合通信性能测试
  • 源码位置：
    ${INSTALL_DIR}/tools/hccl_test
  • 支持版本：CANN 8.3.RC1, CANN 8.5, CANN 25.RC
  • 适用场景：分布式训练场景下的集合通信性能测试
  • 源码位置：
    ${INSTALL_DIR}/tools/hccl_test
  • 支持版本：CANN 8.3.RC1, CANN 8.5, CANN 25.RC

支持的产品型号

支持的产品型号

产品系列最大 Rank 数备注
Atlas 训练系列产品4096-
Atlas A2 训练系列产品32K-
Atlas A3 训练系列产品/Atlas A3 推理系列产品32KAlltoAll/AlltoAllV 最大 8K
Atlas 300I Duo 推理卡--
产品系列最大 Rank 数备注
Atlas 训练系列产品4096-
Atlas A2 训练系列产品32K-
Atlas A3 训练系列产品/Atlas A3 推理系列产品32KAlltoAll/AlltoAllV 最大 8K
Atlas 300I Duo 推理卡--

核心算子（推荐测试）

核心算子（推荐测试）

分布式训练场景最常用：
算子可执行文件通信模式适用场景推荐度
AllReduce
all_reduce_test
多对多梯度聚合、参数同步⭐⭐⭐ 必测
AllGather
all_gather_test
多对多数据聚合、参数收集⭐⭐⭐ 必测
Broadcast
broadcast_test
一对多配置分发、初始化⭐⭐ 可选
AlltoAll
alltoall_test
多对多数据重排、负载均衡⭐⭐ 可选
提示: 完整算子列表见 references/parameters.md
分布式训练场景最常用：
算子可执行文件通信模式适用场景推荐度
AllReduce
all_reduce_test
多对多梯度聚合、参数同步⭐⭐⭐ 必测
AllGather
all_gather_test
多对多数据聚合、参数收集⭐⭐⭐ 必测
Broadcast
broadcast_test
一对多配置分发、初始化⭐⭐ 可选
AlltoAll
alltoall_test
多对多数据重排、负载均衡⭐⭐ 可选
提示：完整算子列表请参考 references/parameters.md

Quick Reference

快速参考

bash
undefined
bash
undefined

1. 前置检查（多机测试必需）

1. 前置检查（多机测试必需）

./scripts/pre-test-check.sh 175.99.1.2 175.99.1.3
./scripts/pre-test-check.sh 175.99.1.2 175.99.1.3

2. 编译工具

2. 编译工具

cd ${INSTALL_DIR}/tools/hccl_test make MPI_HOME=/usr/local/mpich ASCEND_DIR=${INSTALL_DIR}
cd ${INSTALL_DIR}/tools/hccl_test make MPI_HOME=/usr/local/mpich ASCEND_DIR=${INSTALL_DIR}

3. 快速连通性测试（单机）

3. 快速连通性测试（单机）

mpirun -n 8 ./bin/all_reduce_test -p 8 -b 8K -e 64M -f 2 -d fp32 -o sum
mpirun -n 8 ./bin/all_reduce_test -p 8 -b 8K -e 64M -f 2 -d fp32 -o sum

4. 完整性能测试（多机，推荐）

4. 完整性能测试（多机，推荐）

mpirun -f hostfile -n 16 ./bin/all_reduce_test -p 8 -b 8K -e 1G -f 2 -d fp32 -o sum

---
mpirun -f hostfile -n 16 ./bin/all_reduce_test -p 8 -b 8K -e 1G -f 2 -d fp32 -o sum

---

1. Pre-test Checklist（多机测试必需）

1. 测试前检查清单（多机测试必需）

⚠️ 重要: 多机测试前必须完成以下检查，否则可能出现建链超时或测试失败。
⚠️ 重要: 多机测试前必须完成以下检查，否则可能出现建链超时或测试失败。

1.1 SSH 免密登录配置

1.1 SSH 免密登录配置

所有节点间必须配置 SSH 免密登录：
bash
undefined
所有节点间必须配置 SSH 免密登录：
bash
undefined

1. 生成 SSH 密钥（如已存在可跳过）

1. 生成 SSH 密钥（如已存在可跳过）

ssh-keygen -t rsa
ssh-keygen -t rsa

2. 将公钥复制到所有节点（包括本机）

2. 将公钥复制到所有节点（包括本机）

ssh-copy-id -i ~/.ssh/id_rsa.pub root@<node1_ip> ssh-copy-id -i ~/.ssh/id_rsa.pub root@<node2_ip>
ssh-copy-id -i ~/.ssh/id_rsa.pub root@<node1_ip> ssh-copy-id -i ~/.ssh/id_rsa.pub root@<node2_ip>

3. 验证免密登录

3. 验证免密登录

ssh root@<node1_ip> "echo 'SSH OK'" ssh root@<node2_ip> "echo 'SSH OK'"
undefined
ssh root@<node1_ip> "echo 'SSH OK'" ssh root@<node2_ip> "echo 'SSH OK'"
undefined

1.2 CANN 版本一致性检查

1.2 CANN 版本一致性检查

多机 CANN 版本必须一致，否则会导致测试失败：
bash
undefined
多机 CANN 版本必须一致，否则会导致测试失败：
bash
undefined

检查所有节点的 CANN 版本

检查所有节点的 CANN 版本

for node in 175.99.1.2 175.99.1.3; do echo "=== $node ===" ssh root@$node "cat /usr/local/Ascend/ascend-toolkit/latest/version.cfg | grep runtime_running_version" done

> **注意**: 版本不一致时需统一版本（建议统一为最新 RC 版本）。
for node in 175.99.1.2 175.99.1.3; do echo "=== $node ===" ssh root@$node "cat /usr/local/Ascend/ascend-toolkit/latest/version.cfg | grep runtime_running_version" done

> **注意**: 版本不一致时需统一版本（建议统一为最新 RC 版本）。

1.3 NPU 健康状态检查

1.3 NPU 健康状态检查

测试前需确认所有 NPU 状态正常：
bash
undefined
测试前需确认所有 NPU 状态正常：
bash
undefined

检查所有节点的 NPU 健康状态

检查所有节点的 NPU 健康状态

for node in 175.99.1.2 175.99.1.3; do echo "=== $node NPU Health ===" ssh root@$node "npu-smi info -t health -i 0" done

**NPU 状态说明**：
| 状态 | 说明 | 操作建议 |
|-----|------|---------|
| OK | 正常 | ✅ 可以使用 |
| Alarm | 告警 | ⚠️ 需排查故障 |
| Offline | 离线 | ❌ 不可使用 |

> 如存在 Alarm 状态，需排除故障卡。例如 NPU 0 故障，使用 7 张卡测试。
for node in 175.99.1.2 175.99.1.3; do echo "=== $node NPU 健康状态 ===" ssh root@$node "npu-smi info -t health -i 0" done

**NPU 状态说明**：
| 状态 | 说明 | 操作建议 |
|-----|------|---------|
| OK | 正常 | ✅ 可以使用 |
| Alarm | 告警 | ⚠️ 需排查故障 |
| Offline | 离线 | ❌ 不可使用 |

> 如存在 Alarm 状态，需排除故障卡。例如 NPU 0 故障，使用 7 张卡测试。

1.4 一键前置检查脚本

1.4 一键前置检查脚本

bash
undefined
bash
undefined

使用提供的检查脚本（推荐）

使用提供的检查脚本（推荐）

./scripts/pre-test-check.sh 175.99.1.2 175.99.1.3

---
./scripts/pre-test-check.sh 175.99.1.2 175.99.1.3

---

2. MPI Installation

2. MPI安装

HCCL性能测试工具依赖MPI拉起多个进程，默认使用 MPICH。
HCCL性能测试工具依赖MPI拉起多个进程，默认使用 MPICH。

2.1 MPICH Installation (Recommended)

2.1 MPICH安装（推荐）

下载地址：https://www.mpich.org/static/downloads/
产品系列推荐版本
Atlas A3 训练系列产品/Atlas A3 推理系列产品MPICH 4.1.3
Atlas A2 训练系列产品MPICH 3.2.1
Atlas 训练系列产品MPICH 3.2.1
Atlas 300I Duo 推理卡MPICH 3.2.1
安装步骤：
bash
undefined
下载地址：https://www.mpich.org/static/downloads/
产品系列推荐版本
Atlas A3 训练系列产品/Atlas A3 推理系列产品MPICH 4.1.3
Atlas A2 训练系列产品MPICH 3.2.1
Atlas 训练系列产品MPICH 3.2.1
Atlas 300I Duo 推理卡MPICH 3.2.1
安装步骤：
bash
undefined

1. 解压

1. 解压

tar -zxvf mpich-${version}.tar.gz cd mpich-${version}
tar -zxvf mpich-${version}.tar.gz cd mpich-${version}

2. 配置编译选项

2. 配置编译选项

Atlas A3 产品（必须使用 TCP 协议）

Atlas A3 产品（必须使用 TCP 协议）

./configure --disable-fortran --prefix=/usr/local/mpich --with-device=ch3:nemesis
./configure --disable-fortran --prefix=/usr/local/mpich --with-device=ch3:nemesis

其他产品

其他产品

./configure --disable-fortran --prefix=/usr/local/mpich
./configure --disable-fortran --prefix=/usr/local/mpich

3. 编译安装

3. 编译安装

make -j 32 && make install
undefined
make -j 32 && make install
undefined

2.2 Open MPI Installation (Alternative)

2.2 Open MPI安装（备选）

适用于需要 IPv6 支持的场景。
bash
tar -zxvf openmpi-4.1.5.tar.gz
cd openmpi-4.1.5
./configure --disable-fortran --enable-ipv6 --prefix=/usr/local/openmpi
make -j 32 && make install
适用于需要 IPv6 支持的场景。
bash
tar -zxvf openmpi-4.1.5.tar.gz
cd openmpi-4.1.5
./configure --disable-fortran --enable-ipv6 --prefix=/usr/local/openmpi
make -j 32 && make install

2.3 环境配置

2.3 环境配置

bash
undefined
bash
undefined

MPICH 环境

MPICH 环境

export INSTALL_DIR=/usr/local/Ascend/ascend-toolkit/latest export PATH=/usr/local/mpich/bin:$PATH export LD_LIBRARY_PATH=/usr/local/mpich/lib:${INSTALL_DIR}/lib64:$LD_LIBRARY_PATH

---
export INSTALL_DIR=/usr/local/Ascend/ascend-toolkit/latest export PATH=/usr/local/mpich/bin:$PATH export LD_LIBRARY_PATH=/usr/local/mpich/lib:${INSTALL_DIR}/lib64:$LD_LIBRARY_PATH

---

3. Tool Compilation

3. 工具编译

bash
cd ${INSTALL_DIR}/tools/hccl_test
bash
cd ${INSTALL_DIR}/tools/hccl_test

MPICH

MPICH

make MPI_HOME=/usr/local/mpich ASCEND_DIR=${INSTALL_DIR}
make MPI_HOME=/usr/local/mpich ASCEND_DIR=${INSTALL_DIR}

Open MPI

Open MPI

make MPI_HOME=/usr/local/openmpi ASCEND_DIR=${INSTALL_DIR}

编译成功后，在 `bin` 目录下生成 10 个可执行文件。

---
make MPI_HOME=/usr/local/openmpi ASCEND_DIR=${INSTALL_DIR}

编译成功后，在 `bin` 目录下生成 10 个可执行文件。

---

4. Testing Scenarios

4. 测试场景

4.1 快速连通性测试

4.1 快速连通性测试

用于验证 HCCL 基本连通性，数据量较小，执行速度快：
bash
undefined
用于验证 HCCL 基本连通性，数据量较小，执行速度快：
bash
undefined

单机快速测试

单机快速测试

mpirun -n 8 ./bin/all_reduce_test -p 8 -b 8K -e 64M -f 2 -d fp32 -o sum
mpirun -n 8 ./bin/all_reduce_test -p 8 -b 8K -e 64M -f 2 -d fp32 -o sum

多机快速测试

多机快速测试

mpirun -f hostfile -n 16 ./bin/all_reduce_test -p 8 -b 8K -e 64M -f 2 -d fp32 -o sum
undefined
mpirun -f hostfile -n 16 ./bin/all_reduce_test -p 8 -b 8K -e 64M -f 2 -d fp32 -o sum
undefined

4.2 完整性能测试（推荐）

4.2 完整性能测试（推荐）

用于测试大带宽网络性能，数据量到 1GB，更能反映实际训练场景：
bash
undefined
用于测试大带宽网络性能，数据量到 1GB，更能反映实际训练场景：
bash
undefined

单机完整性能测试

单机完整性能测试

mpirun -n 8 ./bin/all_reduce_test -p 8 -b 8K -e 1G -f 2 -d fp32 -o sum
mpirun -n 8 ./bin/all_reduce_test -p 8 -b 8K -e 1G -f 2 -d fp32 -o sum

多机完整性能测试（推荐）

多机完整性能测试（推荐）

mpirun -f hostfile -n 16 ./bin/all_reduce_test -p 8 -b 8K -e 1G -f 2 -d fp32 -o sum

**参数说明**：
- `-b 8K`: 起始数据量 8KB
- `-e 1G`: 结束数据量 1GB（64M 只能测试小数据量）
- `-f 2`: 乘法因子，测试 8K, 16K, 32K, 64K, 128K, 256K, 512K, 1M, 2M, 4M, 8M, 16M, 32M, 64M, 128M, 256M, 512M, 1G
mpirun -f hostfile -n 16 ./bin/all_reduce_test -p 8 -b 8K -e 1G -f 2 -d fp32 -o sum

**参数说明**：
- `-b 8K`: 起始数据量 8KB
- `-e 1G`: 结束数据量 1GB（64M 只能测试小数据量）
- `-f 2`: 乘法因子，测试 8K, 16K, 32K, 64K, 128K, 256K, 512K, 1M, 2M, 4M, 8M, 16M, 32M, 64M, 128M, 256M, 512M, 1G

4.3 核心算子测试

4.3 核心算子测试

bash
undefined
bash
undefined

使用 quick-verify.sh 测试核心算子（推荐）

使用 quick-verify.sh 测试核心算子（推荐）

./scripts/quick-verify.sh 8
./scripts/quick-verify.sh 8

手动测试核心算子

手动测试核心算子

./bin/all_reduce_test -p 8 -b 8K -e 1G -f 2 -d fp32 -o sum ./bin/all_gather_test -p 8 -b 8K -e 1G -f 2 -d fp32
undefined
./bin/all_reduce_test -p 8 -b 8K -e 1G -f 2 -d fp32 -o sum ./bin/all_gather_test -p 8 -b 8K -e 1G -f 2 -d fp32
undefined

4.4 Hostfile 配置

4.4 Hostfile配置

MPICH Format (
节点IP:卡数
)：
bash
undefined
MPICH格式 (
节点IP:卡数
)：
bash
undefined

单机测试

单机测试

175.99.1.3:8
175.99.1.3:8

双机测试

双机测试

175.99.1.3:8 175.99.1.4:8

> 请将属于同一超节点的 AI Server 信息配置在一起，不支持交叉配置。

---
175.99.1.3:8 175.99.1.4:8

> 请将属于同一超节点的 AI Server 信息配置在一起，不支持交叉配置。

---

5. Parameters

5. 参数说明

5.1 核心参数速查

5.1 核心参数速查

参数说明示例
-p <npus>
单节点参与训练的 NPU 个数
-p 8
-b <size>
测试数据量起始值
-b 8K
-e <size>
测试数据量结束值
-e 1G
-f <factor>
乘法因子
-f 2
-d <type>
数据类型: fp32/fp16/int32
-d fp32
-o <op>
操作类型: sum/prod/max/min
-o sum
-n <iters>
迭代次数（默认 20）
-n 20
-c <0/1>
是否开启结果校验（默认 1）
-c 1
详细参数说明见 references/parameters.md
参数说明示例
-p <npus>
单节点参与训练的 NPU 个数
-p 8
-b <size>
测试数据量起始值
-b 8K
-e <size>
测试数据量结束值
-e 1G
-f <factor>
乘法因子
-f 2
-d <type>
数据类型: fp32/fp16/int32
-d fp32
-o <op>
操作类型: sum/prod/max/min
-o sum
-n <iters>
迭代次数（默认 20）
-n 20
-c <0/1>
是否开启结果校验（默认 1）
-c 1
详细参数说明见 references/parameters.md

5.2 数据量配置示例

5.2 数据量配置示例

bash
undefined
bash
undefined

固定数据量测试

固定数据量测试

-b 100M -e 100M
-b 100M -e 100M

乘法因子测试（测试 100M, 200M, 400M）

乘法因子测试（测试 100M, 200M, 400M）

-b 100M -e 400M -f 2
-b 100M -e 400M -f 2

完整性能测试（推荐）

完整性能测试（推荐）

-b 8K -e 1G -f 2

---
-b 8K -e 1G -f 2

---

6. Results

6. 测试结果

6.1 输出格式

6.1 输出格式

data_size      avg_time(us)    alg_bandwidth(GB/s)    check_result
8192           125.3           0.065                  success
16384          132.1           0.124                  success
...
字段说明
data_size
单个 NPU 上参与集合通信的数据量（Bytes）
avg_time
集合通信算子执行耗时（us）
alg_bandwidth
算法带宽（GB/s），计算方式：集合通信数据量/耗时
check_result
结果校验标识：success/failed/NULL
data_size      avg_time(us)    alg_bandwidth(GB/s)    check_result
8192           125.3           0.065                  success
16384          132.1           0.124                  success
...
字段说明
data_size
单个 NPU 上参与集合通信的数据量（Bytes）
avg_time
集合通信算子执行耗时（us）
alg_bandwidth
算法带宽（GB/s），计算方式：集合通信数据量/耗时
check_result
结果校验标识：success/failed/NULL

6.2 结果解析

6.2 结果解析

bash
undefined
bash
undefined

解析结果文件

解析结果文件

./scripts/parse-hccl-result.py output.log
./scripts/parse-hccl-result.py output.log

输出 Markdown 表格

输出 Markdown 表格

./scripts/parse-hccl-result.py output.log -f markdown

---
./scripts/parse-hccl-result.py output.log -f markdown

---

7. Actual Test Results

7. 实际测试结果

7.1 双机 16×910B3 测试数据

7.1 双机 16×910B3 测试数据

我们在双机 16×910B3 环境测试了全部 10 种算子：
算子结果备注
AllReduce✅ PASS最高带宽 48.59 GB/s (32MB)
AllGather✅ PASS-
AllGatherV❌ FAILretcode: 5（变长参数问题）
AlltoAll✅ PASS-
AlltoAllV✅ PASS-
Broadcast✅ PASS-
Reduce✅ PASS-
ReduceScatter✅ PASS-
ReduceScatterV❌ FAILretcode: 5（变长参数问题）
Scatter✅ PASS-
通过率：8/10 (80%)，核心算子全部通过。
我们在双机 16×910B3 环境测试了全部 10 种算子：
算子结果备注
AllReduce✅ PASS最高带宽 48.59 GB/s (32MB)
AllGather✅ PASS-
AllGatherV❌ FAILretcode: 5（变长参数问题）
AlltoAll✅ PASS-
AlltoAllV✅ PASS-
Broadcast✅ PASS-
Reduce✅ PASS-
ReduceScatter✅ PASS-
ReduceScatterV❌ FAILretcode: 5（变长参数问题）
Scatter✅ PASS-
通过率：8/10 (80%)，核心算子全部通过。

7.2 测试环境参考

7.2 测试环境参考

  • 测试节点：175.100.2.3, 175.100.2.4
  • NPU：910B3 × 8 每节点（共 16 卡）
  • CANN：25.3.rc1
  • 通信网卡：enp189s0f0
  • MPI：MPICH 3.2.1
  • 测试节点：175.100.2.3, 175.100.2.4
  • NPU：910B3 × 8 每节点（共 16 卡）
  • CANN：25.3.rc1
  • 通信网卡：enp189s0f0
  • MPI：MPICH 3.2.1

8. Common Issues

8. 常见问题

8.1 前置条件问题

8.1 前置条件问题

问题原因解决方法
SSH 免密登录失败未配置 SSH 密钥执行 ssh-copy-id 配置免密登录
CANN 版本不一致多机 CANN 版本不同统一所有节点的 CANN 版本
NPU Alarm 状态NPU 硬件故障检查 npu-smi info -t health，排除故障卡
问题原因解决方法
SSH 免密登录失败未配置 SSH 密钥执行 ssh-copy-id 配置免密登录
CANN 版本不一致多机 CANN 版本不同统一所有节点的 CANN 版本
NPU Alarm 状态NPU 硬件故障检查 npu-smi info -t health，排除故障卡

8.2 运行时问题

8.2 运行时问题

问题原因解决方法
gethostbyname failed主机名无法解析配置 /etc/hosts
retcode: 7残余进程干扰执行清理命令：
mpirun -f hostfile -n 16 pkill -9 -f "all_reduce_test"
retcode: 5变长参数配置错误AllGatherV/ReduceScatterV 需要特殊参数配置
问题原因解决方法
gethostbyname failed主机名无法解析配置 /etc/hosts
retcode: 7残余进程干扰执行清理命令：
mpirun -f hostfile -n 16 pkill -9 -f "all_reduce_test"
retcode: 5变长参数配置错误AllGatherV/ReduceScatterV 需要特殊参数配置

8.3 其他注意事项

8.3 其他注意事项

  1. Docker 容器：如果使用 Docker 容器进行测试，需要使用 host 网络模式
  2. 日志查看：测试失败时可查看 
    ~/ascend/log/debug/plog
    中的最新日志
  3. 进程清理：测试前检查卡上是否有其他进程占用，如有需要手动清理
详细故障排除见 references/common-issues.md
  1. Docker 容器：如果使用 Docker 容器进行测试，需要使用 host 网络模式
  2. 日志查看：测试失败时可查看 
    ~/ascend/log/debug/plog
    中的最新日志
  3. 进程清理：测试前检查卡上是否有其他进程占用，如有需要手动清理
详细故障排除见 references/common-issues.md

9. Scripts

9. 脚本工具

9.1 前置检查脚本

9.1 前置检查脚本

bash
undefined
bash
undefined

多机测试前置检查

多机测试前置检查

./scripts/pre-test-check.sh 175.99.1.2 175.99.1.3

检查内容：
- SSH 免密登录
- CANN 版本一致性
- NPU 健康状态
- 网络连通性
./scripts/pre-test-check.sh 175.99.1.2 175.99.1.3

检查内容：
- SSH 免密登录
- CANN 版本一致性
- NPU 健康状态
- 网络连通性

9.2 快速验证脚本

9.2 快速验证脚本

bash
undefined
bash
undefined

测试核心算子

测试核心算子

./scripts/quick-verify.sh 8
./scripts/quick-verify.sh 8

完整性能测试

完整性能测试

./scripts/quick-verify.sh 8 full
undefined
./scripts/quick-verify.sh 8 full
undefined

9.3 多机测试脚本

9.3 多机测试脚本

bash
undefined
bash
undefined

一键多机测试（自动前置检查 + 测试）

一键多机测试（自动前置检查 + 测试）

./scripts/multi-node-test.sh --nodes 175.99.1.2,175.99.1.3 --npus 8 --mode full

---
./scripts/multi-node-test.sh --nodes 175.99.1.2,175.99.1.3 --npus 8 --mode full

---

Official References

10. 官方参考文档