RK3576 NPU 部署 YOLOv8：PT→ONNX→RKNN 全流程避坑指南

本文记录一套从 PC 端完成 YOLOv8 模型转换、并在 RK3576 开发板上完成推理验证的完整流程，重点覆盖常见版本坑：Torch/ONNX 版本不对会导致导出空壳模型或 build 阶段报错。

适用环境：x86_64 PC（推荐 Ubuntu 22.04）
目标芯片：Rockchip RK3576
核心流程：.pt ➜ .onnx ➜ .rknn ➜ 真机推理

1. 基础环境与依赖准备

建议使用 Conda 创建全新隔离环境：

conda create -n rknn_yolov8 python=3.10 -y
conda activate rknn_yolov8

1.1 锁定稳定 PyTorch（重要）

踩坑现象：若直接安装较新 torch，在导出 ONNX 时可能因底层 onnxscript 等冲突，生成体积只有 0.3MB 左右的“空壳 ONNX”。

解决方案：锁定到稳定版本（只做导出与转换，CPU 版即可）：

pip install torch==2.1.0 torchvision==0.16.0 --index-url https://download.pytorch.org/whl/cpu

1.2 安装系统依赖（Ubuntu）

sudo apt-get update
sudo apt-get install -y libxslt1-dev zlib1g-dev libgl1-mesa-glx libprotobuf-dev gcc

2. 安装瑞芯微官方工具链

2.1 安装 RKNN-Toolkit2

cd ~
git clone https://github.com/airockchip/rknn-toolkit2.git
pip install ~/rknn-toolkit2/rknn-toolkit2/packages/x86_64/rknn_toolkit2-2.3.2-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

2.2 安装 Rockchip 魔改版 YOLOv8

cd ~
git clone https://github.com/airockchip/ultralytics_yolov8.git
cd ultralytics_yolov8
pip install -e .
pip install onnxscript

2.3 降级 ONNX（解决 mapping 报错）

踩坑现象：rknn-toolkit2 依赖清单可能允许较新 onnx，但其内部代码会强依赖老版本的 mapping 模块，导致 build 阶段报：

AttributeError: module 'onnx' has no attribute 'mapping'

解决方案：强制降级 ONNX：

pip install onnx==1.14.1

3. 导出适配 NPU 的 ONNX

在 ~/ultralytics_yolov8 目录下执行：

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

验证标准：ls -lh yolov8n.onnx 文件大小通常应在 12MB ~ 13MB 左右；如果是 0.3MB 基本可判定导出链路版本不匹配，需要回到 Torch/依赖版本检查。

4. 转换并生成 .rknn（核心）

在同目录新建 convert.py（示例）：

from rknn.api import RKNN

if __name__ == '__main__':
    rknn = RKNN(verbose=True)
    rknn.config(mean_values=[[0, 0, 0]], std_values=[[255, 255, 255]], target_platform='rk3576')

    ret = rknn.load_onnx(model='./yolov8n.onnx')
    if ret != 0:
        exit(ret)

    ret = rknn.build(do_quantization=False)
    if ret != 0:
        exit(ret)

    ret = rknn.export_rknn('./yolov8n_rk3576.rknn')
    if ret != 0:
        exit(ret)

    print('RK3576 模型转换成功')
    rknn.release()

执行转换：

python convert.py

5. 下次复用：只做转换时的最短路径

1. 运行 export.py（改 pt 路径）生成 onnx
2. 运行 make_dataset.py 生成 dataset.txt
3. 运行 convert.py（改配置路径）生成 rknn

6. 真机部署与验证

.rknn 一旦 build 完毕就已面向 RK3576 硬件，PC 模拟器无法直接运行已 build 的 .rknn；验证必须连接实体开发板。

1. 获取官方验证代码

cd ~
git clone https://github.com/airockchip/rknn_model_zoo.git
cd rknn_model_zoo/examples/yolov8/python
pip install opencv-python

2. 连接设备并推理验证

确保 adb devices 能识别设备。运行官方脚本时必须加 --target rk3576，否则可能默认识别为其他平台导致报错：

python yolov8.py --model_path ~/ultralytics_yolov8/yolov8n_rk3576.rknn --target rk3576

成功标志：脚本会在当前目录生成绘制检测框后的 out.jpg。

7. 性能参考（RK3576 / YOLOv8n）

• FP16：精度最高，纯 NPU 推理约 25~35 FPS（端到端视输入与后处理而定）
• INT8：精度轻微下降，纯 NPU 推理可到 70~75 FPS（端到端通常更低）