CANN ATC 模型转换指南cann-recipes-harmony-infer 端侧推理离线模型生成实战【免费下载链接】cann-recipes-harmony-infer本项目为鸿蒙开发者提供基于CANN平台的业务实践案例方便开发者参考实现端云能力迁移及端侧推理部署。项目地址: https://gitcode.com/cann/cann-recipes-harmony-inferATCAscend Tensor Compiler是异构计算架构 CANN 体系下的模型转换工具它能够将开源框架的网络模型如 ONNX、MindSpore 导出的 AIR 模型以及基于 Ascend IR 定义的单算子描述文件JSON 格式统一转换为昇腾、麒麟 AI 处理器支持的离线模型格式om/omc。在 cann-recipes-harmony-infer 项目中ATC 是连接「自定义算子/ONNX 模型开发」与「鸿蒙端侧 NPU 推理」的关键桥梁无论是ops/ascendc目录下的自定义算子验证还是 Soble 端侧推理示例 中图片滤波识别的 NPU 加速都依赖 ATC 先生成离线模型。读完本文你将掌握 ATC 工具的环境准备、三类典型转换场景ONNX 模型、AIR 模型、单算子描述文件的完整命令用法以及核心参数的取值含义与仓库内的真实应用佐证。ATC 工具简介ATC 的核心职责是离线编译它把训练框架产出的网络模型或 Ascend IR 单算子描述在 PC 侧提前编译成适配特定 AI 处理器型号的离线模型文件端侧应用运行时无需再做模型解析与图优化直接加载离线模型即可执行推理。在鸿蒙端侧推理场景中这一环节尤其重要。以仓库中的 Soble 示例 为例工程说明中明确指出「使用 DevEco 构建应用前请将ATC 转换后的 omc 模型文件放置到应用entry/src/main/resources/rawfile目录下再进行应用构建和安装」。也就是说ATC 转换产物是端侧应用打包的必要输入转换结果直接决定了端侧推理能否运行。环境准备安装开发套件参见 环境准备 完成环境搭建核心步骤为下载对应版本的鸿蒙社区版 CANN 开发套件包Ascend-cann-toolkit_${cann_version}_linux-${arch}-mobile-station.run执行安装命令chmod x Ascend-cann-toolkit_${cann_version}_linux-${arch}-mobile-station.run ./Ascend-cann-toolkit_${cann_version}_linux-${arch}-mobile-station.run --install --force --install-path${install_path}其中${cann_version}表示 CANN 包版本号${arch}表示 CPU 架构如 aarch64、x86_64${install_path}表示指定安装路径默认安装在/usr/local/Ascend目录。安装完成后该场景下ATC 工具位于${install_path}/cann/bin目录下。以 root 安装为例安装目录为/usr/local/Ascend/ascend-toolkit。仓库中自定义算子的构建脚本如 build_and_install.sh也默认在ASCEND_HOME_PATH未设置时回退到/usr/local/Ascend/cann并加载setenv.bash可见该路径是 CANN 环境的默认约定。配置环境变量安装 CANN 软件后使用 CANN 运行用户进行编译、运行时需要以 CANN 运行用户登录环境执行如下环境变量# 默认路径安装以root用户为例非root用户将/usr/local替换为${HOME} source /usr/local/Ascend/cann-${cann_version}/set_env.sh # 指定路径安装 # source ${install_path}/cann-${cann_version}/set_env.sh执行后atc命令即进入 PATH。需要说明的是${cann_version}需替换为实际安装的 CANN 版本号目录名。模型转换实战以下三类转换场景覆盖了仓库中从算子验证到端侧部署的全部模型来源。ONNX 网络模型转换成离线模型ONNX 是仓库自定义算子工程输出网络模型的默认格式。例如 add_custom 自定义算子工程 通过onnx.helper.make_node(AddCustom, ...)构造包含自定义算子节点的 ONNX 模型sobel_custom 工程 则构造包含SobelCustom算子的 ONNX 模型输入UINT8类型、shape 为[1, 763, 1024, 3]。这些 ONNX 文件正是通过 ATC 转换成离线模型后参与端侧验证的。将 ONNX 网络模型转换为离线模型的命令atc --model$HOME/module/resnet50*.onnx --framework5 --output$HOME/module/out/onnx_resnet50 --soc_versionsoc_version参数说明--modelResnet50 网络模型文件所在路径。--framework原始框架类型5 表示 ONNX。--output生成的离线模型路径。--soc_versionKirin AI 处理器的型号如KirinX90、Kirin9030等。仓库中 AddKernelInvocation 样例的 run.sh 对soc_version的取值有直接约束脚本内置VersionMap仅接受KirinX90与Kirin9030两个取值若传入其他值会报错ERROR: SOC_VERSION should be in [...]并在后续以该值指定-DASCEND_PRODUCT_TYPE参与编译。这印证了上述--soc_version取值在该项目中的实际可用范围。*.air 格式的模型文件转换成离线模型*.air为 Ascend Intermediate Representation 格式的模型文件由 MindSpore 等框架导出转换为离线模型的命令atc --model$HOME/module/ResNet50.air --framework1 --output$HOME/module/out/ResNet50_air --soc_versionsoc_version参数说明--model*.air格式的模型文件所在路径。--framework原始框架类型1 表示*.air格式的模型文件。--output生成的离线模型路径。--soc_versionKirin AI 处理器的型号如KirinX90、Kirin9030等。注意与 ONNX 场景的区别仅在于--framework的取值其余参数语义完全一致。单算子描述文件转换成离线模型单算子描述文件是基于 Ascend IR 定义的单个算子的定义文件包括算子的输入、输出及属性等信息。借助该文件转换成适配昇腾、麒麟 AI 处理器的离线模型后可以脱离完整网络模型单独验证单算子的功能这也是自定义算子开发调试阶段常用的验证手段。转换命令atc --singleop$HOME/singleop/add.json --output$HOME/singleop/out/op_model --soc_versionsoc_version参数说明--singleop用于指定add.json单算子描述文件。--output转换后的离线模型存放路径。--soc_versionKirin AI 处理器的型号如KirinX90、Kirin9030等。从仓库结构看ops/ascendc下每个自定义算子工程均包含op_host算子宿主侧实现与 tiling与op_kernel算子核函数实现并配套 build_and_install.sh 编译生成custom_opp_${OS_ID}_${arch}.run算子包安装到 CANN 环境。算子包安装成功后ATC 才能正确识别自定义算子进而支持将包含这些算子的 ONNX 模型如上述SobelCustom.onnx或单算子描述文件转换为离线模型。转换产物在端侧推理中的应用转换得到的离线模型在鸿蒙端侧通过 CANN 提供的 HiAI Foundation 与 NNCore 接口加载执行。以 Soble 示例 为例其端侧推理链路为将 ATC 转换后的SobelCustom.omc模型放入应用entry/src/main/resources/rawfile目录应用启动后通过OH_NNCompilation_ConstructWithOfflineModelBuffer(const void* modelBuffer, size_t modelSize)直接基于离线模型 buffer 构建编译对象通过OH_NNCompilation_SetDevice、OH_NNCompilation_Build完成设备绑定与编译再由OH_NNExecutor_Construct创建执行器通过OH_NNExecutor_RunSync同步执行推理将滤波识别结果与耗时展示到界面。该链路说明--soc_version必须与端侧实际搭载的 Kirin AI 处理器型号严格一致否则离线模型无法在目标设备上加载执行。ATC 核心参数详解下表完整列出 ATC 工具的主要参数摘自 docs/atc_tools_guide.md 附录并补充了仓库实践中的补充说明ATC 参数名称参数简述是否必选默认值--help或--h显示帮助信息。否不涉及--model原始模型文件路径与文件名。是不涉及--framework原始框架类型。是不涉及--input_format输入数据格式。否Caffe、MindSpore、ONNX 默认为 NCHWTensorFlow 默认为 NHWC--input_shape模型输入数据的 shape。否不涉及--singleop单算子定义文件将单个算子 JSON 文件转换成适配昇腾 AI 处理器的离线模型。否不涉及--output如果是开源框架的网络模型存放转换后的离线模型的路径以及文件名如果是单算子描述文件存放转换后的单算子模型的路径。是不涉及--output_type指定网络输出数据类型或指定某个输出节点的输出类型。否不涉及--soc_version模型转换时指定芯片版本。是不涉及--core_type设置网络模型使用的 Core 类型若网络模型中包括 Cube 算子则只能使用 AiCore。否AiCore--out_nodes指定输出节点。否不涉及--external_weight生成 om 离线模型时是否将原始网络中的 Const/Constant 节点的权重保存在单独的文件中同时将节点类型转换为 FileConstant 类型。否0--precision_mode设置网络模型的精度模式。否force_fp16--precision_mode_v2设置网络模型的精度模式。与--precision_mode不能同时使用推荐使用--precision_mode_v2。否fp16--log设置 ATC 模型转换过程中显示日志的级别。否null关键参数的仓库实践注记--soc_version必选从 run.sh 的VersionMap定义可见本项目支持KirinX90与Kirin9030两种型号且二者均强制使用CORE_TYPEAiCore对应--core_type的默认值 AiCore。该型号还影响运行模式KirinX90/Kirin9030不支持 CPU 仿真分支脚本中明确提示Kirin Soc Currently not support cpu!只支持simNPU 仿真与npu模式。--framework必选仓库中实际使用到的是 5ONNX与 1AIR对应 create_onnx.py 生成的*.onnx模型文件。转换前请先通过build_and_install.sh完成自定义算子包安装否则 ATC 无法识别模型中的自定义算子节点。--input_format/--input_shape对于动态 shape 的模型可在转换时通过--input_shape固定输入维度端侧推理时输入张量的 shape 必须与转换时设定一致。Soble 示例中SobelCustom.onnx的输入为[1, 763, 1024, 3]输出为[1, 1, 761, 1022]转换时若指定--input_shape应与此保持一致。--precision_mode_v2默认 fp16默认以 fp16 精度完成转换可在精度与性能之间权衡若网络中存在精度敏感层可通过--precision_mode_v2调整为fp32等模式。需要注意该参数与--precision_mode互斥官方推荐使用--precision_mode_v2。--log默认 null设置转换过程日志级别用于排查转换失败时的问题定位转换异常时可结合日志中报错的算子信息回到op_host/op_kernel侧修正实现。常见问题与注意事项soc_version必须与端侧芯片一致离线模型与芯片型号强绑定--soc_version与设备实际处理器型号不匹配将导致模型无法加载。本项目以KirinX90、Kirin9030为基准参见 AddKernelInvocation/run.sh。自定义算子需先安装算子包包含自定义算子的模型在转换前必须通过对应工程如 sobel_custom、add_custom的build_and_install.sh生成并安装custom_opp_${OS_ID}_${arch}.run算子包否则 ATC 会因无法识别算子而报错。端侧模型文件名与放置目录转换后的离线模型如.omc需放入鸿蒙应用entry/src/main/resources/rawfile目录后再构建应用参见 Soble 示例说明。含 Cube 算子的网络必须使用 AiCore--core_type默认即为 AiCore一般无需显式指定若网络仅包含矢量算子可评估其他 Core 类型的收益。精度模式选型默认 fp16 转换可获得较好性能但对精度敏感的网络建议先使用默认精度验证结果再逐步放宽避免端侧推理结果偏差。参考与延伸阅读环境准备与依赖安装toolkit 安装、install_deps.sh依赖安装与环境变量配置的完整步骤。AscendC 自定义算子开发指南理解op_host/op_kernel结构与算子包构建流程。AddKernelInvocation 算子调用样例演示自定义算子从编译到 NPU 仿真/运行验证的完整闭环其中main.cpp展示了aclInit、流创建、数据搬运与核函数调用的完整流程。Soble 端侧推理示例ATC 转换产物在鸿蒙应用中的加载与执行方式。自定义算子工程 create_onnx.py 与 sobel_custom 的 create_onnx.py构造待转换 ONNX 模型的参考实现。【免费下载链接】cann-recipes-harmony-infer本项目为鸿蒙开发者提供基于CANN平台的业务实践案例方便开发者参考实现端云能力迁移及端侧推理部署。项目地址: https://gitcode.com/cann/cann-recipes-harmony-infer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考