YOLOv11 模型迁移指导文档

1 模型概述与应用场景

1.1 模型概述

YOLOv11m是Ultralytics推出的第11代YOLO系列目标检测模型，在COCO数据集上实现了精度与推理速度的最佳均衡，是实时目标检测的主流选择。该模型可同时检测80类目标（人、车、飞机、火车等），输入640×640图像即可输出所有目标的类别、置信度和边界框坐标，广泛用于安防监控、交通检测和工业质检等场景。

2 迁移环境

本章描述YOLOv11模型迁移到Ascend310P3所需的硬件和软件环境。310P服务器为离线环境（无外网），所有依赖需提前准备离线安装包。

2.1 硬件环境

目标推理服务器为华为Ascend310P3，4卡配置，aarch64架构。以下为310P3硬件环境信息：

2.2 软件环境

310P3上运行推理所需的软件栈包括CANN工具链、Python运行环境及模型推理依赖库。以下为各软件版本及说明：

3 资源与依赖

本章列出模型迁移所需的全部资源文件，包括模型权重、测试数据、推理脚本和离线依赖包。所有资源位于/yolo11Adapt/目录下。

3.1 模型权重

迁移涉及三种格式的模型权重：PyTorch原始权重(.pt)、ONNX导出模型(.onnx)和ATC转换的OM模型(.om)。.pt和.onnx已预置在目录中，.om需在310P3上通过ATC命令生成。

3.2 测试数据集

使用3张JPEG图片验证推理效果，涵盖person、train、airplane等典型检测目标。

3.3 推理脚本

提供三种推理方式的Python脚本，分别对应torch_npu、ONNX Runtime和ais_bench OM推理。脚本已适配310P3环境，输出检测结果图片和目标列表。

3.4 离线依赖包

310P服务器无外网，所有Python依赖需通过离线包安装。离线包包含60个wheel包、torch_npu本地安装包和ais_bench源码（需编译）。install.sh脚本实现一键安装，采用"检测import可用性→只修不可导入包"策略，避免破坏CANN镜像预装的symlink结构。

4 环境准备

4.1 资源传输

310P服务器为离线环境，需将整个/yolo11Adapt/目录传输至310P容器内：

方式一：scp传输 (如有内网) scp -r /yolo11Adapt @<310P_ip>:/

方式二：U盘/移动硬盘拷贝 将/yolo11Adapt目录整体拷贝至U盘，在310P容器内挂载复制

方式三：容器镜像打包 docker save/load 整个容器镜像 (含所有依赖)

4.2 环境确认

进入310P容器后，依次确认以下环境要素：

1. 确认NPU设备 (310P3, 4卡)

npu-smi info

2. 确认CANN可用

source /usr/local/Ascend/cann-8.5.0/set_env.sh

3. 确认Python版本 (必须3.11)

python3 --version

4. 确认ATC可用

atc --help | head -3

4.3 离线依赖安装

310P为离线环境，所有Python包通过离线wheel包安装。核心策略：CANN镜像已预装大部分包 (torch/numpy/ultralytics等通过symlink可用)，install.sh只修复不可导入的包，不做全量重装，避免破坏CANN symlink结构。 cd /yolo11Adapt/offer_package tar xzf yolo11m_offline_pkg.tar.gz bash install.sh

install.sh执行流程：

重要提示：

1. 绝不能创建system site-packages → CANN site-packages的反向symlink。CANN镜像中numpy/torch等是symlink从CANN指向system site-packages (原始设计)，反向symlink会造成循环引用导致所有包不可导入。
2. CANN镜像中已预装的包 (torch/numpy/ultralytics等) 不要重装，重装会破坏symlink结构。install.sh通过import检测避免了此问题。
3. Python版本必须为3.11，与wheel包cp311严格匹配。

4.4 安装后验证

python3 -c "import torch; print(torch.version)" # 2.3.1 python3 -c "import torch_npu; print(torch_npu.version)" # 2.3.1.post6 python3 -c "from ultralytics import YOLO; print('OK')" # OK python3 -c "import onnxruntime; print(onnxruntime.version)" # 1.16.3 python3 -c "from ais_bench.infer.interface import InferSession; print('OK')" # OK

5 ATC模型转换 (ONNX → OM)

5.1 转换命令

source /usr/local/Ascend/cann-8.5.0/set_env.sh

atc --model=/yolo11Adapt/output/yolo11m.onnx
--framework=5 \n --output=/yolo11Adapt/output/yolo11m \n --soc_version=Ascend310P3 \n --input_shape="images:1,3,640,640"

5.2 参数说明

5.3 预期输出

转换成功后生成: /yolo11Adapt/output/yolo11m.om (约40~50MB) 注意: 首次ATC转换可能耗时30分钟以上 (编译算子)，属于正常现象。

5.4 常见问题

6 推理测试

6.1 torch_npu推理 (脚本01)

原理: ultralytics框架加载PT权重，通过torch_npu后端在NPU上推理。脚本包含NPU预热和FP16加速优化。 cd /yolo11Adapt python3 script/01_torch_npu_infer.py 关键检查点：

6.2 ONNX推理 (脚本02)

原理: ultralytics直接加载ONNX模型，使用ONNX Runtime在CPU上推理。作为NPU推理的baseline对照，验证模型正确性。 python3 script/02_onnx_infer.py

6.3 ais_bench OM推理 (脚本03)

原理: 加载ATC转换的OM模型，通过aclruntime在NPU上推理。这是310P上的生产级推理方式，性能最优。 python3 script/03_ais_bench_infer.py 前提: yolo11m_310P3.om已通过ATC生成，位于/yolo11Adapt/model/

注意: 脚本03的letterbox预处理使用居中padding (四周均匀分布)，坐标还原时需减去pad_left和pad_top偏移量，与脚本01/02的右下角padding不同。

7 推理方式对比

8 后处理说明

三个脚本均包含完整的YOLO后处理流程：

1. 置信度过滤 (CONF_THRESH=0.25)
2. NMS去重 (IOU_THRESH=0.45)
3. Letterbox坐标还原 (将640x640坐标还原为原始图片坐标)

Letterbox padding方式差异 (重要):

9 常见问题排查

问题 1：torch.npu.is_available()返回False

现象描述：进入310P容器后执行torch.npu.is_available()返回False，无法使用NPU推理。 根因分析：CANN环境未正确加载或torch_npu与CANN版本不匹配。 解决措施：1) 执行npu-smi info确认NPU设备可见 2) source /usr/local/Ascend/cann-8.5.0/set_env.sh加载环境 3) 检查torch_npu版本(2.3.1.post6)与CANN版本(8.5.0)匹配 4) 若仍失败，检查CANN OPP包是否完整安装

问题 2：ATC转换OM失败，算子不支持 (Conv2D/MaxPoolV3)

现象描述：执行ATC转换时报错：Unsupported_Operator(EZ3003): No supported Ops kernel and engine are found for [/model.1/conv/Conv], optype [Conv2D]。Conv2D、MaxPoolV3等基础算子找不到支持内核。 根因分析：YOLO11的ONNX模型与Ascend310P3不兼容。Conv2D和MaxPoolV3等基础算子找不到支持内核，问题不在于模型优化参数，而是YOLO11的网络结构（C2f模块和注意力机制）在310P3上不被支持，根因是CANN版本或OPP算子包不匹配。 解决措施：措施1（推荐）：更换CANN镜像版本。从昇腾社区下载匹配的ARM版本： docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/cann:8.5.0-310p-openeuler24.03-py3.11 查看已有CANN镜像：docker images | grep cann 措施2：下载310P3专用算子包（OPP）。访问 https://support.huawei.com/enterprise/zh/Ascend%20Computing/cann-pid-251168373/software 选择对应版本安装。

问题 3：cv2模块不可导入但pip显示already satisfied

现象描述：执行import cv2报ModuleNotFoundError，但pip list显示opencv-python-headless已安装。 根因分析：CANN site-packages中opencv-python-headless为broken symlink（指向system site-packages中已删除的实际文件），pip误判为已安装。 解决措施：1) pip uninstall -y opencv-python opencv-python-headless 2) pip install --no-deps --force-reinstall opencv-python-headless==4.10.0.84 3) 执行import cv2验证可导入

问题 4：ultralytics模块不可导入但pip显示already satisfied

现象描述：执行from ultralytics import YOLO报ModuleNotFoundError，但pip list显示ultralytics已安装。 根因分析：CANN site-packages中ultralytics为broken symlink，实际文件已被pip卸载删除。 解决措施：1) pip uninstall -y ultralytics ultralytics-thop 2) pip install --no-deps --force-reinstall ultralytics==8.4.77 3) pip install --no-deps ultralytics-thop==2.0.20 4) 执行from ultralytics import YOLO验证可导入

问题 5：aclruntime模块import失败

现象描述：执行import aclruntime报ModuleNotFoundError或ImportError。 根因分析：aclruntime未编译安装，或编译时CANN_PATH环境变量未设置导致找不到libascendcl.so。 解决措施：1) export CANN_PATH=/usr/local/Ascend/cann-8.5.0 2) export ASCEND_TOOLKIT_HOME=$CANN_PATH 3) cd ais_bench_src/backend && rm -rf build dist *.egg-info 4) pip3 install --no-build-isolation . 5) 验证: python3 -c "import aclruntime"

问题 6：ais_bench加载OM模型失败

现象描述：InferSession加载OM文件时报错，提示芯片型号不匹配。 根因分析：OM模型的soc_version与当前310P3芯片不一致（如使用了Ascend310P1生成的OM）。 解决措施：1) 删除旧OM文件 2) 使用正确的soc_version重新ATC转换: atc --model=yolo11m.onnx --framework=5 --output=yolo11m --soc_version=Ascend310P3 --input_shape="images:1,3,640,640" 3) 将新生成的OM文件拷贝至脚本03期望的路径

问题 7：OM文件权限过开放，ais_bench拒绝加载

现象描述：执行ais_bench推理时报错：[ERROR] The file ... is group writable, or is others writable, as import file(or directory), permission should not be over 0o755(rwxr-xr-x)。InferSession初始化失败。 根因分析：昇腾ais_bench推理框架的安全机制严格禁止加载组用户(group)或其他用户(others)具有写权限的模型文件。当前.om文件权限过于开放。 解决措施：移除模型文件的组写和其他写权限： chmod go-w /yolo11Adapt/model/yolo11m_310P3.om 建议同时修正整个model目录权限： chmod 755 /yolo11Adapt/model chmod 644 /yolo11Adapt/model/.om chmod 644 /yolo11Adapt/model/.onnx chmod 644 /yolo11Adapt/model/.pt 验证：ls -la /yolo11Adapt/model/.om

问题 8：检测结果为0

现象描述：推理脚本执行完成但检测数量为0，无任何目标框输出。 根因分析：输入图片路径错误、图片无法读取、或置信度阈值设置过高。 解决措施：1) 检查图片文件路径是否正确 2) 检查图片文件是否可读（cv2.imread返回非None） 3) 降低CONF_THRESH（如从0.25降到0.1） 4) 确认模型权重文件完整

问题 9：ATC模型转换失败

现象描述：执行atc命令报OPP not found或算子不支持错误。 根因分析：310P3 OPP包未安装，或CANN版本过低导致部分算子（如Conv2D）不支持。 解决措施：1) 安装对应Ascend310P3的OPP包 2) 确认CANN版本>=8.5.0 3) source set_env.sh后重试ATC命令 4) 检查ONNX模型输入shape与ATC --input_shape参数匹配

问题 10：安装后所有包都不可导入

现象描述：install.sh执行完成后，python3 -c "import torch"等所有模块均报ModuleNotFoundError。 根因分析：误创建了system site-packages → CANN site-packages的反向symlink，造成循环引用。CANN原始设计中torch/numpy等是从CANN指向system的symlink，反向symlink形成死循环。 解决措施：1) 删除反向symlink: rm /usr/local/python3.11.14/lib/python3.11/site-packages 2) 重建正常目录: mkdir /usr/local/python3.11.14/lib/python3.11/site-packages 3) 重新执行install.sh 4) install.sh已内置broken symlink清理和按需安装逻辑，不会创建反向symlink

问题 11：pip install --no-build-isolation编译aclruntime失败

现象描述：在离线310P环境执行pip install --no-build-isolation .编译aclruntime时失败。 根因分析：离线环境缺少编译依赖（setuptools/pybind11未安装），或CANN_PATH未设置。 解决措施：1) 确保setuptools和pybind11已安装: pip install --no-deps setuptools pybind11 2) 设置CANN环境变量: export CANN_PATH=/usr/local/Ascend/cann-8.5.0 source $CANN_PATH/set_env.sh 3) 重新编译: pip3 install --no-build-isolation --no-index --find-links=wheels/ .

10 完整测试流程 (一键执行)

Step0：确认环境

source /usr/local/Ascend/cann-8.5.0/set_env.sh npu-smi info python3 --version

Step1：离线依赖安装

cd /yolo11Adapt/offer_package bash install.sh

Step2：ATC转OM

atc --model=/yolo11Adapt/output/yolo11m.onnx --framework=5 \n --output=/yolo11Adapt/output/yolo11m \n --soc_version=Ascend310P3 \n --input_shape="images:1,3,640,640"

Step3：拷贝OM到脚本路径

cp /yolo11Adapt/output/yolo11m.om /yolo11Adapt/model/yolo11m_310P3.om chmod 644 /yolo11Adapt/model/yolo11m_310P3.om

Step4：推理测试

cd /yolo11Adapt python3 script/01_torch_npu_infer.py python3 script/02_onnx_infer.py python3 script/03_ais_bench_infer.py