Ultralytics YOLO 华为昇腾（Huawei Ascend）集成实战：CANN ATC 导出 .om 离线模型与 NPU 训练部署全指南

Ultralytics YOLO 在仓库中提供了对华为昇腾 AI 处理器的完整集成支持：既可以通过 torch_npu 在昇腾 NPU 上完成单卡/多卡训练，也可以借助华为 CANN 工具链中的 ATC（Ascend Tensor Compiler）把标准 ONNX 图编译为 .om 离线模型，最终在 Atlas 开发板与 OrangePi AIPro 等边缘设备上以低功耗运行推理。本文以仓库文档 docs/en/integrations/ascend.md 为主体，结合 导出器实现、ATC 转换封装 与 昇腾推理后端 源码，系统讲解环境安装、模型导出、参数含义、设备部署与底层原理，读完后你可以独立完成"训练 → 导出 .om → 设备端推理"的完整链路。

什么是华为昇腾与 CANN

华为昇腾（Ascend）是一族 AI 处理器，与它配套的是 CANN（Compute Architecture for Neural Networks，异构计算架构）。CANN 生态内包含 ATC（Ascend Tensor Compiler）——一个运行在宿主机上的编译工具，负责把标准 ONNX 图转换为针对昇腾 AI Core 的、与具体硬件绑定的 .om 离线模型。

一个关键特性是 ATC 完全在宿主机侧运行：你可以在没有任何昇腾硬件挂载的普通 x86-64 或 ARM64 Linux 机器上完成模型编译，再把产物 .om 拷贝到目标设备执行推理。这意味着导出动作可以无缝放进 CI 流水线、容器镜像或开发者的笔记本中，而硬件资源只需在部署阶段投入。

在仓库的导出流程中，ascend 还有几个别名：当 format 被设置为 huawei、cann 或 om 时，会统一归一化为 ascend，见 ultralytics/engine/exporter.py#L584-L585。

在昇腾 NPU 上训练 Ultralytics YOLO

Ultralytics 通过 torch_npu 支持昇腾 NPU 上的单卡与多卡训练，并完整覆盖 AMP 混合精度、验证（validation）、断点续训（checkpointing / resume）以及 AutoBatch 自动批大小选择能力。

• 选择单张 NPU：device=npu:0
• 选择多张 NPU：device=npu:0,1，分布式训练底层通过 HCCL（Huawei Collective Communication Library）完成集合通信

训练前需要先安装与硬件匹配的 CANN、PyTorch 与 torch_npu 版本，并确保已 source 昇腾环境变量脚本。更详细的安装与使用示例可参见训练模式文档 docs/en/modes/train.md。

Ascend 导出格式概览

Ultralytics 的昇腾导出遵循一条 ONNX-first 的链路：

1. 导出器首先调用标准的 ONNX 导出流程写出一个中间 ONNX 图（即标准的 Ultralytics ONNX 导出 产物，无任何私有中间格式）；
2. 随后调用 ATC，把该 ONNX 图针对你通过 name 参数指定的 SoC（System-on-Chip）编译为 .om 二进制；
3. 最终产出一个自包含的模型目录，其中存放 .om 文件以及携带类别、输入尺寸、任务类型等信息的 Ultralytics 元数据。

从源码看，这一步由 export_ascend 方法编排：在 ultralytics/engine/exporter.py#L1565-L1582，导出器会先 _check_atc() 确认工具链在 PATH 上（避免缺工具时白白先跑一次完整 ONNX 导出），再把 ONNX opset 强制收敛到 CANN 解析器可接受的上限 17，然后调用 onnx2ascend 完成编译。

Ascend 模型的关键特性

• 专用 AI Core 执行：编译后的模型运行在昇腾 AI Core 上而非宿主 CPU，为实时摄像头流水线提供显著更高的吞吐。
• 宿主机侧编译：ATC 无需挂载 NPU，导出可在 CI、容器或笔记本电脑上执行。
• ONNX 优先：标准 Ultralytics ONNX 导出可直接喂给 CANN 工具链，无需私有中间格式。
• 静态输入形状：输入形状在编译期就被烘焙进 .om，运行期不再有形状协商的开销。
• 多设备目标：同一份 ONNX 图只需修改 name，即可为任意受支持的 SoC 重新编译。

支持的任务范围

昇腾导出覆盖 Ultralytics 的全部七类任务。其中 语义分割（Semantic）与深度估计（Depth）仅在 YOLO26 上可用——YOLO26 是当前仓库中唯一内置这两类检测头的模型家族，这一点也可以从任务支持宏 docs/macros/supported-tasks.md 的表格结构中看出：Detect / Segment / Classify / Pose / OBB 对 YOLOv8、YOLO11、YOLO26 均可用，而 Semantic 与 Depth 只出现在 YOLO26 列。各任务详细说明见 docs/en/tasks/detect.md、docs/en/tasks/segment.md 等任务文档。

支持的昇腾设备（SoC 目标）

通过 name 参数传入目标 SoC，ATC 会以 --soc_version 的形式将其烘焙进 .om，因此该值必须与最终部署的板卡严格一致。在本地，你可以编译任何你的 CANN 安装提供了算子内核的 SoC。以下是文档验证过的四个目标及其对应设备：

name	对应设备	本地导出	Ultralytics 平台
Ascend310P3	Atlas 300I Pro、Atlas 300V Pro	✅	✅
Ascend310P1	Atlas 300I	✅	✅
Ascend310B4	OrangePi AIPro 20T、Atlas 200I A2	✅	✅
Ascend310B1	OrangePi AIPro 8T	✅	✅

从源码实现看，导出器对 name 只做前缀合法性校验（必须 Ascend 开头），不做 SoC 白名单限制——因为合法取值完全取决于你机器上安装了哪些 Ascend-cann-kernels-* 内核包，硬编码名单反而会误伤有效目标，未知 SoC 由 ATC 自行报错（见 ultralytics/engine/exporter.py#L746-L759）。

导出到 Ascend：把 YOLO 模型编译为 .om

环境与安装

昇腾导出依赖 CANN 工具包，而它仅支持 Linux。编译前必须确保 atc 编译器位于 PATH 上——先 source 昇腾环境脚本，例如：

source /usr/local/Ascend/ascend-toolkit/set_env.sh

随后安装 Ultralytics 本体：

pip install ultralytics

CANN 工具包由华为单独分发，不会被自动安装。你需要从昇腾社区下载页获取与目标 SoC 匹配的版本，或直接使用官方提供的 ascendai/cann 容器镜像（容器内已捆绑 ATC 及其依赖）。

重要警告：工具包必须匹配目标 SoC。 ATC 只能编译其已安装算子内核的 SoC 家族。若工具包只携带 ascend310p 内核，却要求导出 Ascend310B4 目标，编译会以 No supported Ops kernel and engine are found for ... Conv2D 之类的错误失败。请为部署设备安装对应的 Ascend-cann-kernels-<soc> 内核包。

使用方式

昇腾格式完整支持 Export / Predict / Validate 三种模式（见 docs/en/modes/export.md、docs/en/modes/predict.md、docs/en/modes/val.md)）。推理与验证运行在昇腾硬件上。先导出模型，再加载导出产物执行推理或精度校验。

Python 方式：

from ultralytics import YOLO

# 加载一个 YOLO26 模型
model = YOLO("yolo26n.pt")

# 为 Atlas 200I / OrangePi AIPro 板卡导出为昇腾格式
model.export(format="ascend", name="Ascend310B4")

# 加载导出的昇腾模型并在设备上执行推理（source 参数可指向本地图片/视频路径）
ascend_model = YOLO("yolo26n_ascend_model")
results = ascend_model("path/to/image.jpg")

CLI 方式：

# 把 YOLO26n PyTorch 模型导出为昇腾格式
yolo export model=yolo26n.pt format=ascend name=Ascend310B4

# 用导出的模型在设备上执行推理
yolo predict model=yolo26n_ascend_model source='path/to/image.jpg'

导出参数详解

参数	类型	默认值	说明
format	str	'ascend'	导出目标格式，决定与昇腾 AI 处理器的兼容性。
name	str	'Ascend310B4'	目标 SoC，作为 --soc_version 传给 ATC，例如 Ascend310P3。只要你的 CANN 装了对应内核即为合法值（见上文设备表）。必须与部署设备一致。
imgsz	int 或 tuple	640	模型输入图像尺寸，以静态形状的形式烘焙进 .om。
batch	int	1	编译进离线模型的静态批大小。
quantize	int	16	量化精度。昇腾导出仅支持 FP16，未指定时自动启用 16。它取代了已废弃的 half / int8 标志。
opset	int	17	中间 ONNX 图的算子集版本。上限为 17——这是 CANN ONNX 解析器支持的最高版本。
simplify	bool	True	用 onnxslim 对中间 ONNX 图做简化。
nms	bool	False	为受支持的检测、分割、姿态与 OBB 模型附加非极大值抑制（NMS）。

为什么 FP32 不可用？

昇腾 AI Core 的卷积算子只接受 DT_FLOAT16 与 DT_INT8 输入，因此 FP32 离线模型在硬件上根本无法执行。导出器因而默认以 --precision_mode=force_fp16 编译（见 ultralytics/utils/export/ascend.py#L61），当 quantize 未指定时自动置为 16（见 ultralytics/engine/exporter.py#L760-L761）。如果你显式请求 quantize=32，导出器会直接报错，而不是默默产出一个无法运行的模型——ascend 位于导出器维护的 FP32 不支持格式集合中（见 ultralytics/engine/exporter.py#L437）。

ATC 底层命令解析

onnx2ascend（见 ultralytics/utils/export/ascend.py#L24-L71）把导出参数组装成一条完整的 ATC 命令，值得逐项理解：

atc
  --model=<onnx文件绝对路径>            # 输入 ONNX 模型
  --framework=5                         # 框架标识，5 = ONNX
  --output=<目录>/<模型名>_<SoC名>       # ATC 自动追加 .om 后缀
  --input_format=NCHW
  --input_shape=images:<batch>,<channels>,<height>,<width>
  --soc_version=<name>                  # 目标 SoC
  --precision_mode=force_fp16           # 强制 FP16

实现细节上还有两点值得注意：命令以 argv 列表形式通过 subprocess.run 执行而不是拼 shell 字符串，避免路径中的元字符问题；ATC 会在其当前工作目录遗留 kernel_meta/ 与 fusion_result.json 等中间产物，因此导出器在临时目录（tempfile.TemporaryDirectory）中运行 ATC，确保仓库与输出目录干净。批大小、通道数、输入尺寸分别来自导出参数的 batch、channels 与 imgsz——其中通道数取自导出时输入张量的实际形状。

输出目录结构

导出成功后会在模型旁生成一个自包含目录：

yolo26n_ascend_model/
├── yolo26n_Ascend310B4.om  # 编译后的昇腾离线模型（AI Core 可执行产物）
└── metadata.yaml           # 模型元数据（类别、图像尺寸、任务类型等）

.om 文件是 CANN 运行时在设备上加载执行的编译产物，其文件名携带目标 SoC，使产物具备自描述性。需要注意两点约定：每个目录内只保留一个 .om——推理时加载器会取目录中唯一找到的那个模型；metadata.yaml 中的类别名、图像尺寸等信息会被 Ultralytics 推理管线读取使用。

部署导出的 YOLO 昇腾模型

运行时安装（设备侧）

设备端推理需要两部分组件：CANN 运行时，以及 ais_bench Python 包——它封装了 CANN 的 pyACL 绑定。在已安装并 source 好 CANN 的昇腾设备上，需要从华为昇腾 tools 仓库获取 ais-bench 工具源码，进入 ais-bench_workload/tool/ais_bench 目录，依次构建并安装其 backend 子包（产出 aclruntime-*.whl）与主包（产出 ais_bench-*.whl）。

# 在昇腾设备上、CANN 已安装并 source 的前提下
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 获取 ais_bench 源码并按官方说明构建 wheel，随后安装 aclruntime 与 ais_bench 两个 wheel

安装完成后，把导出的 yolo26n_ascend_model 目录整体拷贝到设备，之后即可像使用任何其他 Ultralytics 格式一样直接加载推理。

设备端推理的底层加载逻辑

推理侧的载体是 AscendBackend 类（见 ultralytics/nn/backends/ascend.py#L15-L66）。加载时它会：

1. 尝试 from ais_bench.infer.interface import InferSession 导入运行时，若 ais_bench 未安装则抛出带指引的 ImportError；
2. 在传入的模型目录中用 w.rglob("*.om") 递归查找唯一的 .om 文件，找不到则抛出 FileNotFoundError；
3. 以设备序号与 .om 路径创建 InferSession，再通过 read_metadata / apply_metadata 把 metadata.yaml 的类别与输入信息应用到推理管线；
4. forward 阶段把输入张量转移到 CPU 转成 numpy 数组后交给会话的 infer 执行，返回单数组或多输出数组。

此外 AscendBackend 还实现了析构钩子，会话析构时调用 free_resource() 释放设备端资源。

推荐工作流

1. 训练：使用 Ultralytics 的 训练模式 训练你的模型，或直接从一个预训练检查点开始。
2. 导出：在任何装有 CANN 的 Linux 宿主机上执行昇腾导出，name 传入与目标 SoC 匹配的值。
3. 拷贝：把导出的模型目录（含 .om 与 metadata.yaml）复制到昇腾设备。
4. 部署：在设备上安装 CANN 运行时与 ais_bench，加载模型做端侧推理。

典型应用场景

运行在昇腾硬件上的 YOLO 模型适用于广泛的嵌入式与工业视觉场景：

• 工业自动化：生产线上的高速质检与缺陷检测。
• 智能安防监控：边缘网关上的实时多摄像头目标检测，无需依赖中心服务器。
• 机器人：自主移动机器人与协作机械臂的车载感知。
• 智慧城市：低功耗路边单元上的交通监控与行人分析。

总结

本指南完整覆盖了两条主线：如何在华为昇腾 NPU 上借助 torch_npu 训练 Ultralytics YOLO，以及如何用 CANN ATC 编译器把模型导出为昇腾 .om 格式。导出全程在宿主机执行、产出自包含模型目录，并可通过单一的 name 参数为任意受支持的昇腾 SoC 编译。结合仓库源码可以看到，整条链路（ONNX 中间图 → ATC 编译 → 目录化产物 → AscendBackend 设备端推理）结构清晰、可 CI 化，是边缘部署 YOLO 模型的一条低功耗工程路径。其他集成方案可继续查阅 集成指南首页。

FAQ

如何把 Ultralytics YOLO 模型导出为昇腾格式？

安装 Ultralytics 与 CANN 工具包，source CANN 环境使 atc 出现在 PATH 上，然后用 model.export(format="ascend", name="Ascend310B4")（Python）或 yolo export model=yolo26n.pt format=ascend name=Ascend310B4（CLI）导出。name 需设置为你部署设备的 SoC。

导出模型必须有昇腾硬件吗？

不需要。ATC 编译器完全运行在宿主机，在无 NPU 挂载的标准 x86-64 或 ARM64 Linux 机器上即可完成编译。你只在用导出的 .om 跑推理时需要昇腾硬件。

导出为何报 "No supported Ops kernel and engine are found"？

你的 CANN 安装不包含所请求 SoC 的算子内核。每个工具包只捆绑特定 SoC 家族的内核，请安装与目标匹配的 Ascend-cann-kernels-<soc> 包，或改用面向该设备家族的容器镜像。

为什么昇腾导出只支持 FP16？

昇腾 AI Core 的卷积只接受 DT_FLOAT16 与 DT_INT8 张量，FP32 离线模型在硬件上无法执行。因此导出器以 --precision_mode=force_fp16 编译，并会拒绝显式的 quantize=32 请求。

支持哪些昇腾设备？

任何你的 CANN 工具包提供了内核的 SoC 都可通过 name 参数选择。文档验证的四个目标是 Ascend310P3（Atlas 300I Pro / 300V Pro）、Ascend310P1（Atlas 300I）、Ascend310B4（OrangePi AIPro 20T / Atlas 200I A2）与 Ascend310B1（OrangePi AIPro 8T）。