hccl-test

Files (12)

• SKILL.md
• common-issues.md · references/
• docker-notes.md · references/
• parameters.md · references/
• pre-test-checklist.md · references/
• testing-scenarios.md · references/
• hostfile-template.txt · scripts/
• multi-node-test.sh · scripts/
• parse-hccl-result.py · scripts/
• pre-test-check.sh · scripts/
• quick-verify.sh · scripts/
• setup-hccl-env.sh · scripts/

SKILL.md (first lines)

# HCCL Performance Test

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

## Overview

- **适用场景**：分布式训练场景下的集合通信性能测试
- **源码位置**：`${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](references/parameters.md)

---

## Quick Reference

```bash
# 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. Pre-test Checklist（多机测试必需）

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

### 1.1 SSH 免密登录配置

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

```bash
# 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 版本必须一致，否则会导致测试失败：

```bash
# 检查所有节点的 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 状态正常：

```bash
# 检查所有节点的 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 一键前置检查脚本

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

---

## 2. MPI Installation

From Ascend/agent-skills, MulanPSL-2.0.

More from Ascend/agent-skills