hccl-test

HCCL パフォーマンステスト

HCCL パフォーマンステストツールは、HCCL（Huawei Collective Communication Library）の集合通信機能の正確性と性能をテストするためのツールです。

概要

• 適用シナリオ：分散トレーニング環境における集合通信のパフォーマンステスト
• ソースコードの場所：${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 推論シリーズ製品	32K	AlltoAll/AlltoAllV は最大 8K
Atlas 300I Duo 推論カード	-	-

コア演算子（テスト推奨）

分散トレーニング環境で最もよく使用されます。

演算子	実行ファイル	通信モード	適用シナリオ	推奨度
AllReduce	all_reduce_test	多対多	勾配の集約、パラメーター同期	⭐⭐⭐ 必須
AllGather	all_gather_test	多対多	データ集約、パラメーター収集	⭐⭐⭐ 必須
Broadcast	broadcast_test	一対多	設定の配布、初期化	⭐⭐ 任意
AlltoAll	alltoall_test	多対多	データの再配置、負荷分散	⭐⭐ 任意

ヒント：演算子の全一覧は references/parameters.md を参照してください。

---

クイックリファレンス

# 1. 前置检查（多机测试必需）
./scripts/pre-test-check.sh 175.99.1.2 175.99.1.3

# 2. 编译工具
cd ${INSTALL_DIR}/tools/hccl_test
make MPI_HOME=/usr/local/mpich ASCEND_DIR=${INSTALL_DIR}

# 3. 快速连通性测试（单机）
mpirun -n 8 ./bin/all_reduce_test -p 8 -b 8K -e 64M -f 2 -d fp32 -o sum

# 4. 完整性能测试（多机，推荐）
mpirun -f hostfile -n 16 ./bin/all_reduce_test -p 8 -b 8K -e 1G -f 2 -d fp32 -o sum

---

1. テスト前チェックリスト（マルチノードテストで必須）

⚠️ 重要：マルチノードテストの前に、以下のチェックを必ず完了してください。完了しない場合、接続確立のタイムアウトやテスト失敗が発生する可能性があります。

1.1 SSH パスワードなしログインの設定

すべてのノード間で SSH パスワードなしログインを設定する必要があります。

# 1. 生成 SSH 密钥（如已存在可跳过）
ssh-keygen -t rsa

# 2. 将公钥复制到所有节点（包括本机）
ssh-copy-id -i ~/.ssh/id_rsa.pub root@<node1_ip>
ssh-copy-id -i ~/.ssh/id_rsa.pub root@<node2_ip>

# 3. 验证免密登录
ssh root@<node1_ip> "echo 'SSH OK'"
ssh root@<node2_ip> "echo 'SSH OK'"

1.2 CANN バージョンの一致確認

マルチノード環境では 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 バージョンへの統一を推奨します）。

1.3 NPU の正常性確認

テスト前に、すべての 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 枚のカードを使用してテストします。

1.4 事前チェックを一括で実行するスクリプト

# 使用提供的检查脚本（推荐）
./scripts/pre-test-check.sh 175.99.1.2 175.99.1.3

---

2. MPI のインストール

HCCL パフォーマンステストツールは、複数のプロセスを起動するために MPI に依存しています。デフォルトでは MPICH を使用します。

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

インストール手順：

# 1. 解压
tar -zxvf mpich-${version}.tar.gz
cd mpich-${version}

# 2. 配置编译选项
# Atlas A3 产品（必须使用 TCP 协议）
./configure --disable-fortran --prefix=/usr/local/mpich --with-device=ch3:nemesis

# 其他产品
./configure --disable-fortran --prefix=/usr/local/mpich

# 3. 编译安装
make -j 32 && make install

2.2 Open MPI のインストール（代替）

IPv6 のサポートが必要なシナリオに適しています。

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 環境設定

# 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

---

3. ツールのコンパイル

cd ${INSTALL_DIR}/tools/hccl_test

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

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

コンパイルが成功すると、bin ディレクトリに 10 個の実行ファイルが生成されます。

---

4. テストシナリオ

4.1 クイック接続テスト

HCCL の基本的な接続を確認します。データ量が小さいため、すばやく実行できます。

# 单机快速测试
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

4.2 完全なパフォーマンステスト（推奨）

大帯域幅ネットワークの性能をテストします。データ量は最大 1GB で、実際のトレーニングシナリオをよりよく反映できます。

# 单机完整性能测试
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 をテストします。

4.3 コア演算子のテスト

# 使用 quick-verify.sh 测试核心算子（推荐）
./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

4.4 Hostfile の設定

MPICH 形式（ノードIP:カード数）：

# 单机测试
175.99.1.3:8

# 双机测试
175.99.1.3:8
175.99.1.4:8

同一のスーパーノードに属する AI Server の情報をまとめて設定してください。混在する設定には対応していません。

---

5. パラメーター

5.1 コアパラメーター早見表

パラメーター	説明	例
-p <npus>	1 ノードでトレーニングに参加する 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 データ量の設定例

# 固定数据量测试
-b 100M -e 100M

# 乘法因子测试（测试 100M, 200M, 400M）
-b 100M -e 400M -f 2

# 完整性能测试（推荐）
-b 8K -e 1G -f 2

---

6. 結果

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 1 台あたりのデータ量（Bytes）
avg_time	集合通信演算子の実行時間（us）
alg_bandwidth	アルゴリズム帯域幅（GB/s）。計算方法：集合通信データ量/実行時間
check_result	結果検証のステータス：success/failed/NULL

6.2 結果の解析

# 解析结果文件
./scripts/parse-hccl-result.py output.log

# 输出 Markdown 表格
./scripts/parse-hccl-result.py output.log -f markdown

---

7. 実際のテスト結果

7.1 2 ノード、16×910B3 のテストデータ

2 ノード、16×910B3 の環境で、10 種類の演算子すべてをテストしました。

演算子	結果	備考
AllReduce	✅ PASS	最大帯域幅 48.59 GB/s（32MB）
AllGather	✅ PASS	-
AllGatherV	❌ FAIL	retcode: 5（可変長パラメーターの問題）
AlltoAll	✅ PASS	-
AlltoAllV	✅ PASS	-
Broadcast	✅ PASS	-
Reduce	✅ PASS	-
ReduceScatter	✅ PASS	-
ReduceScatterV	❌ FAIL	retcode: 5（可変長パラメーターの問題）
Scatter	✅ PASS	-

合格率：8/10（80%）。コア演算子はすべて合格しました。

7.2 テスト環境の参考情報

• テストノード：175.100.2.3, 175.100.2.4
• NPU：各ノードに 910B3 × 8（合計 16 カード）
• CANN：25.3.rc1
• 通信ネットワークカード：enp189s0f0
• MPI：MPICH 3.2.1

---

8. よくある問題

8.1 前置条件问题

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

8.2 运行时问题

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

8.3 其他注意事项

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

详细故障排除见 references/common-issues.md

---

9. Scripts

9.1 前置检查脚本

# 多机测试前置检查
./scripts/pre-test-check.sh 175.99.1.2 175.99.1.3

检查内容：

• SSH 免密登录
• CANN 版本一致性
• NPU 健康状态
• 网络连通性

9.2 快速验证脚本

# 测试核心算子
./scripts/quick-verify.sh 8

# 完整性能测试
./scripts/quick-verify.sh 8 full

9.3 多机测试脚本

# 一键多机测试（自动前置检查 + 测试）
./scripts/multi-node-test.sh --nodes 175.99.1.2,175.99.1.3 --npus 8 --mode full

---

Official References

• CANN 8.3.RC1: https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/83RC1/devaids/hccltool/HCCLpertest_16_0001.html
• CANN 8.5: https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/850/devaids/hccltool/HCCLpertest_16_0001.html
• HCCL 常见问题: https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/83RC1/devaids/hccltool/HCCLpertest_16_0008.html