CANN ops-math 源码构建完全指南自定义算子包、ops-math 包与静态库的编译、安装与验证【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math本指南系统讲解 CANN 数学算子库 ops-math 的源码构建全流程涵盖第三方依赖准备、联网/未联网两种编译场景、三种产物形态自定义算子包、ops-math 包、ops-math 静态库的编译/安装/卸载操作以及构建完成后的本地 UT 验证方法。读完本文你将能够根据业务场景选择合适的构建方式在 Atlas 训练/推理系列产品上完成算子包的自助构建与部署。构建前的准备源码构建前需要先完成环境准备和源码下载具体可参考项目根目录 README.md 与 环境部署环境准备完成 NPU 驱动、CANN toolkit 包安装确保环境正常构建脚本会通过ASCEND_HOME_PATH环境变量定位 CANN 安装路径。源码下载下载与 CANN 版本配套的分支源码。通用命令为git clone -b ${tag_version} https://gitcode.com/cann/ops-math.git例如下载 9.0.0 分支git clone -b 9.0.0 https://gitcode.com/cann/ops-math.git说明若环境中已存在配套分支源码如 CANNLab 默认已提供最新版本 CANN 对应的源码可跳过源码下载步骤。从源码结构看ops-math 仓库以算子为粒度组织源码每个算子目录下包含op_apiaclnn 接口层、op_host算子原型与信息注册、op_kernelAI Core 内核、op_kernel_aicpuAI CPU 内核、testsUT 用例等子目录例如 math/abs 与 conversion/transpose。编译脚本据此实现了按算子粒度的选择性编译这也是下文三种产物形态的基础。三种产物形态按部署诉求选择项目根目录的编译入口 build.sh 支持三种产物形态它们的定位与能力边界不同请按需选择产物形态编译范围与 CANN 包关系支持调用方式自定义算子包选择部分算子以挂载形式作用于 CANN 包不改变原始包内容生成的自定义算子包优先级高于原始 CANN 包aclnn 和图模式调用 AI Core、AI CPU 算子ops-math 包整个项目可完整替换CANN 包对应部分aclnn 和图模式调用 AI Core 算子ops-math 静态库整个项目编译为一个静态库文件含libcann_math_static.a和 aclnn 接口头文件可链接进应用仅支持 aclnn 调用 AI Core 算子三种形态的取舍建议若需要最小化部署、对软件包大小有要求或需要基于本项目进行二次发布建议采用静态库编译——该库可链接到应用开发程序仅保留业务所需的算子实现软件最小化部署若只需验证或上线个别算子优先使用自定义算子包单算子编译编译速度快、不影响原 CANN 包若需要整体替换 CANN 包中数学算子部分则编译 ops-math 包。安装第三方依赖ops-math 编译过程依赖以下第三方开源软件开源软件版本说明json3.11.3JSON 解析库makeself2.5.0自解压 run 包生成工具eigen5.0.0线性代数模板库protobuf25.1序列化协议库abseil-cpp20230802.1基础工具库opbasemaster算子基座库自 CANN 9.0.0 及以后版本需要下载cann-cmakemaster-049构建辅助 cmake 模块重要说明对于 CANNLab、Docker 和 Spack 环境默认联网编译过程中会自动下载第三方依赖无需手动安装可跳过本章操作。若编译环境可以访问网络请参考下文 联网编译编译脚本会自动联网下载第三方软件否则请参考 未联网编译 手动下载第三方软件。下载地址明细与版本要求保持一致——若从其他地址下载请确保版本号一致否则可能引入构建兼容性问题。联网编译在有互联网的环境下编译编译过程中会自动安装第三方依赖无需手动安装。以下按是否使用 Spack分两类场景说明。不使用 Spack 的场景自定义算子包1. 编译自定义算子包进入项目根目录执行如下编译命令bash build.sh --pkg --soc${soc_version} [--vendor_name${vendor_name}] [--ops${op_list}] [-j${n}] # 以Abs算子编译为例 # bash build.sh --pkg --socascend910b --opsabs -j16 # 编译experimental贡献目录下的用户算子以Abs算子为例编译时请以实际贡献算子为准 # bash build.sh --pkg --experimental --socascend910b --opsabs -j16参数说明--soc${soc_version}表示 NPU 型号。Atlas A2 训练系列产品/Atlas A2 推理系列产品使用ascend910b默认Atlas A3 训练系列产品/Atlas A3 推理系列产品使用ascend910_93Ascend 950PR/Ascend 950DT 产品使用ascend950--vendor_name可选${vendor_name}表示构建的自定义算子包名默认名为custom--ops可选${op_list}表示待编译算子不指定时默认编译所有算子格式形如abs,add_lora,...多算子之间用英文逗号,分隔--experimental可选表示编译用户保存在 experimental 贡献目录下的算子-j可选指定编译线程数加快编译速度。需要特别说明的是若${vendor_name}和${op_list}都不传入编译的是ops-math 包若编译所有算子的自定义算子包需传入${vendor_name}。当提示如下信息说明编译成功Self-extractable archive cann-ops-math-${vendor_name}_linux-${arch}.run successfully created.编译成功后run 包存放于项目根目录的build_out目录下。2. 安装自定义算子包./build_out/cann-ops-math-${vendor_name}_linux-${arch}.run自定义算子包默认安装路径为${ASCEND_HOME_PATH}/opp/vendors。其中${ASCEND_HOME_PATH}已通过环境变量配置表示 CANN toolkit 包安装路径一般为${install_path}/cann。从构建依赖的 cmake 配置 cmake/dependencies.cmake 可以印证编译定位 CANN 安装目录时优先读取$ASCEND_HOME_PATH环境变量未设置时 root 用户默认探测/usr/local/Ascend/ascend-toolkit/latest或/usr/local/Ascend/latest。说明可通过配置--install-path${install_path}参数定义算子包安装目录。在使用自定义算子包前需执行source ${install_path}/vendors/${vendor_name}/bin/set_env.bash命令。set_env.bash脚本会将自定义算子包安装路径追加到环境变量ASCEND_CUSTOM_OPP_PATH中使自定义算子包在当前环境中生效。3.可选卸载自定义算子包自定义算子包安装后在${ASCEND_HOME_PATH}/opp/vendors/${vendor_name}_math/scripts目录会生成uninstall.sh通过该脚本可卸载自定义算子包bash ${ASCEND_HOME_PATH}/opp/vendors/${vendor_name}_math/scripts/uninstall.shops-math 包说明全量编译会构建仓库内全部算子耗时较长与机器配置、-j并行度及是否联网下载第三方依赖有关日常开发请优先使用单算子编译--ops算子名。1. 编译 ops-math 包进入项目根目录执行如下编译命令# 编译除experimental目录外的所有算子 bash build.sh --pkg --soc${soc_version} [-j${n}] # 如bash build.sh --pkg --socascend910b -j16 # 编译experimental目录下的所有算子 # bash build.sh --pkg --experimental --soc${soc_version} [-j${n}]--soc${soc_version}表示 NPU 型号取值同上ascend910b默认 /ascend910_93/ascend950--experimental可选表示编译用户保存在 experimental 目录下的算子-j可选指定编译线程数加快编译速度。若提示如下信息说明编译成功Self-extractable archive cann-${soc_name}-ops-math_${cann_version}_linux-${arch}.run successfully created.${soc_name}表示 NPU 型号名称即${soc_version}删除 ascend 后剩余的内容例如ascend910b对应910b。编译成功后run 包存放于build_out目录下。2. 安装 ops-math 包# 安装命令 ./build_out/cann-${soc_name}-ops-math_${cann_version}_linux-${arch}.run --full --install-path${install_path}${install_path}表示指定安装路径需要与 toolkit 包安装在相同路径默认安装在/usr/local/Ascend目录。3.可选卸载 ops-math 包# 卸载命令 ./${install_path}/cann/share/info/ops_math/script/uninstall.shops-math 静态库说明静态库仅支持 Atlas A2、Atlas A3 系列产品。experimental 算子暂不支持使用静态库。1. 编译 ops-math 静态库进入项目根目录执行如下编译命令bash build.sh --pkg --static --soc${soc_version} [-j${n}]--soc${soc_version}表示 NPU 型号。Atlas A2 系列产品使用ascend910b默认Atlas A3 系列产品使用ascend910_93-j可选指定编译线程数加快编译速度。若提示如下信息说明编译并压缩成功[SUCCESS] Build static lib success! Successfully created compressed package: ${repo_path}/build_out/cann-${soc_name}-ops-math-static_${cann_version}_linux-${arch}.tar.gz${repo_path}表示项目根目录。编译成功后压缩包存放于build_out目录下。2. 解压 ops-math 静态库进入build_out目录执行解压命令tar -zxvf ./cann-${soc_name}-ops-math-static_${cann_version}_linux-${arch}.tar.gz -C ${static_lib_path}${static_lib_path}表示静态库解压路径。解压后目录结构如下├── cann-${soc_name}-ops-math-static_${cann_version}_linux-${arch} │ ├── lib64 │ │ ├── libcann_math_static.a # 静态库文件 │ └── include | ├── ... # aclnn接口头文件使用 Spack 的场景Spack 是一种高性能科学计算领域的包管理工具仓库在 spack 目录下提供了一键式环境准备脚本 prepare_cann_env.sh 及配套的 spack.yaml、repos.yaml 配置。该脚本会自动完成检查并安装 Git → 下载并安装 Spack v1.1.0 → 配置 Spack 仓库 → 下载 CANN Spack 包仓库 → 创建并激活名为cann-dev-env的 Spack 环境 → 设置当前目录为开发分支spack develop -p repo pkg→ 解析依赖spack concretize -f→ 安装spack install。更多细节可参考 Spack 快速安装指南。自定义算子包1. 编译自定义算子包进入项目根目录执行一键式脚本source prepare_cann_env.sh cann-ops-math{cann_version} pkg soc${soc_version} [vendor_name${vendor_name}] [ops${op_list}] [j${n}] # 以Abs算子编译为例 # source prepare_cann_env.sh cann-ops-mathmaster pkg socascend910b opsabs j16 # 编译experimental贡献目录下的用户算子以Abs算子为例编译时请以实际贡献算子为准 # source prepare_cann_env.sh cann-ops-mathmaster pkg experimental socascend910b opsabs j16参数说明soc${soc_version}表示 NPU 型号取值同前ascend910b默认 /ascend910_93/ascend950vendor_name可选${vendor_name}表示构建的自定义算子包名默认名为customops可选${op_list}表示待编译算子不指定时默认编译所有算子格式形如abs,add_lora,...多算子之间用英文逗号,分隔experimental可选表示编译用户保存在 experimental 贡献目录下的算子j可选指定编译线程数加快编译速度。同样地若${vendor_name}和${op_list}都不传入编译的是ops-math 包若编译所有算子的自定义算子包需传入${vendor_name}。当提示如下信息说明编译成功 cann-ops-math: Successfully installed cann-ops-math-master-xxxxxxxxxxxxxxxxx2. 查看产物位置spack location -i cann-ops-math此处产物指 run 包。实际上 run 包已自动安装到$ASCEND_HOME_PATH中在代码根目录下的build_out目录下亦可找到 run 包。3.可选卸载自定义算子包bash ${ASCEND_HOME_PATH}/opp/vendors/${vendor_name}_math/scripts/uninstall.shops-math 包说明全量编译会构建仓库内全部算子耗时较长与机器配置、j并行度及是否联网下载第三方依赖有关日常开发请优先使用单算子编译ops算子名。1. 编译 ops-math 包# 编译除experimental目录外的所有算子 source prepare_cann_env.sh cann-ops-math{cann_version} pkg soc${soc_version} [j${n}] # 编译experimental目录下的所有算子 # source prepare_cann_env.sh cann-ops-mathmaster pkg experimental socascend910b j16soc${soc_version}表示 NPU 型号取值同前experimental可选表示编译用户保存在 experimental 目录下的算子j可选指定编译线程数加快编译速度。若提示 cann-ops-math: Successfully installed cann-ops-math-master-xxxxxxxxxxxxxxxxx说明编译成功。2. 查看产物位置spack location -i cann-ops-math3.可选卸载 ops-math 包# 卸载命令 ./${install_path}/cann/share/info/ops_math/script/uninstall.shops-math 静态库说明静态库仅支持 Atlas A2、Atlas A3 系列产品。experimental 算子暂不支持使用静态库。1. 编译 ops-math 静态库source prepare_cann_env.sh cann-ops-math{cann_version} pkg static soc${soc_version} [j${n}]soc${soc_version}表示 NPU 型号。Atlas A2 系列产品使用ascend910b默认Atlas A3 系列产品使用ascend910_93j可选指定编译线程数加快编译速度。若提示 cann-ops-math: Successfully installed cann-ops-math-master-xxxxxxxxxxxxxxxxx说明编译并压缩成功。2. 查看产物位置spack location -i cann-ops-math此处产物指 tar 包在代码根目录下的build_out目录下亦可找到 tar 包。3. 解压 ops-math 静态库tar -zxvf ./cann-${soc_name}-ops-math-static_${cann_version}_linux-${arch}.tar.gz -C ${static_lib_path}解压后目录结构lib64/libcann_math_static.a静态库文件 include下 aclnn 接口头文件与不使用 Spack 场景一致。未联网编译若在没有连接互联网的环境下编译需要提前准备好依赖的第三方软件再进行源码编译。具体过程如下1. 下载第三方依赖在联网环境中提前下载第三方软件目前有如下两种方式请按需选择方式 1手动下载。根据上文 安装第三方依赖 的表格手动下载若从其他地址下载请确保版本号一致。方式 2脚本一键下载。通过 third_lib_download.py 脚本一键下载该脚本位于本项目scripts/tools/目录。下载该脚本并执行python ${scripts_dir}/third_lib_download.py${scripts_dir}表示脚本存放路径下载的第三方软件包默认存放在当前脚本所在目录。从脚本源码看它会依次下载 json、makeself、eigen、protobuf、abseil-cpp、cann-cmake 共 6 个压缩包并通过git clone获取 opbase 仓库任一失败都会以非零状态码退出并打印失败的地址清单便于离线转移前排查。2. 编译算子包将下载好的第三方软件上传至离线环境可存放在third_party目录或自定义目录下。推荐前者其编译命令与联网编译场景下的命令一致。third_party目录推荐在本项目根目录创建third_party目录若有则无需创建将第三方软件拷贝到该指定目录。此时编译命令与联网编译命令一致具体参考上文 联网编译。自定义目录在离线环境的任意位置新建${cann_3rd_lib_path}目录将第三方软件拷贝到该目录并确保该目录有权限访问mkdir -p ${cann_3rd_lib_path}此时编译命令需在联网编译命令基础上额外增加--cann_3rd_lib_path${cann_3rd_lib_path}用于指定第三方软件所在路径。假设存放路径为/path/cann_3rd_lib_path不同编译方式对应的命令如下自定义算子包bash build.sh --pkg --soc${soc_version} [--vendor_name${vendor_name}] [--ops${op_list}] --cann_3rd_lib_path${cann_3rd_lib_path} # 以Abs算子编译为例 # bash build.sh --pkg --socascend910b --opsabs -j16 --cann_3rd_lib_path/path/cann_3rd_lib_pathops-math 整包bash build.sh --pkg --soc${soc_version} --cann_3rd_lib_path${cann_3rd_lib_path} # bash build.sh --pkg --socascend910b --cann_3rd_lib_path/path/cann_3rd_lib_pathops-math 静态库bash build.sh --pkg --static --soc${soc_version} --cann_3rd_lib_path${cann_3rd_lib_path} # bash build.sh --pkg --static --socascend910b --cann_3rd_lib_path/path/cann_3rd_lib_path从参数解析实现 scripts/build_options.sh 可以看到--cann_3rd_lib_path会被realpath归一化为绝对路径后传入 cmake 阶段第三方依赖的默认安装路径为./third_party。3. 安装/卸载算子包未联网和联网场景下编译得到的算子包结果一样默认存放于项目根目录build_out目录下并且安装和卸载的操作命令也一样具体参见上文 联网编译。源码构建的底层流程理解构建脚本的内部流程有助于排查问题与扩展参数。从 build.sh 的main()函数可以看到一次完整的包构建会依次经历以下阶段checkopts $解析并校验命令行参数实现在 scripts/build_options.sh包括参数合法性检查与组合冲突检查。例如--opsop_list与--vendor_namename会置位ENABLE_CUSTOM自定义算子包模式--static只能与--pkg搭配使用--pkg不能与-u/--ophost/--opapi/--opgraph等测试类参数混用-j默认线程数为 8--build-type仅支持Release/Debug默认Release--ccache默认开启支持--gtest_filterpattern、--cov覆盖率、--noexec只编译不执行等测试扩展参数。assemble_cmake_args将解析结果组装为 cmake 命令行参数。clean_build_binarycmake_init清理旧构建产物并初始化 cmake 工程。按需执行build_lib构建 ophost/opapi/opgraph 等 host 侧动态库、build_binary编译 AI Core 内核二进制、build_static_lib静态库、build_package打 run 包。若指定-u则执行build_ut编译单元测试目标。其中 cmake 阶段的依赖定位可参考 cmake/dependencies.cmake优先使用ASCEND_HOME_PATH环境变量确定 CANN 安装目录依次find_package查找 dlog、securec、OPBASE、platform、metadef、runtime、nnopbase、tilingapi、aicpu 等 CANN 组件测试场景ENABLE_TEST下还会查找 tikicpulib。本地验证执行 UT 用例源码包部署后可通过项目根目录build.sh执行 UT 用例验证项目功能是否正常。说明执行 UT 用例依赖 googletest 单元测试框架详细介绍可参考 googletest 官方文档中Running a Subset of the Tests一节。# 安装根目录下test相关requirements.txt依赖 pip3 install -r tests/requirements.txt # 方式1: 编译并执行指定算子和对应功能的UT测试用例选其一 bash build.sh -u --[opapi|ophost|opkernel|opkernel_aicpu] --opsabs # 方式2: 编译并执行所有的UT测试用例 # bash build.sh -u # 方式3: 编译所有的UT测试用例但不执行 # bash build.sh -u --noexec # 方式4: 编译并执行对应功能的UT测试用例选其一 # bash build.sh -u --[opapi|ophost|opkernel|opkernel_aicpu] # 方式5: 编译对应功能的UT测试用例但不执行选其一 # bash build.sh -u --noexec --[opapi|ophost|opkernel|opkernel_aicpu] # 方式6: 执行UT测试用例时可指定soc编译 # bash build.sh -u --[opapi|ophost|opkernel|opkernel_aicpu] [--soc${soc_version}]UT 的粒度与算子目录结构一一对应--opapi验证 aclnn 接口层、--ophost验证算子原型与信息注册层、--opkernel验证 AI Core 内核、--opkernel_aicpu验证 AI CPU 内核。以验证 ophost 功能是否正常为例执行如下命令bash build.sh -u --ophost执行完成后出现如下内容表示执行成功Global Environment TearDown [] ${n} tests from ${m} test suites ran. (${x} ms total) [ PASSED ] ${n} tests. [100%] Built target math_op_host_ut${n}表示执行了 n 个用例${m}表示 m 项测试${x}表示执行用例消耗的时间单位毫秒。从 scripts/build_ut.sh 的build_ut实现可以看到脚本会依据UT_TARGETS如math_op_host_ut、math_op_api_ut、math_op_kernel_ut、math_aicpu_op_kernel_ut、math_op_graph_ut等依次调用cmake --build完成编译并支持--cov生成覆盖率generate_ops_cpp_cov目标。常见问题与注意事项自定义算子包不生效安装自定义算子包后需先执行source ${install_path}/vendors/${vendor_name}/bin/set_env.bash将安装路径追加到ASCEND_CUSTOM_OPP_PATH后再调用算子。全量编译耗时过长全量编译会构建仓库内全部算子耗时与机器配置、-j并行度及是否联网下载第三方依赖有关日常开发优先使用--ops算子名单算子编译。离线环境依赖版本漂移手动下载第三方软件时务必与表格版本号保持一致json 3.11.3、eigen 5.0.0、protobuf 25.1、abseil-cpp 20230802.1、makeself 2.5.0、cann-cmake master-049、opbase master。静态库适用范围静态库仅支持 Atlas A2、Atlas A3 系列产品experimental 算子暂不支持静态库编译。产物位置所有 run 包 / tar 压缩包默认生成于项目根目录build_out目录安装路径可通过--install-path自定义ops-math 包需与 toolkit 包同路径默认/usr/local/Ascend。Spack 环境持久化prepare_cann_env.sh会把 Spack 的setup-env.sh追加到~/.bashrc后续终端将自动加载如需清理全部 Spack 相关文件与配置可执行bash prepare_cann_env.sh clean。【免费下载链接】ops-math本项目是CANN提供的数学类基础计算算子库实现网络在NPU上加速计算。项目地址: https://gitcode.com/cann/ops-math创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考