@@ -2,50 +2,213 @@ ## 环境准备 -1. 安装依赖。 +本项目支持源码构建，编译运行前需参考以下步骤完成基础环境搭建和源码下载，确保已安装NPU驱动、固件和CANN软件。 - 本项目编译用到的软件依赖如下，请注意版本要求。 +### 前置依赖 - - python: 3.7.x 至 3.11.4 版本 - - pip >= 20.3.0 - - setuptools >= 45.0.0 - - wheel >= 0.34.0 - - gcc >= 7.3.0 - - cmake >= 3.16.0 - - pkg-config >= 0.29.1（用于编译rdma-core） - - ccache（可选，用于提高二次编译速度） +本项目编译用到的软件依赖如下，注意满足版本号要求。 -2. 安装社区版CANN Toolkit包 +- python: 3.7.x 至 3.11.4 版本 +- pip >= 20.3.0 +- setuptools >= 45.0.0 +- wheel >= 0.34.0 +- gcc >= 7.3.0 +- cmake >= 3.16.0 +- pkg-config >= 0.29.1（用于编译rdma-core） +- ccache（可选，用于提高二次编译速度） - 编译本项目依赖CANN Toolkit开发套件包，请根据操作系统架构，从[CANN软件包归档页面](https://ascend.devcloud.huaweicloud.com/artifactory/cann-run-mirror/software/master/)中下载最新的CANN Toolkit安装包，参考[昇腾文档中心-CANN软件安装指南](https://www.hiascend.com/document/redirect/CannCommunityInstWizard)中的“安装CANN-安装Toolkit开发套件包”章节进行安装： +### 安装CANN软件包 - ```shell - # 安装命令，其中--install-path为可选参数，用于指定安装路径 - bash Ascend-cann-toolkit__linux-.run --full --install-path= +1. **安装驱动与固件（运行态依赖）** + + 驱动与固件的下载和安装操作请参考《[CANN软件安装指南](https://www.hiascend.com/document/redirect/CannCommunityInstWizard)》中“准备软件包”和“安装NPU驱动和固件”章节。驱动与固件是运行态依赖，若仅编译本项目源码，可以不安装。 + +2. **安装CANN软件包** + + - **场景1：体验master版本能力或基于master版本进行开发** + + 请单击[下载链接](https://ascend.devcloud.huaweicloud.com/artifactory/cann-run-mirror/software/master/)，选择最新时间版本，并根据产品型号和环境架构下载对应软件包。安装命令如下，更多指导参考《[CANN软件安装指南](https://www.hiascend.com/document/redirect/CannCommunityInstWizard)》。 + + 1. 安装CANN Toolkit开发套件包。 + + ```bash + # 确保安装包具有可执行权限 + chmod +x Ascend-cann-toolkit_${cann_version}_linux-${arch}.run + # 安装命令 + ./Ascend-cann-toolkit_${cann_version}_linux-${arch}.run --install --install-path=${install_path} + ``` + + 2. 安装CANN ops算子包（运行态依赖）。 + + ops算子包是运行态依赖，若仅编译本项目源码，可不安装此软件包。 + + ```bash + # 确保安装包具有可执行权限 + chmod +x Ascend-cann-${soc_name}-ops_${cann_version}_linux-${arch}.run + # 安装命令 + ./Ascend-cann-${soc_name}-ops_${cann_version}_linux-${arch}.run --install --install-path=${install_path} + ``` + + - \$\{cann\_version\}：表示CANN软件包版本号。 + - \$\{arch\}：表示CPU架构，如aarch64、x86_64。 + - \$\{soc\_name\}：表示NPU型号名称。 + - \$\{install\_path\}：表示指定安装路径，CANN ops算子包需与CANN Toolkit开发套件包安装在相同路径，root用户默认安装在`/usr/local/Ascend`目录。 + + - **场景2：体验已发布版本能力或基于已发布版本进行开发** + + 请访问[CANN官网下载中心](https://www.hiascend.com/cann/download)，选择发布版本（仅支持CANN 8.5.0及后续版本），并根据产品型号和环境架构下载对应软件包，最后参考网页提供的命令完成安装。 + +### 环境验证 + +安装完CANN软件包后，需验证环境是否正常。 + +- **检查NPU设备**： + + ```bash + # 运行npu-smi，若能正常显示设备信息，则驱动正常 + npu-smi info + ``` + +- **检查CANN软件**： + + ```bash + # 查看CANN Toolkit开发套件包的version字段提供的版本信息（默认路径安装），表示CPU架构（aarch64或x86_64）。 + cat /usr/local/Ascend/cann/-linux/ascend_toolkit_install.info + # 查看CANN ops算子包的version字段提供的版本信息（默认路径安装）。 + cat /usr/local/Ascend/cann/-linux/ascend_ops_install.info ``` - - ``: 表示CANN包版本号。 - - ``: 表示CPU架构，如aarch64、x86_64。 - - ``: 表示指定安装路径，可选，root用户默认安装在/usr/local/Ascend目录，指定路径安装时，指定的路径权限需设置为755。 +### 环境变量配置 -3. 设置CANN软件环境变量。 +按需选择合适的命令使环境变量生效。 - ```shell - # 默认路径，root用户安装 - source /usr/local/Ascend/cann/set_env.sh - - # 默认路径，非root用户安装 - source $HOME/Ascend/cann/set_env.sh - ``` - -## 源码下载 - -```shell -# 下载项目源码，以master分支为例 -git clone https://gitcode.com/cann/hcomm.git +```bash +# 默认路径安装，以root用户为例（非root用户，将/usr/local替换为${HOME}） +source /usr/local/Ascend/cann/set_env.sh +# 指定路径安装 +# source ${install_path}/cann/set_env.sh ``` -## 编译 +## 编译安装 + +### 下载源码 + +源码下载命令如下，请将\$\{tag\_version\}替换为目标分支标签名，源码分支标签与CANN版本配套关系参见[release仓库](https://gitcode.com/cann/release-management)。 + +```shell +# 下载项目对应分支源码 +git clone -b ${tag_version} https://gitcode.com/cann/hcomm.git +``` + +### 编译源码 + +本项目提供一键式编译构建能力，进入代码仓根目录，执行如下命令： + +```shell +# 编译 host 包 +bash build.sh --pkg +# 编译 host + device 包 +bash build.sh --pkg --full +``` + +编译时会自动下载[开源第三方软件依赖](#开源第三方软件依赖)中列出的依赖包。如果编译环境无法访问网络，您需要在联网环境中下载上述依赖压缩包，手动上传至编译环境，并通过 `--cann_3rd_lib_path` 参数指定依赖包的存放路径。 + +```shell +# 指定依赖包存放路径，默认为：./third_party +bash build.sh --cann_3rd_lib_path={your_3rd_party_path} +``` + +编译完成后，会在`./build_out`目录下生成 `cann-hcomm__linux-.run` 软件包。 + +其中 ``表示软件版本号，``表示操作系统架构，取值包括“x86_64”与“aarch64”。 + +### 安装 + +安装编译生成的HCOMM软件包： + +```shell +bash ./build_out/cann-hcomm__linux-.run --full +``` + +请注意：编译时需要将上述命令中的软件包名称替换为实际软件包名称。 + +安装完成后，用户编译生成的HCOMM软件包会替换已安装CANN Toolkit开发套件包中的HCOMM相关软件。 + +### 卸载 + +若您想卸载编译生成的HCOMM软件包，恢复到安装完CANN Toolkit开发套件包的状态，可参考如下命令： + +```shell +bash ./build_out/cann-hcomm__linux-.run --uninstall +``` + +请注意：卸载时需要将上述命令中的软件包名称替换为实际软件包名称。 + +## 测试 + +### LLT 测试 + +安装完编译生成的HCOMM软件包后，可通过如下命令执行LLT用例。 + +```shell +bash build.sh --ut +``` + +### 上板测试 + +> [!NOTE]说明 +> 上板测试前，请确保已安装驱动固件、CANN Toolkit开发套件包与CANN ops算子包。 + +开发者可通过HCCL Test工具进行集合通信功能与性能的上板测试，HCCL Test工具的使用流程如下： + +1. 工具编译 + + 使用HCCL Test工具前需要安装MPI依赖、编译HCCL Test工具，详细操作方法可参见配套版本的[昇腾文档中心-HCCL性能测试工具使用指南](https://hiascend.com/document/redirect/CannCommunityToolHcclTest)中的“MPI安装与配置”与“工具编译”章节。 + +2. 关闭验签 + + 本源码仓编译生成的`cann-hcomm__linux-.run`软件包中包含如下tar.gz子包： + - `cann-hcomm-compat.tar.gz`: HCOMM兼容升级包。 + - `cann-hccd-compat.tar.gz`: DataFlow兼容升级包。 + - `aicpu_hcomm.tar.gz`: AI CPU通信基础包。 + + 上述tar.gz包会在业务启动时加载至Device，加载过程中默认会由驱动进行安全验签，确保包可信。由于开发者通过本源码仓自行编译生成的tar.gz包中并不含签名头，所以需要关闭驱动安全验签的机制。 + + **关闭验签方式：** + + 配套使用Ascend HDK 25.5.T2.B001及以上版本，并通过该Ascend HDK自带的npu-smi工具关闭验签。以下为参考命令，需要以root用户在物理机上执行（以device 0为例）。 + + ```shell + npu-smi set -t custom-op-secverify-enable -i 0 -d 1 # 使能验签配置 + npu-smi set -t custom-op-secverify-mode -i 0 -d 0 # 关闭客户自定义验签 + ``` + +3. 执行HCCL Test测试命令，测试集合通信的功能及性能。 + + 以1个计算节点，8个NPU设备，测试AllReduce算子的性能为例，命令示例如下： + + ```shell + # “/usr/local/Ascend”是root用户以默认路径安装的CANN软件安装路径，请根据实际情况替换 + cd /usr/local/Ascend/ascend-toolkit/latest/tools/hccl_test + + # 数据量（-b）从8KB到64MB，增量系数（-f）为2倍，参与训练的NPU个数为8 + mpirun -n 8 ./bin/all_reduce_test -b 8K -e 64M -f 2 -d fp32 -o sum -p 8 + ``` + + 工具的详细使用说明可参见[昇腾文档中心-HCCL 性能测试工具使用指南](https://hiascend.com/document/redirect/CannCommunityToolHcclTest)中的“工具执行”章节。 + +4. 查看结果 + + 执行完HCCL Test工具后，回显示例如下： + + ![hccltest_result](figures/hccl_test_result.png) + + - “check_result”为 success，代表通信算子执行结果成功，AllReduce 算子功能正确。 + - ”aveg_time“：集合通信算子的执行耗时，单位 us。 + - ”alg_bandwidth“：集合通信算子执行带宽，单位为 GB/s。 + - ”data_size“：单个 NPU 上参与集合通信的数据量，单位为 Bytes。 + +## 附录 ### 开源第三方软件依赖 @@ -65,130 +228,4 @@ git clone https://gitcode.com/cann/hcomm.git | abseil-cpp | 20250127.0 | [abseil-cpp-20250127.0.tar.gz](https://gitcode.com/cann-src-third-party/abseil-cpp/releases/download/20250127.0/abseil-cpp-20250127.0.tar.gz) | | protobuf | 25.1 | [protobuf-25.1.tar.gz](https://gitcode.com/cann-src-third-party/protobuf/releases/download/v25.1/protobuf-25.1.tar.gz) | | rdma-core | v42.7-h1 | [rdma-core-42.7.tar.gz](https://gitcode.com/cann-src-third-party/rdma-core/releases/download/v42.7-h1/rdma-core-42.7.tar.gz) | -| rdma-core-patch | v42.7-h1 | [rdma-core-42.7.patch](https://gitcode.com/cann-src-third-party/rdma-core/releases/download/v42.7-h1/rdma-core-42.7.patch) | -### 源码编译 - -本项目提供一键式编译构建能力，进入代码仓根目录，执行如下命令： - -```shell -# 编译 host 包 -bash build.sh --pkg -# 编译 host + device 包 -bash build.sh --pkg --full -``` - -若您的编译环境无法访问网络，您需要在联网环境中下载上述开源软件压缩包，并手动上传至编译环境中，并通过 `--cann_3rd_lib_path` 参数指定软件包路径： - -```shell -# 指定软件包路径，默认为：./third_party -bash build.sh --cann_3rd_lib_path={your_3rd_party_path} -``` - -编译完成后会在`./build_out`目录下生成 `cann-hcomm__linux-.run` 软件包。 - -> ``表示软件版本号，``表示操作系统架构，取值包括“x86_64”与“aarch64”。 - -## 安装 - -安装编译生成的HCOMM软件包： - -```shell -bash ./build_out/cann-hcomm__linux-.run --full -``` - -请注意：编译时需要将上述命令中的软件包名称替换为实际编译生成的软件包名称。 - -安装完成后，用户编译生成的HCOMM软件包会替换已安装CANN开发套件包中的HCOMM相关软件。 - -## 卸载 - -卸载已安装的HCOMM软件包： - -```shell -bash ./build_out/cann-hcomm__linux-.run --uninstall -``` - -请注意：卸载时需要将上述命令中的软件包名称替换为实际安装的软件包名称。 - -## LLT 测试 - -安装完编译生成的HCOMM软件包后，可通过如下命令执行LLT用例。 - -```shell -bash build.sh --ut -``` - -## 上板测试 - -HCCL软件包安装完成后，开发者可通过HCCL Test工具进行集合通信功能与性能的测试，HCCL Test工具的使用流程如下： - -1. 环境准备 - - 运行本项目除需安装CANN Toolkit开发套件包外，还需安装NPU驱动、NPU固件和CANN ops算子包。 - - NPU驱动和固件可参考[昇腾文档中心-CANN软件安装指南](https://www.hiascend.com/document/redirect/CannCommunityInstWizard)中的“安装NPU驱动和固件”章节进行安装： - - ```shell - # 安装驱动 - ./Ascend-hdk--npu-driver__linux-.run --full --install-for-all - - # 安装固件 - ./Ascend-hdk--npu-firmware_.run --full - ``` - - CANN ops算子包可根据NPU产品型号和操作系统架构，从[CANN软件包归档页面](https://ascend.devcloud.huaweicloud.com/artifactory/cann-run-release/software/master/)中下载对应的CANN ops包，参考[昇腾文档中心-CANN软件安装指南](https://www.hiascend.com/document/redirect/CannCommunityInstWizard)中的“安装CANN-安装ops算子包”章节进行安装： - - ```shell - # 安装算子包 - bash Ascend-cann--ops__linux-.run --install - ``` - - - ``: 表示NPU产品型号。 - - ``: 表示CANN包版本号。 - - ``: 表示CPU架构，如aarch64、x86_64。 - -2. 工具编译 - - 使用 HCCL Test 工具前需要安装 MPI 依赖，配置相关环境变量，并编译 HCCL Test 工具，详细操作方法可参见配套版本的[昇腾文档中心-HCCL 性能测试工具使用指南](https://hiascend.com/document/redirect/CannCommunityToolHcclTest)中的“工具编译”章节。 - -3. 关闭验签 - - - hcomm仓编译产生`cann-hcomm__linux-.run`软件包中包含如下tar.gz包： - - `cann-hcomm-compat.tar.gz`: hcomm兼容升级包 - - `cann-hccd-compat.tar.gz`: dataflow兼容升级包 - - `aicpu_hcomm.tar.gz`: AICPU通信基础包 - - 上述tar.gz包会在业务启动时加载至Device，加载过程中默认会由驱动进行安全验签，确保包可信 - - 开发者下载hcomm仓源码自行编译产生的tar.gz包并不含签名头，为此需要关闭驱动安全验签的机制 - - 关闭验签方式： - - 配套使用HDK 25.5.T2.B001或以上版本，并通过该HDK配套的npu-smi工具关闭验签。参考如下命令，以root用户在物理机上执行。 - 以device 0为例： - ```shell - npu-smi set -t custom-op-secverify-enable -i 0 -d 1 # 使能验签配置 - npu-smi set -t custom-op-secverify-mode -i 0 -d 0 # 关闭客户自定义验签 - ``` - -4. 执行HCCL Test测试命令，测试集合通信的功能及性能 - - 以1个计算节点，8个NPU设备，测试AllReduce算子的性能为例，命令示例如下： - - ```shell - # “/usr/local/Ascend”是root用户以默认路径安装的CANN软件安装路径，请根据实际情况替换 - cd /usr/local/Ascend/ascend-toolkit/latest/tools/hccl_test - - # 数据量（-b）从8KB到64MB，增量系数（-f）为2倍，参与训练的NPU个数为8 - mpirun -n 8 ./bin/all_reduce_test -b 8K -e 64M -f 2 -d fp32 -o sum -p 8 - ``` - - 工具的详细使用说明可参见[昇腾文档中心-HCCL 性能测试工具使用指南](https://hiascend.com/document/redirect/CannCommunityToolHcclTest)中的“工具执行”章节。 - -5. 查看结果 - - 执行完HCCL Test工具后，回显示例如下： - - ![hccltest_result](figures/hccl_test_result.png) - - - “check_result”为 success，代表通信算子执行结果成功，AllReduce 算子功能正确。 - - ”aveg_time“：集合通信算子的执行耗时，单位 us。 - - ”alg_bandwidth“：集合通信算子执行带宽，单位为 GB/s。 - - ”data_size“：单个 NPU 上参与集合通信的数据量，单位为 Bytes。 +| rdma-core-patch | v42.7-h1 | [rdma-core-42.7.patch](https://gitcode.com/cann-src-third-party/rdma-core/releases/download/v42.7-h1/rdma-core-42.7.patch)| \ No newline at end of file