HIXL 源码构建指南环境准备、编译选项、本地验证与安装全流程【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl本篇指南完整讲解 CANN/HIXL 开源仓库的源码构建流程从环境准备Docker 部署或手动安装 CANN 包、环境验证、环境变量配置到build.sh编译参数详解、tests/run_test.sh本地验证以及最终 run 包的安装与签名说明。读完本文你将能够独立完成 HIXL 从源码到可运行软件包的构建闭环并具备排查编译与测试失败的基本能力。文中所有命令均与当前仓库 build.sh、tests/run_test.sh 的实际实现保持一致。环境准备HIXL 支持源码编译。在开始编译前需要确保已经安装 Toolkit 开发套件包执行所有样例前需要确保已安装驱动和固件执行 Python 样例前还需要确保已安装 ops 包。软件安装方式可根据实际情况选择安装方式说明使用场景使用 Docker 部署Docker 镜像是一种 CANN 高效部署方式目前适用于 Atlas A2、A3、A5 系列产品OS 仅支持 Ubuntu 操作系统适用有昇腾设备需要快速搭建环境的开发者手动安装-适用有昇腾设备想体验手动安装 CANN 包或体验最新 master 分支能力的开发者场景一使用 Docker 部署1. 安装固件和驱动请参考 CANN 软件安装指南完成固件与驱动安装。2. 安装依赖、CANN Toolkit 开发套件包以及 CANN ops 算子包操作步骤如下下载 X86 构建镜像docker pull --platformamd64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel下载 ARM 构建镜像docker pull --platformarm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel上面提供的是 A3 环境上的镜像下载方式更多版本镜像和镜像使用方法可在 Ascend-CANN 镜像页根据实际需要自行选择。以下是推荐的使用方式可供参考imageswr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel # 创建并进入容器 # 假设您需要使用的NPU设备安装在/dev/davinci0和/dev/davinci1上并且您的NPU驱动程序安装在/usr/local/Ascend上 docker run \ --name env_for_hixl_build \ --device /dev/davinci0 \ --device /dev/davinci1 \ --device /dev/davinci_manager \ --device /dev/devmm_svm \ --device /dev/hisi_hdc \ --cap-add SYS_PTRACE \ -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[!NOTE] 说明--cap-add SYS_PTRACE创建 Docker 容器时添加SYS_PTRACE权限以支持本地验证时的内存泄漏检测功能。AscendHub CANN devel 镜像默认以root用户进入镜像内已预装 cmake、gcc、git 等构建工具。更多 docker 选项介绍请通过docker --help查询。配套构建镜像的 CANN 包安装路径为/usr/local/Ascend环境变量脚本为/usr/local/Ascend/ascend-toolkit/set_env.sh。如需要使用镜像之外的其他 CANN 版本可参考后续章节在 docker 内手工安装 CANN 包。A5Atlas 950环境容器配置A5 环境除上述通用配置外还需要额外的设备挂载与路径配置否则容器内无法完成拓扑发现和 UB 网络通信。以下命令可供参考镜像以 9.1.0-950 为例imageswr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.1.0-950-openeuler24.03-py3.12 # 创建并进入容器 # 假设您需要使用的NPU设备为/dev/davinci0~/dev/davinci7共8张卡并且您的NPU驱动程序安装在/usr/local/Ascend上 docker run -it \ --name env_for_hixl_build_a5 \ --network host \ --cap-add SYS_PTRACE \ --device /dev/davinci0 \ --device /dev/davinci1 \ --device /dev/davinci2 \ --device /dev/davinci3 \ --device /dev/davinci4 \ --device /dev/davinci5 \ --device /dev/davinci6 \ --device /dev/davinci7 \ --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 \ ${image} bash[!NOTE] 说明相比 A2/A3 通用配置A5 必须额外增加以下配置--device /dev/ummu、--device /dev/uburmaUB 网络通信所需的用户态设备。-v /usr/local/Ascend/driver/topo/:/usr/local/Ascend/driver/topo/拓扑信息目录缺少该挂载将导致容器内拓扑发现失败。--network host复用宿主机网络命名空间。/dev/devmm_svm为 A2/A3 的内存管理设备A5 上无需挂载。设备号/dev/davinciN请根据实际在位的卡数量调整。场景二手动安装 CANN 包场景 1体验 master 版本能力或基于 master 版本进行开发如果想体验master 分支最新能力可从官方软件下载渠道获取 master 版本软件包按照如下步骤安装。更多安装指导请参考 CANN 软件安装指南。安装固件和驱动请参考 CANN 软件安装指南完成。安装社区版 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}安装社区版 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}表示 ops 包中的 NPU 型号标识需按芯片型号选择对应关系如下芯片型号${soc_name}ops 包示例Ascend910A3Ascend-cann-A3-ops_${cann_version}_linux-${arch}.runAscend910B910bAscend-cann-910b-ops_${cann_version}_linux-${arch}.runAscend950950Ascend-cann-950-ops_${cann_version}_linux-${arch}.run${install_path}表示指定安装路径需要与 toolkit 包安装在相同路径root 用户默认安装在/usr/local/Ascend目录。场景 2体验已发布版本能力或基于已发布版本进行开发如果想体验官网正式发布的 CANN 包能力请访问 CANN 官网下载中心选择对应版本 CANN 软件包仅支持 CANN 8.5.0 及后续版本进行安装。环境验证安装完 CANN 包后需验证环境和驱动是否正常。检查 NPU 设备# 运行npu-smi若能正常显示设备信息则驱动正常 npu-smi info检查 CANN 安装# 查看CANN Toolkit的version字段提供的版本信息默认路径安装arch表示CPU架构aarch64或x86_64。 cat /usr/local/Ascend/cann/arch-linux/ascend_toolkit_install.info # 查看CANN ops的version字段提供的版本信息默认路径安装arch表示CPU架构aarch64或x86_64。 cat /usr/local/Ascend/cann/arch-linux/ascend_ops_install.info环境变量配置按需选择合适的命令使环境变量生效# Docker 配套构建镜像AscendHub CANN 镜像见场景一使用Docker部署 source /usr/local/Ascend/ascend-toolkit/set_env.sh # 手动安装默认路径以 root 用户为例非 root 用户将 /usr/local 替换为 ${HOME} source /usr/local/Ascend/cann/set_env.sh # 指定路径安装 # source ${install_path}/cann/set_env.sh源码编译安装第三方开源依赖以下所列为源码编译用到的依赖请注意版本要求# Ubuntu/Debian操作系统安装命令示例如下其他操作系统请自行安装 sudo apt-get install cmake bash ccacheGCC 7.3.x - 14.2.xPython 3.9.x - 3.14.xCMake 3.16.0bash 5.1.16由于测试用例开启了地址消毒代码中执行 system 函数会触发低版本的 bash 被地址消毒检查出内存泄露。unzip用于解压下载的第三方开源软件的 zip 压缩包。ccache可选ccache 为编译器缓存优化工具用于加快二次编译速度。HIXL 在编译时依赖的第三方开源软件列表如下开源软件版本下载地址googletest1.14.0googletest-1.14.0.tar.gzjson3.11.3json-3.11.3.tar.gzmakeself2.5.0makeself-release-2.5.0-patch1.tar.gzpybind112.13.6pybind11-2.13.6.tar.gzcann-cmakemaster-054cmake-master-054.tar.gz[!NOTE] 注意 如果您从其他地址下载请确保版本号一致。源码下载开发者可通过如下命令下载本仓源码git clone https://gitcode.com/cann/hixl.git[!NOTE] 注意 gitcode 平台在使用 HTTPS 协议的时候要配置并使用个人访问令牌代替登录密码进行克隆、推送等操作。若您的编译环境无法访问网络由于无法通过git指令下载代码须在联网环境中下载源码后手动上传至目标环境在联网环境中进入本项目主页通过「下载 ZIP」或「clone」按钮根据指导完成源码下载。连接至离线环境上传源码至您指定的目录下。若下载的为源码压缩包还需进行解压。源码编译若您的编译环境可以访问网络编译过程中将自动下载上述开源第三方软件可以使用如下命令进行编译# 默认路径安装root用户默认路径是/usr/local/Ascend普通用户默认路径是${HOME}/Ascend bash build.sh # 若源码未改动或者修改不涉及src/ops下的代码建议添加--host参数进行编译 bash build.sh --host # 若需要同时编译C样例或基准测试benchmarks需要额外指定--examples参数 bash build.sh --examples若您的编译环境无法访问网络您需要在联网环境中下载上述开源软件压缩包并手动上传至您的编译环境中您需要在编译环境中新建一个{your_3rd_party_path}目录来存放这些第三方开源软件mkdir -p {your_3rd_party_path}创建好目录后将下载好的第三方开源软件压缩包上传至目录{your_3rd_party_path}后可以使用如下命令进行编译bash build.sh --cann_3rd_lib_path{your_3rd_party_path}成功编译后会在 build_out 目录下生成cann-hixl_${cann_version}_linux-${arch}.run${cann_version}表示 cann 版本号。${arch}表示 CPU 架构如 aarch64、x86_64。更多执行选项可以用-h查看或查询下表bash build.sh -h参数说明默认值-h, --help打印帮助信息--v, --verbose显示详细的编译命令--jN设置编译时使用的线程数8--build_typeRelease\|Debug--build-typeRelease\|Debug设置编译类型Release--cann_3rd_lib_pathPATH--cann-3rd-lib-pathPATH设置第三方依赖包安装路径./third_party--output_pathPATH--output-pathPATH设置编译输出路径./build_out--pkg构建 run 包保留参数---pkg-typeTYPE指定软件包类型run、rpm、deb或allrun--examples编译样例和基准测试OFF--host仅编译 host 发布件跳过 device 编译和打包OFF--experimental启用实验特性开启后src/experimental/下的代码参与编译和打包OFF--asan启用地址消毒用于内存泄漏检测OFF--cov启用代码覆盖率OFF--sign-scriptPATH--sign_scriptPATH设置签名脚本的指定路径---enable-sign启用签名功能-编译参数的源码实现对应从 build.sh 的源码可以印证上述参数的实际行为默认值定义脚本在checkopts()函数中初始化THREAD_NUM8、OUTPUT_PATH${BASEPATH}/build_out、CANN_3RD_LIB_PATH$BASEPATH/third_party、CMAKE_BUILD_TYPERelease、PACKAGE_TYPErun与文档表格中的默认值完全一致。--asan/--cov联动源码中--cov与--asan都会额外将CMAKE_BUILD_TYPE强制设置为Debug对应ENABLE_GCOVON/ENABLE_ASANON的分支因此启用消毒或覆盖率时编译类型自动切换为 Debug这也解释了文档中bash 5.1.16由于测试用例开启了地址消毒的版本要求。--examples联动该参数一次打开三个开关ENABLE_EXAMPLESON、ENABLE_BENCHMARKSON、ENABLE_HIXL_TOOLON对应仓库中的 examples、benchmarks 与 scripts/tools/hixl_tool 三个子工程因此一条命令即可同时产出样例与基准测试。参数值校验check_build_type只接受Release/Debugcheck_pkg_type只接受run/rpm/deb/all非法取值会打印 usage 并exit 1可有效防止误传。构建流程build()函数通过cmake传入CMAKE_BUILD_TYPE、CMAKE_INSTALL_PREFIX、PACKAGE_TYPE、ENABLE_EXAMPLES、ENABLE_BENCHMARKS、ENABLE_HIXL_TOOL、ENABLE_ASAN、ENABLE_GCOV、HIXL_BUILD_HOST_ONLY、ENABLE_EXPERIMENTAL、ENABLE_SIGN、CUSTOM_SIGN_SCRIPT、CANN_3RD_LIB_PATH等宏随后执行make ${VERBOSE} -j${THREAD_NUM} make package最后通过move_pkg将生成的 run/rpm/deb 包移动到OUTPUT_PATH并在成功时打印Build success!。编译模式的关键差异默认编译会同时构建 host 和 device 发布件最终只在build_out目录下输出cann-hixl_*.run包。指定--host时不编译 src/ops 下的 device 子工程也不会将 device 发布件打包进build_out安装该 run 包时会保留已存在的 device 部分仅覆盖 host 部分卸载时才会一并删除。如果使用--host进行源码编译并部署运行时需要运行环境提前安装 ops 整包或者带有签名的 hixl 子包并保证源码和 run 包周版本一致--host编译的 run 包与运行环境整包无法保证跨版本执行兼容。源码编译时如果未修改源码或者修改不涉及 src/ops 下的代码建议添加--host进行编译可显著缩短编译时间。指定--experimental时src/experimental 目录下的 C 源文件会编入libcann_hixl.so其下的 Python 模块会注入到hixlwheel 中。默认关闭不影响现有功能。本地验证(tests)利用 tests 路径下的测试用例进行本地验证安装依赖# 安装根目录下requirements.txt依赖 pip3 install -r requirements.txtrequirements.txt 中声明的依赖包括 numpy、pyyaml6.0.1、decorator、sympy、scipy、attrs、protobuf、psutil、setuptools59.0.1、wheel0.37.1、coverage 等。如果需要本地查看 tests 覆盖率则需要额外安装 coverage并将 Python3 的 bin 路径添加到 PATH 环境变量中命令示例如下pip3 install coverage # 修改下面的PYTHON3_HOME为实际的PYTHON安装目录 export PATH$PATH:$PYTHON3_HOME/bin执行测试用例# 默认路径安装root用户默认路径是/usr/local/Ascend/普通用户默认路径是${HOME}/Ascend bash tests/run_test.sh # 如果已自行将第三方开源软件压缩包上传至目录{your_3rd_party_path}可以使用如下命令进行执行 bash tests/run_test.sh --cann_3rd_lib_path{your_3rd_party_path}更多执行选项可以用-h查看bash tests/run_test.sh -h从 tests/run_test.sh 的 usage 输出可以看到除--cann_3rd_lib_path外还支持-t/--test指定测试目标cpp仅跑 C 测试、py仅跑 Python 测试、缺省或all为两者全跑、-s/--suite指定 C 测试套件、-c/--cov以覆盖率模式构建、--asan启用地址消毒设置 cov 时会同时开启 asan、-f/--changed-files-file传入变更文件列表以跳过仅文档变更时的测试等。脚本开头会unset LD_LIBRARY_PATH与unset LD_PRELOAD避免环境变量污染测试进程。预期结果与失败排查测试通过构建阶段会打印build success!执行过程不出现红色提示!!! ... TEST FAILED, PLEASE CHECK YOUR CHANGES !!!脚本正常结束。C 用例失败输出红色!!! CPP TEST FAILED, PLEASE CHECK YOUR CHANGES !!!并给出失败用例命令与日志路径形如log: 日志文件可用cat 日志文件查看详情。定位后用bash tests/run_test.sh -t cpp -s suite单独复跑suite可选llm_datadist、adxl、channel_pool、hixl、fabric_mem。这些套件分别对应仓库中的 tests/cpp/llm_datadist、tests/cpp/adxl、tests/cpp/hixl/cs、tests/cpp/hixl、tests/cpp/hixl/fabric_mem 测试目录。Python 用例失败输出红色!!! PY TEST FAILED, PLEASE CHECK YOUR CHANGES !!!unittest 会直接打印失败堆栈据此定位用例。定位后用bash tests/run_test.sh -t py仅复跑 Python 测试。Python 用例位于 tests/python 与 tests/e2e 目录。构建失败提示build failed.请根据报错检查 CANN 环境变量是否加载、第三方依赖是否齐全。安装将源码编译环节生成的 run 包进行安装。此处的安装路径无论默认还是指定需与前面安装 toolkit 包时的路径保持一致。# 如果需要指定安装路径则加上--install-path${cann_install_path} ./cann-hixl_${cann_version}_linux-${arch}.run --full --quiet --pylocal--full全量模式安装。--quiet静默安装跳过人机交互环节。--pylocal安装 HIXL 软件包时是否将 .whl 安装到 HIXL 安装路径。若选择该参数则 .whl 安装在${cann_install_path}/cann/python/site-packages路径。若不选择该参数则 .whl 安装在本地 python 路径例如/usr/local/python3.7.5/lib/python3.7/site-packages。更多安装选项请用--help选项查看。安装脚本的实现可参考仓库中的 scripts/package/hixl/scripts 目录其中 install.sh、run_hixl_install.sh 与 hixl_custom_install.sh 等脚本共同负责软件包的解压、软链接创建与 Python wheel 安装等逻辑。关于签名的补充说明编译产生cann-hixl_version_linux-arch.run软件包中含有cann-hixl-compat.tar.gzhixl 兼容升级包。cann-hixl-compat.tar.gz会在业务启动时加载至 Device加载过程中默认会由驱动进行安全验签确保包可信。开发者下载本仓源码自行编译产生cann-hixl-compat.tar.gz并不含签名头为此需要关闭驱动安全验签的机制。关闭验签方式关闭验签功能依赖 Ascend NPU 驱动软件包Ascend HDK 25.5.T2.B001 或以上版本可以通过该 Ascend HDK 配套的 npu-smi 工具查询版本和关闭验签需要以 root 用户在物理机上执行。以 device 0 为例其中-i后面的参数是 device idnpu-smi info # 查询基本信息包含驱动版本 npu-smi set -t custom-op-secverify-enable -i 0 -d 1 # 使能自定义验签 npu-smi set -t custom-op-secverify-mode -i 0 -d 0 # 设置成关闭验签模式安装后的进一步使用安装完成后可参考 样例运行 尝试运行样例也可参考 基准测试 Benchmarks 尝试运行基准测试。此外仓库还提供了一键脚本 run_all_bench.sh 与 run_all_benchmarks.py 用于批量执行基准测试以及 scripts/ci_test/hixl.sh 用于 CI 场景下的构建与测试调度可结合实际需要选用。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HIXL 源码构建指南：环境准备、编译选项、本地验证与安装全流程
HIXL 源码构建指南环境准备、编译选项、本地验证与安装全流程【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl本篇指南完整讲解 CANN/HIXL 开源仓库的源码构建流程从环境准备Docker 部署或手动安装 CANN 包、环境验证、环境变量配置到build.sh编译参数详解、tests/run_test.sh本地验证以及最终 run 包的安装与签名说明。读完本文你将能够独立完成 HIXL 从源码到可运行软件包的构建闭环并具备排查编译与测试失败的基本能力。文中所有命令均与当前仓库 build.sh、tests/run_test.sh 的实际实现保持一致。环境准备HIXL 支持源码编译。在开始编译前需要确保已经安装 Toolkit 开发套件包执行所有样例前需要确保已安装驱动和固件执行 Python 样例前还需要确保已安装 ops 包。软件安装方式可根据实际情况选择安装方式说明使用场景使用 Docker 部署Docker 镜像是一种 CANN 高效部署方式目前适用于 Atlas A2、A3、A5 系列产品OS 仅支持 Ubuntu 操作系统适用有昇腾设备需要快速搭建环境的开发者手动安装-适用有昇腾设备想体验手动安装 CANN 包或体验最新 master 分支能力的开发者场景一使用 Docker 部署1. 安装固件和驱动请参考 CANN 软件安装指南完成固件与驱动安装。2. 安装依赖、CANN Toolkit 开发套件包以及 CANN ops 算子包操作步骤如下下载 X86 构建镜像docker pull --platformamd64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel下载 ARM 构建镜像docker pull --platformarm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel上面提供的是 A3 环境上的镜像下载方式更多版本镜像和镜像使用方法可在 Ascend-CANN 镜像页根据实际需要自行选择。以下是推荐的使用方式可供参考imageswr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.0.1-a3-ubuntu22.04-py3.12-devel # 创建并进入容器 # 假设您需要使用的NPU设备安装在/dev/davinci0和/dev/davinci1上并且您的NPU驱动程序安装在/usr/local/Ascend上 docker run \ --name env_for_hixl_build \ --device /dev/davinci0 \ --device /dev/davinci1 \ --device /dev/davinci_manager \ --device /dev/devmm_svm \ --device /dev/hisi_hdc \ --cap-add SYS_PTRACE \ -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[!NOTE] 说明--cap-add SYS_PTRACE创建 Docker 容器时添加SYS_PTRACE权限以支持本地验证时的内存泄漏检测功能。AscendHub CANN devel 镜像默认以root用户进入镜像内已预装 cmake、gcc、git 等构建工具。更多 docker 选项介绍请通过docker --help查询。配套构建镜像的 CANN 包安装路径为/usr/local/Ascend环境变量脚本为/usr/local/Ascend/ascend-toolkit/set_env.sh。如需要使用镜像之外的其他 CANN 版本可参考后续章节在 docker 内手工安装 CANN 包。A5Atlas 950环境容器配置A5 环境除上述通用配置外还需要额外的设备挂载与路径配置否则容器内无法完成拓扑发现和 UB 网络通信。以下命令可供参考镜像以 9.1.0-950 为例imageswr.cn-south-1.myhuaweicloud.com/ascendhub/cann:9.1.0-950-openeuler24.03-py3.12 # 创建并进入容器 # 假设您需要使用的NPU设备为/dev/davinci0~/dev/davinci7共8张卡并且您的NPU驱动程序安装在/usr/local/Ascend上 docker run -it \ --name env_for_hixl_build_a5 \ --network host \ --cap-add SYS_PTRACE \ --device /dev/davinci0 \ --device /dev/davinci1 \ --device /dev/davinci2 \ --device /dev/davinci3 \ --device /dev/davinci4 \ --device /dev/davinci5 \ --device /dev/davinci6 \ --device /dev/davinci7 \ --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 \ ${image} bash[!NOTE] 说明相比 A2/A3 通用配置A5 必须额外增加以下配置--device /dev/ummu、--device /dev/uburmaUB 网络通信所需的用户态设备。-v /usr/local/Ascend/driver/topo/:/usr/local/Ascend/driver/topo/拓扑信息目录缺少该挂载将导致容器内拓扑发现失败。--network host复用宿主机网络命名空间。/dev/devmm_svm为 A2/A3 的内存管理设备A5 上无需挂载。设备号/dev/davinciN请根据实际在位的卡数量调整。场景二手动安装 CANN 包场景 1体验 master 版本能力或基于 master 版本进行开发如果想体验master 分支最新能力可从官方软件下载渠道获取 master 版本软件包按照如下步骤安装。更多安装指导请参考 CANN 软件安装指南。安装固件和驱动请参考 CANN 软件安装指南完成。安装社区版 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}安装社区版 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}表示 ops 包中的 NPU 型号标识需按芯片型号选择对应关系如下芯片型号${soc_name}ops 包示例Ascend910A3Ascend-cann-A3-ops_${cann_version}_linux-${arch}.runAscend910B910bAscend-cann-910b-ops_${cann_version}_linux-${arch}.runAscend950950Ascend-cann-950-ops_${cann_version}_linux-${arch}.run${install_path}表示指定安装路径需要与 toolkit 包安装在相同路径root 用户默认安装在/usr/local/Ascend目录。场景 2体验已发布版本能力或基于已发布版本进行开发如果想体验官网正式发布的 CANN 包能力请访问 CANN 官网下载中心选择对应版本 CANN 软件包仅支持 CANN 8.5.0 及后续版本进行安装。环境验证安装完 CANN 包后需验证环境和驱动是否正常。检查 NPU 设备# 运行npu-smi若能正常显示设备信息则驱动正常 npu-smi info检查 CANN 安装# 查看CANN Toolkit的version字段提供的版本信息默认路径安装arch表示CPU架构aarch64或x86_64。 cat /usr/local/Ascend/cann/arch-linux/ascend_toolkit_install.info # 查看CANN ops的version字段提供的版本信息默认路径安装arch表示CPU架构aarch64或x86_64。 cat /usr/local/Ascend/cann/arch-linux/ascend_ops_install.info环境变量配置按需选择合适的命令使环境变量生效# Docker 配套构建镜像AscendHub CANN 镜像见场景一使用Docker部署 source /usr/local/Ascend/ascend-toolkit/set_env.sh # 手动安装默认路径以 root 用户为例非 root 用户将 /usr/local 替换为 ${HOME} source /usr/local/Ascend/cann/set_env.sh # 指定路径安装 # source ${install_path}/cann/set_env.sh源码编译安装第三方开源依赖以下所列为源码编译用到的依赖请注意版本要求# Ubuntu/Debian操作系统安装命令示例如下其他操作系统请自行安装 sudo apt-get install cmake bash ccacheGCC 7.3.x - 14.2.xPython 3.9.x - 3.14.xCMake 3.16.0bash 5.1.16由于测试用例开启了地址消毒代码中执行 system 函数会触发低版本的 bash 被地址消毒检查出内存泄露。unzip用于解压下载的第三方开源软件的 zip 压缩包。ccache可选ccache 为编译器缓存优化工具用于加快二次编译速度。HIXL 在编译时依赖的第三方开源软件列表如下开源软件版本下载地址googletest1.14.0googletest-1.14.0.tar.gzjson3.11.3json-3.11.3.tar.gzmakeself2.5.0makeself-release-2.5.0-patch1.tar.gzpybind112.13.6pybind11-2.13.6.tar.gzcann-cmakemaster-054cmake-master-054.tar.gz[!NOTE] 注意 如果您从其他地址下载请确保版本号一致。源码下载开发者可通过如下命令下载本仓源码git clone https://gitcode.com/cann/hixl.git[!NOTE] 注意 gitcode 平台在使用 HTTPS 协议的时候要配置并使用个人访问令牌代替登录密码进行克隆、推送等操作。若您的编译环境无法访问网络由于无法通过git指令下载代码须在联网环境中下载源码后手动上传至目标环境在联网环境中进入本项目主页通过「下载 ZIP」或「clone」按钮根据指导完成源码下载。连接至离线环境上传源码至您指定的目录下。若下载的为源码压缩包还需进行解压。源码编译若您的编译环境可以访问网络编译过程中将自动下载上述开源第三方软件可以使用如下命令进行编译# 默认路径安装root用户默认路径是/usr/local/Ascend普通用户默认路径是${HOME}/Ascend bash build.sh # 若源码未改动或者修改不涉及src/ops下的代码建议添加--host参数进行编译 bash build.sh --host # 若需要同时编译C样例或基准测试benchmarks需要额外指定--examples参数 bash build.sh --examples若您的编译环境无法访问网络您需要在联网环境中下载上述开源软件压缩包并手动上传至您的编译环境中您需要在编译环境中新建一个{your_3rd_party_path}目录来存放这些第三方开源软件mkdir -p {your_3rd_party_path}创建好目录后将下载好的第三方开源软件压缩包上传至目录{your_3rd_party_path}后可以使用如下命令进行编译bash build.sh --cann_3rd_lib_path{your_3rd_party_path}成功编译后会在 build_out 目录下生成cann-hixl_${cann_version}_linux-${arch}.run${cann_version}表示 cann 版本号。${arch}表示 CPU 架构如 aarch64、x86_64。更多执行选项可以用-h查看或查询下表bash build.sh -h参数说明默认值-h, --help打印帮助信息--v, --verbose显示详细的编译命令--jN设置编译时使用的线程数8--build_typeRelease\|Debug--build-typeRelease\|Debug设置编译类型Release--cann_3rd_lib_pathPATH--cann-3rd-lib-pathPATH设置第三方依赖包安装路径./third_party--output_pathPATH--output-pathPATH设置编译输出路径./build_out--pkg构建 run 包保留参数---pkg-typeTYPE指定软件包类型run、rpm、deb或allrun--examples编译样例和基准测试OFF--host仅编译 host 发布件跳过 device 编译和打包OFF--experimental启用实验特性开启后src/experimental/下的代码参与编译和打包OFF--asan启用地址消毒用于内存泄漏检测OFF--cov启用代码覆盖率OFF--sign-scriptPATH--sign_scriptPATH设置签名脚本的指定路径---enable-sign启用签名功能-编译参数的源码实现对应从 build.sh 的源码可以印证上述参数的实际行为默认值定义脚本在checkopts()函数中初始化THREAD_NUM8、OUTPUT_PATH${BASEPATH}/build_out、CANN_3RD_LIB_PATH$BASEPATH/third_party、CMAKE_BUILD_TYPERelease、PACKAGE_TYPErun与文档表格中的默认值完全一致。--asan/--cov联动源码中--cov与--asan都会额外将CMAKE_BUILD_TYPE强制设置为Debug对应ENABLE_GCOVON/ENABLE_ASANON的分支因此启用消毒或覆盖率时编译类型自动切换为 Debug这也解释了文档中bash 5.1.16由于测试用例开启了地址消毒的版本要求。--examples联动该参数一次打开三个开关ENABLE_EXAMPLESON、ENABLE_BENCHMARKSON、ENABLE_HIXL_TOOLON对应仓库中的 examples、benchmarks 与 scripts/tools/hixl_tool 三个子工程因此一条命令即可同时产出样例与基准测试。参数值校验check_build_type只接受Release/Debugcheck_pkg_type只接受run/rpm/deb/all非法取值会打印 usage 并exit 1可有效防止误传。构建流程build()函数通过cmake传入CMAKE_BUILD_TYPE、CMAKE_INSTALL_PREFIX、PACKAGE_TYPE、ENABLE_EXAMPLES、ENABLE_BENCHMARKS、ENABLE_HIXL_TOOL、ENABLE_ASAN、ENABLE_GCOV、HIXL_BUILD_HOST_ONLY、ENABLE_EXPERIMENTAL、ENABLE_SIGN、CUSTOM_SIGN_SCRIPT、CANN_3RD_LIB_PATH等宏随后执行make ${VERBOSE} -j${THREAD_NUM} make package最后通过move_pkg将生成的 run/rpm/deb 包移动到OUTPUT_PATH并在成功时打印Build success!。编译模式的关键差异默认编译会同时构建 host 和 device 发布件最终只在build_out目录下输出cann-hixl_*.run包。指定--host时不编译 src/ops 下的 device 子工程也不会将 device 发布件打包进build_out安装该 run 包时会保留已存在的 device 部分仅覆盖 host 部分卸载时才会一并删除。如果使用--host进行源码编译并部署运行时需要运行环境提前安装 ops 整包或者带有签名的 hixl 子包并保证源码和 run 包周版本一致--host编译的 run 包与运行环境整包无法保证跨版本执行兼容。源码编译时如果未修改源码或者修改不涉及 src/ops 下的代码建议添加--host进行编译可显著缩短编译时间。指定--experimental时src/experimental 目录下的 C 源文件会编入libcann_hixl.so其下的 Python 模块会注入到hixlwheel 中。默认关闭不影响现有功能。本地验证(tests)利用 tests 路径下的测试用例进行本地验证安装依赖# 安装根目录下requirements.txt依赖 pip3 install -r requirements.txtrequirements.txt 中声明的依赖包括 numpy、pyyaml6.0.1、decorator、sympy、scipy、attrs、protobuf、psutil、setuptools59.0.1、wheel0.37.1、coverage 等。如果需要本地查看 tests 覆盖率则需要额外安装 coverage并将 Python3 的 bin 路径添加到 PATH 环境变量中命令示例如下pip3 install coverage # 修改下面的PYTHON3_HOME为实际的PYTHON安装目录 export PATH$PATH:$PYTHON3_HOME/bin执行测试用例# 默认路径安装root用户默认路径是/usr/local/Ascend/普通用户默认路径是${HOME}/Ascend bash tests/run_test.sh # 如果已自行将第三方开源软件压缩包上传至目录{your_3rd_party_path}可以使用如下命令进行执行 bash tests/run_test.sh --cann_3rd_lib_path{your_3rd_party_path}更多执行选项可以用-h查看bash tests/run_test.sh -h从 tests/run_test.sh 的 usage 输出可以看到除--cann_3rd_lib_path外还支持-t/--test指定测试目标cpp仅跑 C 测试、py仅跑 Python 测试、缺省或all为两者全跑、-s/--suite指定 C 测试套件、-c/--cov以覆盖率模式构建、--asan启用地址消毒设置 cov 时会同时开启 asan、-f/--changed-files-file传入变更文件列表以跳过仅文档变更时的测试等。脚本开头会unset LD_LIBRARY_PATH与unset LD_PRELOAD避免环境变量污染测试进程。预期结果与失败排查测试通过构建阶段会打印build success!执行过程不出现红色提示!!! ... TEST FAILED, PLEASE CHECK YOUR CHANGES !!!脚本正常结束。C 用例失败输出红色!!! CPP TEST FAILED, PLEASE CHECK YOUR CHANGES !!!并给出失败用例命令与日志路径形如log: 日志文件可用cat 日志文件查看详情。定位后用bash tests/run_test.sh -t cpp -s suite单独复跑suite可选llm_datadist、adxl、channel_pool、hixl、fabric_mem。这些套件分别对应仓库中的 tests/cpp/llm_datadist、tests/cpp/adxl、tests/cpp/hixl/cs、tests/cpp/hixl、tests/cpp/hixl/fabric_mem 测试目录。Python 用例失败输出红色!!! PY TEST FAILED, PLEASE CHECK YOUR CHANGES !!!unittest 会直接打印失败堆栈据此定位用例。定位后用bash tests/run_test.sh -t py仅复跑 Python 测试。Python 用例位于 tests/python 与 tests/e2e 目录。构建失败提示build failed.请根据报错检查 CANN 环境变量是否加载、第三方依赖是否齐全。安装将源码编译环节生成的 run 包进行安装。此处的安装路径无论默认还是指定需与前面安装 toolkit 包时的路径保持一致。# 如果需要指定安装路径则加上--install-path${cann_install_path} ./cann-hixl_${cann_version}_linux-${arch}.run --full --quiet --pylocal--full全量模式安装。--quiet静默安装跳过人机交互环节。--pylocal安装 HIXL 软件包时是否将 .whl 安装到 HIXL 安装路径。若选择该参数则 .whl 安装在${cann_install_path}/cann/python/site-packages路径。若不选择该参数则 .whl 安装在本地 python 路径例如/usr/local/python3.7.5/lib/python3.7/site-packages。更多安装选项请用--help选项查看。安装脚本的实现可参考仓库中的 scripts/package/hixl/scripts 目录其中 install.sh、run_hixl_install.sh 与 hixl_custom_install.sh 等脚本共同负责软件包的解压、软链接创建与 Python wheel 安装等逻辑。关于签名的补充说明编译产生cann-hixl_version_linux-arch.run软件包中含有cann-hixl-compat.tar.gzhixl 兼容升级包。cann-hixl-compat.tar.gz会在业务启动时加载至 Device加载过程中默认会由驱动进行安全验签确保包可信。开发者下载本仓源码自行编译产生cann-hixl-compat.tar.gz并不含签名头为此需要关闭驱动安全验签的机制。关闭验签方式关闭验签功能依赖 Ascend NPU 驱动软件包Ascend HDK 25.5.T2.B001 或以上版本可以通过该 Ascend HDK 配套的 npu-smi 工具查询版本和关闭验签需要以 root 用户在物理机上执行。以 device 0 为例其中-i后面的参数是 device idnpu-smi info # 查询基本信息包含驱动版本 npu-smi set -t custom-op-secverify-enable -i 0 -d 1 # 使能自定义验签 npu-smi set -t custom-op-secverify-mode -i 0 -d 0 # 设置成关闭验签模式安装后的进一步使用安装完成后可参考 样例运行 尝试运行样例也可参考 基准测试 Benchmarks 尝试运行基准测试。此外仓库还提供了一键脚本 run_all_bench.sh 与 run_all_benchmarks.py 用于批量执行基准测试以及 scripts/ci_test/hixl.sh 用于 CI 场景下的构建与测试调度可结合实际需要选用。【免费下载链接】hixlHIXLHuawei Xfer Library是一个灵活、高效的昇腾单边通信库面向集群场景提供简单、可靠、高效的点对点数据传输能力。项目地址: https://gitcode.com/cann/hixl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考