YOLOv10s — 昇腾 Ascend NPU 适配版

本文档记录 YOLOv10s 在华为昇腾 NPU 上的全流程适配、推理优化与精度验证。整体适配路径为：

PyTorch (Ultralytics) → ONNX → onnx2torch → torch_npu → NPU

本仓库完成端到端目标检测 NPU 适配，修复了 YOLOv10 导出 ONNX 模型与 onnx2torch 的兼容性问题，精度无损，单模型实现 51.3× 加速（vs CPU 基线），端到端实现 34.1× 加速（vs CPU 基线），满足实时检测场景基线要求（> 10 FPS）。

目录

1. 昇腾上落地（本仓库重点）
2. 环境要求
3. 快速开始
4. 推理 API
5. 精度与性能评测
6. 优化迭代记录
7. 技术方案详解
8. 已知限制与后续优化方向
9. 引用与许可

1. 昇腾上落地（本仓库重点）

适配改造清单

模型来源：

• GitCode: https://gitcode.com/GitHub_Trending/yo/yolov10
• GitHub: https://github.com/THU-MIG/yolov10

2. 环境要求

2.1 硬件

2.2 软件

pip install torch==2.9.0+cpu torch_npu==2.9.0.post1
pip install onnx2torch==1.5.15 onnx opencv-python-headless numpy

2.3 环境变量（推荐）

export TASK_QUEUE_ENABLE=1   # NPU Stream 级并行，零代码最大收益
export PER_STREAM_QUEUE=1    # 每个 Stream 独立队列

注意: CPU_AFFINITY_CONF 在容器中效果有限，不自动设置。

3. 快速开始

3.1 环境准备与模型导出

pip install torch==2.9.0+cpu torch_npu==2.9.0.post1
pip install onnx2torch==1.5.15 onnx opencv-python-headless numpy

# 克隆 YOLOv10 仓库并导出 ONNX
git clone https://gitcode.com/GitHub_Trending/yo/yolov10.git
cd yolov10
python -c "from ultralytics import YOLOv10; m=YOLOv10('yolov10s.yaml'); m.export(format='onnx', imgsz=640, opset=12, dynamo=False)"

3.2 修复 ONNX 模型

YOLOv10 导出的 ONNX 包含 Constant 节点和 Identity 包装，需先修复：

cd YOLOv10
python fix_onnx_for_npu.py \
  --model yolov10s.onnx \
  --out yolov10s_fixed.onnx

修复内容：

1. 将 Constant 节点转换为 Initializer
2. 消除 Identity 节点对 Initializer 的包装，使 Conv 等算子直接引用权重

3.3 一键验证（推荐，无需真实数据）

cd YOLOv10

# 精度验证（合成数据 NPU vs CPU）
python accuracy_eval.py \
  --model models/yolov10s_fixed.onnx \
  --image /path/to/image.jpg

# 性能基准测试 (NPU)
python benchmark.py --device npu

3.4 运行推理

cd YOLOv10

# NPU 推理
python inference.py \
  --device npu \
  --model models/yolov10s_fixed.onnx \
  --image /path/to/image.jpg \
  --conf 0.25

# CPU fallback
python inference.py \
  --device cpu \
  --model models/yolov10s_fixed.onnx \
  --image /path/to/image.jpg \
  --conf 0.25

4. 推理 API

核心推理类为 YOLOv10Ascend，封装于 inference.py：

from inference import YOLOv10Ascend
import torch

model = YOLOv10Ascend(
    model_path="models/yolov10s_fixed.onnx",
    device=torch.device("npu"),   # 或 torch.device("cpu")
    img_size=640,
    conf_thresh=0.25,
)

boxes, scores, classes = model("/path/to/image.jpg")

• 自动完成图片读取、resize、归一化、模型推理、NMS-free 后处理全流程
• boxes: 检测框坐标 [N, 4] (x1, y1, x2, y2)
• scores: 置信度 [N]
• classes: 类别索引 [N]

5. 精度与性能评测

5.1 性能基线定义

性能基线是衡量 NPU 加速效果的参照标准。本仓库遵循以下基线定义规范：

评测原则: 所有性能数据均在相同输入尺寸、相同 batch size、相同精度条件下测得；NPU 测试前执行 torch.npu.synchronize() 确保计时准确。

5.2 性能评测结果

5.2.1 单模型 Benchmark

测试条件：YOLOv10s, img_size=640, batch=1, FP32, 50 iterations (10 warmup + 50 measured).

基线判定: 目标 FPS > 10，实测 NPU 88.5 FPS，达标 PASS。

5.2.2 端到端 Benchmark

覆盖预处理 + 模型推理 + NMS-free 后处理全流程：

E2E 加速比与单模型差距分析:

单模型 benchmark 仅测 model.forward() 耗时，而 E2E 包含预处理（resize/pad/normalize）与后处理（解码/过滤/clip）。当前实测数据拆解：

结论：E2E 加速比低于单模型是预期现象——预处理在 CPU 上已高度优化（OpenCV），host 侧耗时占比从 CPU 的 0.4% 上升到 NPU 的 23%，导致整体加速比被稀释。后处理已优化为 device 端 clip + 单次 D2H，进一步压缩空间极小。若需继续提升 E2E 吞吐，推荐 batch inference 或 异步流水线 摊薄单图 host 开销。

性能结论:

• 单模型在 NPU 上获得 51.3× 显著加速，11.30 ms/图，满足实时检测基线（> 10 FPS）
• 开启 TASK_QUEUE_ENABLE=2 后单模型进一步提升至 61.2×（9.47 ms，105.6 FPS），零代码额外收益 16.2%
• 端到端获得 34.1× 加速（17.2 ms，58 FPS），生产可用

自证截图:

上图在 Atlas 800I A2 (Ascend910B) 实机运行生成，包含单模型与 E2E 的 CPU/NPU 对比数据。原始日志见 YOLOv10/assets/benchmark_cpu.log 与 YOLOv10/assets/benchmark_npu.log。

5.3 精度验证结果

验证方法：相同输入（随机 tensor 1×3×640×640）下，对比 NPU 与 CPU 的 8 路模型输出。

结论: 全部 8 路输出的 relative error < 1e-7，远低于 1% 阈值，精度达标。

精度验证脚本：

cd YOLOv10
python accuracy_eval.py \
  --model models/yolov10s_fixed.onnx \
  --image /path/to/image.jpg

6. 优化迭代记录

7. 技术方案详解

7.1 关键技术点

7.2 精度保障

• 合成数据验证: 8 路输出 NPU vs CPU relative error < 1e-7
• 修复可复现: fix_onnx_for_npu.py 保证所有用户获得一致的修复后模型
• 阈值判定: 以 1% relative error 为 PASS 阈值，实测误差低于阈值 5 个数量级

8. 已知限制与后续优化方向

已知限制

后续优化方向

9. 引用与许可

引用

• YOLOv10 官方仓库: https://github.com/THU-MIG/yolov10
• torch_npu 性能调优指南: https://www.hiascend.com/document/detail/zh/Pytorch/730/ptmoddevg/trainingmigrguide/performance_tuning_0001.html

许可

本仓库基于 Apache 2.0 License 开源。

目录结构

YOLOv10-518/
├── README.md                    # 本文档
├── YOLOv10/
│   ├── inference.py             # 统一推理入口 (NPU/CPU 自适应)
│   ├── benchmark.py             # 性能基准测试脚本 (CPU/NPU)
│   ├── accuracy_eval.py         # 精度评测脚本 (NPU vs CPU)
│   ├── fix_onnx_for_npu.py      # ONNX 模型修复工具
│   ├── readme.md                # 部署文档
│   ├── SKILL.md                 # Agent Skill 文档
│   └── logs/                    # 评测运行日志
│       ├── benchmark_cpu.log
│       ├── benchmark_npu.log
│       └── accuracy_eval.log
└── .gitattributes