HCCL 源码构建实战环境准备、一键编译、安装卸载与测试验证【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl本文基于 HCCL 仓库官方构建文档docs/zh/build/build.md展开系统介绍从基础环境搭建Docker 或宿主机两条路线、build.sh一键编译源码、软件包安装/卸载到 LLT 单元测试与 HCCL Test 上板测试的完整闭环。读完本文你可以独立在物理机或容器环境中编译出cann-hccl_version_linux-arch.run软件包完成安装替换与功能、性能验证并理解编译脚本背后的 CMake 工程细节与第三方依赖管理机制。一、环境准备依赖清单与两种部署路线前置软件依赖HCCL 支持源码构建编译前需完成基础环境搭建并安装 CANN Toolkit 开发套件包。需要特别注意NPU 驱动、固件和 CANN ops 算子包属于运行态依赖若仅编译源码可以不安装但在运行或上板测试前必须完成安装。编译所需软件依赖及版本要求如下python 3.7.0pip3 20.3.0gcc g7.3.0 至 14.2.xcmake 3.16.0与 CMakeLists.txt 中cmake_minimum_required(VERSION 3.16.0)一致ccache可选用于提高二次编译速度googletest仅执行 UT 时依赖建议版本 release-1.14.0从源码结构看googletest 仅在开启测试构建时被引入CMakeLists.txt 中ENABLE_TEST分支通过add_cann_third_party(gtest)拉取 gtest 并添加 test 子目录ST 测试工程 test/st/algorithm/CMakeLists.txt 同样依赖gtest。场景一使用 Docker 部署1. 安装驱动和固件在宿主机安装 Docker并参考《CANN 软件安装指南》安装配套驱动和固件。2. 下载构建镜像以下以 A3 镜像为例按宿主机 CPU 架构选择一条命令执行。# x86_64 docker pull --platformamd64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel # aarch64 docker pull --platformarm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel镜像内已预装构建工具及 CANN 软件默认以 root 用户进入。其他产品和版本请在 Ascend-CANN 镜像仓库中选择镜像版本须与源码分支、驱动和固件配套。开发 master 版本或更换 CANN 版本时可参照下文“安装 CANN 软件包”在容器内更新 CANN。3. 创建并进入容器以下假设使用/dev/davinci0和/dev/davinci1驱动安装在/usr/local/Ascend。imageswr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel docker run --name env_for_hccl_build --network host \ --device /dev/davinci0 \ --device /dev/davinci1 \ --device /dev/davinci_manager \ --device /dev/devmm_svm \ --device /dev/hisi_hdc \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ -v /usr/bin/hccn_tool:/usr/bin/hccn_tool \ -v /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 \ -v /usr/local/Ascend/driver/tools:/usr/local/Ascend/driver/tools \ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \ -v /etc/ascend_install.info:/etc/ascend_install.info \ -it ${image} bash设备号和挂载路径请按实际环境调整。仅编译时可省略设备及驱动相关挂载上板测试时须保留。更多选项可通过docker run --help查询。A5Atlas 950环境容器配置A5 使用配套镜像并挂载/dev/ummu、/dev/uburma和驱动topo目录以支持拓扑发现与 UB 通信无需挂载/dev/devmm_svm。以下仍以两个 Device 为例imageswr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.1.0-950-openeuler24.03-py3.12 docker run --name env_for_hccl_build_a5 --network host \ --device /dev/davinci0 \ --device /dev/davinci1 \ --device /dev/davinci_manager \ --device /dev/hisi_hdc \ --device /dev/ummu \ --device /dev/uburma \ -v /usr/local/dcmi:/usr/local/dcmi \ -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \ -v /usr/bin/hccn_tool:/usr/bin/hccn_tool \ -v /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 \ -v /usr/local/Ascend/driver/tools:/usr/local/Ascend/driver/tools \ -v /usr/local/Ascend/driver/topo:/usr/local/Ascend/driver/topo \ -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \ -v /etc/ascend_install.info:/etc/ascend_install.info \ -it ${image} bash容器内编译与测试进入容器后加载 CANN 环境变量脚本路径以所选镜像实际安装位置为准source /usr/local/Ascend/ascend-toolkit/set_env.sh随后按本文“编译安装”与“测试”章节执行。使用 HCCL Test 前需按配套工具指南在容器内准备 MPI 并编译工具测试设备须与容器映射一致。直接测试镜像自带 HCCL 时无需重新构建 HCCL 或关闭验签。场景二在宿主机部署安装 CANN 软件包安装驱动与固件运行态依赖驱动与固件的下载和安装操作请参考《CANN 软件安装指南》中“准备软件包”和“安装 NPU 驱动和固件”章节。驱动与固件是运行态依赖若仅编译本项目源码可以不安装。安装 CANN 软件包场景 1体验 master 版本能力或基于 master 版本进行开发请从 master 版本下载页cann-run-mirror/software/master选择最新时间版本并根据产品型号和环境架构下载对应软件包。安装命令如下更多指导参考《CANN 软件安装指南》。1安装 CANN Toolkit 开发套件包# 确保安装包具有可执行权限 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 算子包运行态依赖仅编译源码可不安装# 确保安装包具有可执行权限 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 官网下载中心选择发布版本仅支持 CANN 8.5.0 及后续版本并根据产品型号和环境架构下载对应软件包最后按网页提供的命令完成安装。环境验证安装完 CANN 软件包后需验证环境是否正常。检查 NPU 设备# 运行 npu-smi若能正常显示设备信息则驱动正常 npu-smi info检查 CANN 软件arch表示 CPU 架构aarch64 或 x86_64# 查看 CANN Toolkit 开发套件包的 version 字段默认路径安装 cat /usr/local/Ascend/cann/arch-linux/ascend_toolkit_install.info # 查看 CANN ops 算子包的 version 字段默认路径安装 cat /usr/local/Ascend/cann/arch-linux/ascend_ops_install.info环境变量配置按需选择合适的命令使环境变量生效# 默认路径安装以 root 用户为例非 root 用户将 /usr/local 替换为 ${HOME} source /usr/local/Ascend/cann/set_env.sh # 指定路径安装 # source ${install_path}/cann/set_env.shbuild.sh脚本在编译前会调用set_env函数加载 CANN 环境变量见 build.sh 中set_env()若环境中未设置ASCEND_CANN_PACKAGE_PATH等变量脚本还会按-p|--package-path参数、ASCEND_HOME_PATH、ASCEND_OPP_PATH、默认安装目录的顺序逐级推断 CANN 包路径推断失败会直接报错提示通过-p|--package-path指定。二、编译安装一键构建与软件包管理下载源码源码下载命令如下请将${tag_version}替换为目标分支标签名源码分支标签与 CANN 版本的配套关系参见 release 仓库的版本说明# 下载项目对应分支源码 git clone -b ${tag_version} https://gitcode.com/cann/hccl.git当前仓库的版本信息定义在 version.cmake 中当前为VERSION 9.2.0并声明了对 hcomm、runtime、metadef、bisheng-compiler、asc-devkit 等组件8.5的构建依赖。编译时build.sh会从该文件解析版本号用于软件包命名请确保所选源码标签与 CANN 版本配套。编译源码本项目提供一键式编译构建能力进入代码仓根目录执行如下命令# 编译 host 包 bash build.sh --pkg # 编译 host device 包 bash build.sh --pkg --full编译时会自动下载下文“开源第三方软件依赖”中列出的依赖包。如果编译环境无法访问网络需要在联网环境中下载依赖压缩包手动上传至编译环境并通过--cann_3rd_lib_path参数指定依赖包的存放路径# 指定软件包路径默认为./third_party bash build.sh --cann_3rd_lib_path{your_3rd_party_path}编译完成后会在./build_out目录下生成cann-hccl_version_linux-arch.run软件包其中version表示软件版本号arch表示操作系统架构取值为x86_64或aarch64。编译流程源码解析结合 build.sh 的实现可以确认上述命令背后的完整流程参数解析与默认值脚本将并行度JOB_NUM默认设为 CPU 核数 2 倍-j可覆盖--cann_3rd_lib_path会将路径转绝对路径后存入CANN_3RD_LIB_PATH默认${CURRENT_DIR}/third_party--full与--aicpu都会置位ENABLE_BUILD_DEVICEON即开启设备侧编译。构建入口build_hccl()脚本先导出TOOLCHAIN_DIR指向 CANN Toolkit 内的toolkit/toolchain/hcc交叉编译 hcc 工具链随后在./build目录执行cmake -S ../ -B .配置、cmake --build . -j${CPU_NUM}编译最后make package打包。设备侧device 包构建开启--full后主 CMake 流程通过 CMakeLists.txt 的add_cann_device_project(hccl)触发设备侧工程脚本build_device()还会以 cmake/device/CMakeLists.txt 为独立入口、配合 cmake/aarch64-hcc-toolchain.cmake 工具链文件编译scatter_aicpu_kernel、生成generate_device_aicpu_package即aicpu_hccl.tar.gzAICPU 算子包及sign_aicpu_hccl目标。CMakeLists.txt 中还有针对性说明AICPU kernel 运行在 aarch64 架构的 NPU 上x86 主机自动启用 aarch64 交叉编译。打包机制run 软件包由 CPack 外部脚本 cmake/makeself_custom.cmake 基于 makeself 生成--sha256校验、压缩等级 4cmake/package.cmake 中的pack_built_in()负责按架构x86_64/aarch64确定CPACK_ARCH并装配安装脚本与version.info这正是最终产物cann-hccl_version_linux-arch.run的来源。CANN 构建库获取cmake/fetch_cann_cmake.cmake 优先检查CANN_3RD_LIB_PATH/cann-cmake目录或cmake-master-058.tar.gz本地包不存在时才通过 FetchContent 从 git 拉取master-058标签——离线环境下预先放置本地包即可跳过网络下载。安装安装编译生成的 HCCL 软件包bash ./build_out/cann-hccl_version_linux-arch.run --full请注意编译时需要将上述命令中的软件包名称替换为实际软件包名称。安装完成后用户编译生成的 HCCL 软件包会替换已安装 CANN Toolkit 开发套件包中的 HCCL 相关软件。卸载若想卸载编译生成的 HCCL 软件包恢复到安装完 CANN Toolkit 开发套件包的状态bash ./build_out/cann-hccl_version_linux-arch.run --uninstall同样需要将命令中的软件包名称替换为实际软件包名称。三、测试LLT 单元测试与 HCCL Test 上板测试LLT 测试安装完编译生成的 HCCL 软件包后可通过如下命令执行 LLT 用例bash build.sh --ut从 build.sh 源码看--ut或-u会同时置位ENABLE_TESTon与ENABLE_UTon走build_ut()分支以-DENABLE_UTon重新配置 CMake编译出 test/ut 下的 googletest 用例工程随后run_ut()遍历build/test目录下所有可执行文件并逐一执行。上板测试说明上板测试前请确保已安装驱动固件、CANN Toolkit 开发套件包与 CANN ops 算子包。开发者可通过 HCCL Test 工具进行集合通信功能与性能的测试使用流程如下1. 工具编译使用 HCCL Test 工具前需要安装 MPI 依赖、编译 HCCL Test 工具详细操作方法参见配套版本的《昇腾文档中心 - HCCL 性能测试工具使用指南》中“MPI 安装与配置”与“工具编译”章节。2. 关闭验签源码仓编译生成的cann-hccl_version_linux-arch.run软件包中包含aicpu_hccl.tar.gzHCCL AICPU 算子包。该包会在业务启动时加载至 Device加载过程中默认由驱动进行安全验签确保包可信。由于开发者通过本源码仓自行编译生成的aicpu_hccl.tar.gz包中并不含签名头所以需要关闭驱动安全验签机制。关闭验签方式配套使用 Ascend HDK 25.5.T2.B001 及以上版本并通过该 Ascend HDK 自带的 npu-smi 工具关闭验签。以下参考命令需以 root 用户在物理机上执行以 device 0 为例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 算子的性能为例# /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 性能测试工具使用指南》中“工具执行”章节。4. 查看结果执行完 HCCL Test 工具后回显结果如下“check_result” 为 success代表通信算子执行成功AllReduce 算子功能正确“aveg_time”集合通信算子的执行耗时单位为 us“alg_bandwidth”集合通信算子执行带宽单位为 GB/s“data_size”单个 NPU 上参与集合通信的数据量单位为 Bytes。四、附录开源第三方软件依赖编译本项目时依赖的第三方开源软件如下对应 tar 包可放入--cann_3rd_lib_path指定的目录实现离线构建开源软件版本依赖包文件名makeself2.5.0makeself-release-2.5.0-patch1.tar.gzgoogletest1.14.0googletest-1.14.0.tar.gzcann-cmakemaster-058cmake-master-058.tar.gz上述依赖与源码实现一一对应makeselfcmake/package.cmake 通过add_cann_third_party(makeself-fetch)引入cmake/makeself_custom.cmake 中MAKESELF_EXE即指向${CPACK_3RD_LIB_PATH}/makeself/makeself.sh用于生成 run 自解包googletest仅测试构建引入见 CMakeLists.txt 中ENABLE_TEST分支的add_cann_third_party(gtest)cann-cmakeCANN 官方 CMake 函数库cmake/fetch_cann_cmake.cmake 中固定标签master-058提供init_cann_project、add_cann_third_party、pack_built_in等构建函数。完整依赖清单也可参考仓库根目录的 Third_Party_Open_Source_Software_List.yaml 与 Third_Party_Open_Source_Software_Notice。小结编译前按 Docker场景一注意 A5/Atlas 950 需额外挂载/dev/ummu、/dev/uburma、topo或宿主机场景二Toolkit ops 包同路径安装两条路线之一搭好环境并用npu-smi info与*_install.info验证编译时根目录执行bash build.sh --pkghost 包或追加--full含 AICPU 设备侧包离线环境用--cann_3rd_lib_path指向本地依赖目录安装/卸载对build_out下的 run 包执行--full安装或--uninstall卸载软件包会替换 Toolkit 中的 HCCL 组件测试时bash build.sh --ut跑 LLT 用例上板测试需先关闭自定义算子验签再用mpirun驱动 HCCL Test 工具完成功能正确性与带宽验证。【免费下载链接】hccl集合通信库Huawei Collective Communication Library简称HCCL是基于昇腾AI处理器的高性能集合通信库为计算集群提供高性能、高可靠的通信方案项目地址: https://gitcode.com/cann/hccl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考