2026年4月3日

YOLO 昇腾 NPU 训练与推理完整指南

什么是 YOLO

YOLO（You Only Look Once）是一种实时目标检测算法，通过单次前向传播同时预测图像中所有目标的位置和类别。Ultralytics 是目前最流行的 YOLO 实现框架，支持检测、分割、分类、姿态估计等任务。

本文介绍如何在华为昇腾 NPU（Ascend 910B）上完成 YOLO 的训练和推理全流程，包括：

昇腾 NPU 适配
使用预构建镜像快速启动
模型训练（单卡 / 多卡 DDP）
模型导出与转换（PyTorch → ONNX → OM）
推理服务部署

昇腾 NPU 适配

Ultralytics 官方不支持昇腾 NPU，需要进行代码适配。我们维护了一个适配分支：

仓库：xuopoj/ultralytics (ascend 分支)
迁移文档：migration_npu.md

适配环境

组件	版本
芯片	Ascend 910B4
CANN	8.3.RC1
torch_npu	2.5.1
Python	3.10

主要适配内容

模块	修改	说明
DDP 分布式	HCCL 替代 NCCL	昇腾使用 HCCL 作为集合通信后端
GradScaler	回退到 CPU	NPU 不支持 GradScaler，AMP 自动禁用
显存管理	NPU 专用 API	`empty_cache()` 和 `memory_reserved()` 适配
随机种子	NPU manual_seed	NPU 随机数生成器初始化
时间同步	NPU synchronize	性能计时准确性
Autocast	NPU 支持	`torch.autocast` 设备类型适配
DataLoader	workers=0	NPU 上自动设为 0
设备选择	npu 格式支持	支持 `npu`、`npu:0`、`npu:0,npu:1` 格式

核心修改文件：trainer.py、torch_utils.py、validator.py、autobatch.py

预构建镜像

我们提供了开箱即用的 Docker 镜像，无需手动适配环境。

训练镜像

镜像内已安装适配版 Ultralytics（可编辑模式）、ONNX 工具链和 TensorBoard。

镜像	PyTorch	CANN	状态
`quay.io/service-delivery-hub/yolo-ascend:latest-torch251-cann83rc1-910b`	2.5.1	8.3RC1	推荐
`quay.io/service-delivery-hub/yolo-ascend:latest-torch290-cann850-910b`	2.9.0	8.5.0	实验性

详情：Ascend Image Hub - yolo-ascend

推理镜像

基于 FastAPI 的 OM 模型推理服务器，内置 YOLO 前后处理。

镜像	芯片	CANN
`quay.io/service-delivery-hub/om-serve:latest-cann83rc1-910b`	910B	8.3RC1
`quay.io/service-delivery-hub/om-serve:latest-cann83rc1-310p`	310P	8.3RC1

详情：Ascend Image Hub - yolo-detect

拉取镜像

# 训练镜像
docker pull quay.io/service-delivery-hub/yolo-ascend:latest-torch251-cann83rc1-910b

# 推理镜像
docker pull quay.io/service-delivery-hub/om-serve:latest-cann83rc1-910b

训练

准备数据集

以 VOC2012 为例，数据集目录结构：

<dataset_path>/
  VOC2012/
    Annotations/       # XML 标注文件
    ImageSets/Main/    # train.txt、val.txt
    JPEGImages/        # .jpg 图片
  images/
    train2012/         # 首次运行后自动填充
    val2012/
  labels/
    train2012/         # 首次运行后自动生成 YOLO .txt 标注
    val2012/

创建数据集配置文件 my_data.yaml：

path: /path/to/datasets
train: images/train2012
val: images/val2012

names:
  0: aeroplane
  1: bicycle
  2: bird
  # ... 定义所有类别

镜像内包含 VOC 数据集配置模板，位于 ~/xuopoj/ultralytics/tasks/voc/，首次运行会自动将 VOC XML 标注转换为 YOLO 格式。

启动训练任务

参考基本的MA训练任务创建。

单卡训练

yolo train model=yolo11n.pt data=/data/my_data.yaml device=npu:0 epochs=100 batch=8 imgsz=640

或使用配置文件：

yolo train cfg=tasks/voc/voc_detect.yaml data=tasks/voc/voc_data.yaml device=npu:0

多卡 DDP 训练

yolo train model=yolo11n.pt data=/data/my_data.yaml device=npu:0,npu:1 epochs=100 batch=16

重要：不要手动调用 torchrun，Ultralytics 会自动处理 DDP 启动。

NPU 训练注意事项

AMP 自动禁用（NPU 不支持 GradScaler）
workers 自动设为 0
DDP 使用 HCCL 后端（非 NCCL）
设备格式必须为 npu:0,npu:1（不能省略编号）

监控训练

# 启用 TensorBoard（镜像内已默认启用）
yolo settings tensorboard=True

# 查看训练曲线
tensorboard --logdir runs/detect --port 6006

训练输出

runs/detect/exp/
  weights/best.pt    # 最优模型（按 val mAP）
  weights/last.pt    # 最新检查点
  args.yaml          # 完整配置快照
  results.csv        # 逐 epoch 指标

验证

yolo val model=runs/detect/exp/weights/best.pt data=/data/my_data.yaml device=npu:0

模型导出与转换

训练完成后，需要将模型转换为昇腾 OM 格式以获得最佳推理性能。

第一步：导出 ONNX

yolo export model=runs/detect/exp/weights/best.pt format=onnx opset=12 simplify=True
# 输出：runs/detect/exp/weights/best.onnx

第二步：ONNX → OM

使用 CANN Toolkit 中的 atc 工具转换，根据目标芯片选择 --soc_version：

# Ascend 910B4（训练卡，ModelArts 默认）
atc --model=best.onnx \
    --framework=5 \
    --output=best_910b4 \
    --soc_version=Ascend910B4 \
    --input_shape="images:1,3,640,640" \
    --log=error

# Ascend 310P（推理卡，Atlas 300I/500）
atc --model=best.onnx \
    --framework=5 \
    --output=best_310p \
    --soc_version=Ascend310P3 \
    --input_shape="images:1,3,640,640" \
    --log=error

输出为 .om 文件。--input_shape 中的名称 images 需与 ONNX 模型输入节点名一致，可用 Netron 查看确认。

推理部署

启动 YOLO 推理服务

参考MA模型在线服务。

环境变量

变量	说明	默认值
`MODEL_PATH`	OM 模型文件路径	必填
`INPUT_SHAPE`	模型输入形状	`1,3,640,640`
`DEVICE_ID`	昇腾设备 ID	`0`
`CLASSES`	逗号分隔的类别名称	必填

调用推理接口

# 健康检查
curl http://localhost:8000/health

# 推理
curl -X POST http://localhost:8000/infer \
  -F "image=@photo.jpg"

# 自定义置信度和 IoU 阈值
curl -X POST "http://localhost:8000/infer?conf=0.5&iou=0.4" \
  -F "image=@photo.jpg"

响应格式

{
  "detections": [
    {
      "label": "person",
      "class_id": 14,
      "confidence": 0.87,
      "box": { "x1": 120.0, "y1": 45.0, "x2": 280.0, "y2": 390.0 }
    }
  ],
  "count": 1
}

完整流程总结

准备数据集 → 拉取训练镜像 → NPU 训练 → 导出 ONNX → atc 转换 OM → 拉取推理镜像 → 部署服务