YOLOv11s-Pose 模型导出 ONNX 并适配 Rockchip NPU 全流程记录

一、需求背景

训练了一个 YOLOv11s-Pose 姿态估计模型（.pt 格式），最终目标是部署在瑞芯微 RK3588/RK3568 等芯片的 NPU 上。要将 PyTorch 模型落地到瑞芯微 NPU，第一步是把模型导出为 ONNX，而且不能直接使用官方的 Ultralytics 仓库------必须使用瑞芯微专门优化过的 ultralytics_yolo11 仓库。该仓库对原始模型做了三项针对 NPU 的适配：

1. 移除了对量化不友好的后处理模块；
2. 移除了在 NPU 上效率较低的 DFL 结构；
3. 新增得分和输出分支，用于加速 CPU 端的后处理。

下面记录完整的导出过程和踩坑经验，便于后续在 Rockchip NPU 上继续开发。

二、完整操作步骤

2.1 克隆瑞芯微优化版仓库

必须使用瑞芯微维护的仓库，而非官方 ultralytics/ultralytics：

git clone https://github.com/airockchip/ultralytics_yolo11.git
cd ultralytics_yolo11

⚠️ 关键点：如果误用官方仓库，导出的 ONNX 模型不会包含 NPU 优化，后续 RKNN 转换时会遇到各种兼容性问题。

2.2 创建 Conda 虚拟环境

为项目创建独立的 Python 环境，推荐使用 Python 3.9，与瑞芯微工具链兼容性最好：

conda create -n yolo11_rknn python=3.9 -y
conda activate yolo11_rknn

2.3 安装项目依赖

在项目根目录下执行：

pip install -e .

该命令会自动安装 requirements.txt 中列出的所有依赖，包括 torch、ultralytics 等。

2.4 修改配置文件 ultralytics/cfg/default.yaml

找到文件中的 model: 字段，将其值改为你自己训练好的 .pt 模型的绝对路径，例如：

model: D:/Work/8-python-lingshi/1/ultralytics_yolo11-main/ultralytics/engine/best_24bit.pt

注意：Windows 下路径建议使用正斜杠 /，避免反斜杠 \ 转义问题。

2.5 安装 ONNX 相关依赖

导出过程中可能会提示缺少 onnxscript 等模块，建议提前安装：

pip install onnx onnxscript onnxsim onnxruntime

2.6 执行导出命令

在项目根目录下先设置 PYTHONPATH，再运行导出脚本：

Windows（cmd）：

set PYTHONPATH=./
python ultralytics/engine/exporter.py

Linux/macOS：

export PYTHONPATH=./
python ./ultralytics/engine/exporter.py

三、遇到的问题与解决方案

问题 1：ImportError: cannot import name 'TASK2CALIBRATIONDATA'

• 原因 ：使用了官方的 Ultralytics 仓库，而非瑞芯微优化版的 ultralytics_yolo11。
• 解决 ：切换到 airockchip/ultralytics_yolo11 仓库，并重新安装依赖。

问题 2：Windows 下 export 命令不可用

• 报错 ：'export' 不是内部或外部命令
• 原因 ：export 是 Linux/macOS 的环境变量设置命令，在 Windows 下需要使用 set。
• 解决 ：将命令行中的 export PYTHONPATH=./ 替换为 set PYTHONPATH=./。

问题 3：FileNotFoundError: No such file or directory: 'best_24bit.pt'

• 原因 ：ultralytics/cfg/default.yaml 中的 model: 路径未修改或填写错误。
• 解决 ：在配置文件中填写正确的 .pt 文件绝对路径，并确保文件存在。

问题 4：ModuleNotFoundError: No module named 'onnxscript'

• 原因：缺少 ONNX 导出所需的 Python 库。
• 解决 ：运行 pip install onnxscript onnx onnxsim。

问题 5：Opset 版本警告（Resize 算子适配失败）

• 现象 ：RuntimeError: No Adapter To Version $17 for Resize
• 影响 ：该警告不会影响最终导出结果，模型仍可成功生成 .onnx 文件。
• 建议 ：后续可在导出脚本中指定 opset_version=12 或 13，以避免此类版本适配警告。

四、导出成功标志

导出完成后，终端会输出类似如下的信息：

RKNN: export success ✅ 5.5s, saved as 'D:\...\best_24bit.onnx' (0.5 MB)
Export complete (11.2s)
Results saved to D:\...\ultralytics\engine

生成的 ONNX 文件 best_24bit.onnx 位于原始 .pt 模型同级目录下。

五、后续部署建议

5.1 转换为 RKNN 模型

使用瑞芯微官方工具链进行转换：

git clone https://github.com/airockchip/rknn_model_zoo.git
cd rknn_model_zoo/examples/yolo11/python
python convert.py --model best_24bit.onnx --target rk3588 --output best_24bit.rknn

5.2 部署推理

• 可以直接使用 rknn_model_zoo 提供的 C++/Python 示例进行推理。
• 需要注意：因为模型已经移除了后处理，推理后需要在 CPU 端运行官方的后处理代码。
• 对于**姿态估计（Pose）**任务，还需要参照检测示例，自行适配关键点解码逻辑。

5.3 精度与性能优化

• 建议进行 INT8 量化，以充分利用 NPU 的算力。
• 量化前需要准备一份校准数据集（calibration dataset）。

六、心得总结

1. 版本和仓库是最大的坑 ：务必使用瑞芯微优化版的 ultralytics_yolo11 代码库，官方仓库导出的模型无法直接用于 RKNN 部署。
2. 环境隔离很重要：为每个项目创建独立的 Conda 环境，能有效避免依赖冲突，提高可复现性。
3. Windows 和 Linux 的命令差异 ：留意 export vs set、路径分隔符等细节，避免因系统差异导致奇怪的问题。
4. Op set 版本控制 ：如有必要，可在 exporter.py 中显式设置 opset_version=12，减少不必要的版本适配警告。
5. 官方文档是最好的老师 ：瑞芯微仓库中的 RKOPT_README.md 以及 rknn_model_zoo 示例都值得仔细阅读，它们是部署路上最可靠的指引。