前提条件

使用mpirun工具前，请确保已配置MPI工具相关环境变量，如下所示：
```
export INSTALL_DIR=/usr/local/Ascend/ascend-toolkit/latest
export PATH=/usr/local/mpich-3.2.1/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/mpich-3.2.1/lib:${INSTALL_DIR}/lib64:$LD_LIBRARY_PATH
```
- “INSTALL_DIR”是CANN软件安装后文件存储路径，其中“/usr/local/Ascend”为root用户的默认安装路径，如果使用普通用户安装，或指定路径安装，请自行替换。
- “/usr/local/mpich-3.2.1/lib”为安装后MPI的库文件所在路径，请根据实际情况替换。
运行环境已关闭防火墙。
由于Master节点允许处理的并发建链数受linux内核参数“somaxconn”与“tcp_max_syn_backlog”的限制，所以，针对大规模集群组网，若“somaxconn”与“tcp_max_syn_backlog”取值较小会导致部分客户端概率性提前异常退出，导致集群初始化失败。
大规模集群组网场景下，建议开发者根据集群数量在master节点适当调整“somaxconn”与“tcp_max_syn_backlog”参数的值，例如：
```
sysctl -w net.core.somaxconn=65535 
sysctl -w net.ipv4.tcp_max_syn_backlog=65535
```

命令格式

mpirun -f hostfile -n number ./bin/<executable_file> [-p npus] [-b minbytes] [-e maxbytes] [-f stepfactor] [-o operator] [-r root] [-d datatype] [-n iters] [-w warmup_iters] [-c <0/1>]

例如：

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

若执行mpirun命令时，出现“gethostbyname failed”的错误，请参见gethostbyname failed处理。

参数说明

表1 HCCL性能测试工具参数说明
参数名	可选/必选	描述
mpirun命令参数
-f	可选	Hostfile节点列表文件。单机场景下无需配置此文件；多机场景下，需要配置此文件。文件示例如下：方式一：“节点IP:每节点进程数”，该配置方式仅支持IPv4协议进行通信的场景。 # 训练节点ip:每节点的进程数 10.78.130.22:8 10.78.130.21:8 方式二：“节点名:每节点进程数”，该配置方式支持使用IPv4协议或者IPv6协议进行通信的场景。 # 训练节点名：每节点的进程数 node3:8 node4:8
-n	必选	需要启动的NPU总数。
./bin/<executable_file>	必选	集合通信性能测试工具的执行命令。其中<executable_file>为集合通信性能测试工具的可执行文件。当前可指定文件有：all_gather_test，all_reduce_test，alltoallv_test，alltoall_test，broadcast_test，reduce_scatter_test，reduce_test，scatter_test。例如./bin/all_gather_test。
集合通信性能测试命令支持的参数
-p	必选	单个计算节点上参与训练的NPU个数。默认为当前节点的NPU总数。说明：集合通信测试工具会按照用户配置的参与训练的NPU个数拉起相应的Device，Device的约束可参见规格约束
-b	可选	定义执行集合通信操作所使用的测试数据大小。 -b：测试数据大小的起始值，即最小值。默认值：64M，单位：K、M、G。 -e：测试数据大小的结束值，即最大值。默认值：64M，单位：K、M、G。 -i/-f：数据增量类型，其中“-i”为增量步长方式，"-f"为乘法因子方式。默认开启“-i”增量步长方式，默认步长大小的计算方式为：（测试数据大小的结束值-测试数据大小的起始值）/10。说明：当“-b”取值等于“-e”时，即每次迭代按照固定的数据量大小进行测试。当“-e”的取值大于“-b”时，需要设置数据增量类型，“-i”与“-f”二选一进行配置即可。当“-i”取值为0时，会按照测试数据大小起始值（即“-b”定义的数据量大小）持续测试。例如：假设配置示例为：-b 100M -e 400M -f 2 即测试数据大小起始值为100M，结束值为400M，数据增量乘法因子为2，则每次迭代都会分别取大小为“100M”、“200M”、“400M”的数据进行测试。
-e	可选
-i	可选
-f	可选
HCCL操作参数
-o	可选	Reduce相关执行命令的操作类型，包含：sum、prod、max、min，默认值为sum。 Reduce相关的执行命令有：all_reduce_test、reduce_scatter_test、reduce_test。
-r	可选	执行命令为broadcast_test、reduce_test、scatter_test时，需要通过此参数指定根节点的Device ID。取值范围：[0，实际Device数量-1]。默认值为：0。
-d	可选	HCCL执行命令支持的数据类型，默认值为fp32。针对执行命令all_reduce_test、reduce_scatter_test、reduce_test： Atlas 训练系列产品，支持数据类型int8、int32、int64、fp16、fp32。 Atlas 300I Duo 推理卡，支持的数据类型int8、int16、int32、fp16、fp32，其中“prod”、“max”、“min”操作不支持int16数据类型。 Atlas A2 训练系列产品，支持数据类型int8、int16、int32、int64、fp16、fp32、bfp16，其中“prod”操作不支持int16、bfp16数据类型。针对执行命令broadcast_test、all_gather_test、alltoallv_test、alltoall_test、scatter_test，支持的数据类型包括：int8、int16、int32、fp16、fp32、int64、uint64、uint8、uint16、uint32、fp64、bfp16。其中bfp16数据类型仅Atlas A2 训练系列产品支持。
性能测试参数
-n	可选	迭代次数，默认值为20。
-w	可选	预热迭代次数，此参数不参与性能统计，仅影响HCCL Test工具的执行耗时，默认值：5。说明：由于前几轮迭代可能存在影响性能测试的操作（例如，首轮迭代的socket建链操作等），建议将前几轮迭代设置为预热迭代，不进入性能统计。
结果校验参数
-c	可选	是否开启集合通信操作结果正确性校验。 0：不开启校验， 1：开启校验。默认值：1。说明：大规模集群场景下，开启结果校验会使HCCL Test工具的执行耗时增加。

执行示例

单机场景
 以1个计算节点，8个NPU设备，测试AllReduce算子的性能为例：
1. 配置HCCL的初始化root通信网卡使用的IP协议版本。
```
export HCCL_SOCKET_FAMILY=AF_INET
```
  取值为“AF_INET”，代表使用IPv4协议；取值为“AF_INET6”，代表使用IPv6协议。
2. 调整socket建链超时等待时间。
  集合通信场景中，设备间socket建链超时等待时间默认值为120s，当Master节点需要建链和处理的数据量较大时，默认值120秒无法满足建链需求，需要适当进行调整。
  
  例如，若集群组网中卡数为3K，建议调整为240s；若集群组网中卡数为5K，建议调整为600s。
```
export HCCL_CONNECT_TIMEOUT=600
```
3. 调整NPU之间共享缓冲区的大小。
  两个NPU之间共享数据的缓存区大小默认为200M，可通过环境变量HCCL_BUFFSIZE进行调整，单位为M，取值需要大于等于1，默认值是200M。
  
  集合通信网络中，每一个HCCL通信域都会占用HCCL_BUFFSIZE大小的缓存区。若集群网络中存在较多的HCCL通信域，此缓存区占用量就会增多，可能存在影响模型数据正常存放的风险，此种场景下，可通过此环境变量减少通信域占用的缓存区大小；若业务的模型数据量较小，但通信数据量较大，则可通过此环境变量增大HCCL通信域占用的缓存区大小，提升数据通信效率。
  
  使用hccl_test工具进行性能测试的场景下，往往通信数据量较大，此种场景下，可适当增大HCCL_BUFFSIZE的值，提升数据通信效率。
  
  配置示例：
```
export HCCL_BUFFSIZE=2048
```
  针对集合通信算子，当测试数据量超过HCCL_BUFFSIZE的取值时，可能会出现性能下降的情况，建议HCCL_BUFFSIZE的取值大于测试数据量。
4. 工具执行。
```
cd hccl_test
mpirun -n 8 ./bin/all_reduce_test -b 8K -e 64M -f 2 -d fp32 -o sum -p 8
```
  命令含义：执行allreduce算子，数据量（-b）从8KB到64MB，增量系数（-f）为2倍，参与训练的NPU个数（-p）为8，每个NPU上会拉起1个进程。
多机场景
1. 在训练进程拉起节点配置环境变量，并修改hostfile文件。
  1. 通过环境变量配置HCCL的初始化root通信网卡使用的IP协议版本以及网卡名，HCCL可通过配置的网卡名获取Host IP，完成通信域创建。
```
配置HCCL的初始化root通信网卡使用的IP协议版本，AF_INET：IPv4；AF_INET6：IPv6
export HCCL_SOCKET_FAMILY=AF_INET       #IPv4

# 支持以下格式的网卡名配置（4种规格自行选择1种即可，环境变量中可配置多个网卡，多个网卡间使用英文逗号分隔，取最先匹配到的网卡作为root网卡）

# 精确匹配网卡
export HCCL_SOCKET_IFNAME==eth0,enp0   # 使用指定的eth0或enp0网卡
export HCCL_SOCKET_IFNAME=^=eth0,enp0     # 不使用eth0与enp0网卡

# 模糊匹配网卡
export HCCL_SOCKET_IFNAME=eth,enp       # 使用所有以eth或enp为前缀的网卡
export HCCL_SOCKET_IFNAME=^eth,enp      # 不使用任何以eth或enp为前缀的网卡
```
    需要注意：
    
    MPI工具执行时，会将环境变量同步到所有节点，如果参与集合通信的不同节点的网卡名字不同，例如node1的网卡名为eth1，node2的网卡名为eth2，则需要使用模糊匹配网卡的方式进行环境变量配置。
  2. 修改hostfile文件。
    示例一：配置格式“节点IP:每节点进程数”，该配置方式仅支持使用IPv4协议进行通信的场景。
```
# 训练节点ip:每节点的进程数
10.78.130.22:8
10.78.130.21:8
```
    示例二：配置格式“节点名:每节点进程数”，该配置方式支持使用IPv4协议或者IPv6协议进行通信的场景。
```
# 训练节点名：每节点的进程数
node3:8
node4:8
```
2. 调整socket建链超时等待时间。
  集合通信场景中，设备间socket建链超时等待时间默认值为120s，当Master节点需要建链和处理的数据量较大时，默认值120秒无法满足建链需求，需要适当进行调整。
  
  例如，若集群组网中卡数为3K，建议调整为240s；若集群组网中卡数为5K，建议调整为600s。
```
export HCCL_CONNECT_TIMEOUT=600
```
3. 调整NPU之间共享缓冲区的大小。
  两个NPU之间共享数据的缓存区大小默认为200M，可通过环境变量HCCL_BUFFSIZE进行调整，单位为M，取值需要大于等于1，默认值是200M。
  
  集合通信网络中，每一个HCCL通信域都会占用HCCL_BUFFSIZE大小的缓存区。若集群网络中存在较多的HCCL通信域，此缓存区占用量就会增多，可能存在影响模型数据正常存放的风险，此种场景下，可通过此环境变量减少通信域占用的缓存区大小；若业务的模型数据量较小，但通信数据量较大，则可通过此环境变量增大HCCL通信域占用的缓存区大小，提升数据通信效率。
  
  使用hccl_test工具进行性能测试的场景下，往往通信数据量较大，此种场景下，可适当增大HCCL_BUFFSIZE的值，提升数据通信效率。
  
  配置示例：
```
export HCCL_BUFFSIZE=2048
```
  针对集合通信算子，当测试数据量超过HCCL_BUFFSIZE的取值时，可能会出现性能下降的情况，建议HCCL_BUFFSIZE的取值大于测试数据量。
4. 执行hccl_test测试工具。
  以2个计算节点，共16个NPU设备（每个计算节点包含8个NPU设备），每个NPU测试allreduce算子的性能为例：
```
cd hccl_test
mpirun -f hostfile -n 16 ./bin/all_reduce_test -b 8K -e 64M -f 2 -d fp32 -o sum -p 8
```

工具使用

前提条件

命令格式

参数说明

执行示例