RK3588 部署自训练 YOLO11 模型实战：ONNX 转 RKNN 及 C++ 推理

本文记录了在 RK3588（Linux）平台上，将自训练的 YOLO11（7 类）模型完整部署到板子上的全过程。

包括：环境搭建、模型转换、PC 验证、C++ Demo 编译、板端运行，以及中途遇到的真实问题和解决方法。

一、整体目标与环境说明

🎯 目标

• 使用自训练的 YOLO11（7 类）
• 在 Linux 系统开发板上
• 使用 RKNN C/C++ Demo 成功推理并生成 out.png

🧰 环境信息

• PC：Ubuntu 虚拟机（VMware）
• Python：3.10（conda 环境）
• RKNN Toolkit：rknn-toolkit2
• 芯片：RK3588(8+64)
• 系统：Linux
• 模型：官方 YOLO11，自训练 7 类
• 注意：rknn toolkit 和 requirements.txt 的依赖都安装在 python 环境里了。（rknn-toolkit2、rknpu2 驱动、rknn-toolkit-lite2、rknn_model_zoo 版本要都是 2.3.0 的，必须一致）

二、模型准备：从 YOLO11 到 ONNX

1️⃣ 自训练 YOLO11

使用的是官方 YOLO11，并在自己的数据集上训练，最终得到 best.pt。

2️⃣ 导出 ONNX 模型

在训练环境中执行。需要用到瑞芯微官方的 pt 转 onnx 项目文件。 打开文件如下： 需要在 ./ultralytics/cfg/default.yaml 中修改自己的权重模型文件路径，也就是之前训练得到的 best.pt。我是直接将训练好的权重文件放在文件夹内的。所以将 default.yaml 中第 8 行文件路径设置如下： 然后在以下路径中找到 exporter.py 文件，运行即可。 最终在根目录下得到对应的 onnx 模型。 将 onnx 模型传输到虚拟机内。至此，在 Windows 上的任务结束。

三、ONNX → RKNN，并在 PC 上验证

本文的安装交叉编译工具链、adbd 服务、更新 npu 驱动、安装 rknn-toolkit2 转换环境可参考相关开发板文档。

本人在安装 rknn-toolkit2 转换环境时，按照推荐流程进行测试，没有成功，按照手册的说法是没有安装 TensorFlow。在安装好该模块后，依旧报错，报错信息如下： 根据查阅相关资料，这里的报错是因为 onnx 的版本过新，而 ml_dtypes 的版本太旧。此处建议卸载原有的 onnx，安装更低版本的。

pip uninstall -y onnx pip install onnx==1.16.0 

经过测试，验证成功。

1️⃣ 转换 RKNN 模型

首先，将官方资料中的以下文件拷贝到虚拟机的 software 目录下。 将这两个文件都进行解压，解压到 software 目录下。同时，根据官方手册的提示，将 rknn_model_zoo-2.3.0 的文件夹名称改为 rknn_model_zoo，避免后续出现报错。打开虚拟机终端，进入 modelzoo 目录下，执行权限命令。

cd rknn_model_zoo chmod +x build-linux.sh

将上一节中得到的 onnx 模型拷贝至如下文件夹中，在命令行中输入指令，进入对应文件夹。

cd examples/yolo11/model 

在 yolo11 文件夹中可以找到 cpp、model、python 等文件夹。python 文件夹中找到 yolo11.py 并打开。修改 yolo11.py 中关于类别与类别数的代码。 打开 python 文件夹，进入命令行页面，进入 python 环境。在命令行中输入。（表示执行 convert.py 的代码，使用的模型为之前拷贝进 model 文件夹中的 yolo11.onnx，对象为 rk3588，i8 指转换模型的量化精度）

python3 convert.py ../model/yolo11n.onnx rk3588 i8

成功生成 yolo11.rknn。

2️⃣ PC 上验证 ONNX 和 RKNN（非常关键）

对于新手来讲，不知道自己生成的 onnx 和 rknn 模型是否正确，所以需要在虚拟机上对两个模型进行验证，使用项目自带的 yolo11.py 来验证：

首先，进入 python 目录下，打开命令行，进入 python 环境，在命令行中输入：

python yolo11.py -h

运行的结果如下： 可以从图中看出，该脚本支持指向文件夹，那么将我们的测试图片放在文件夹中。然后在命令行内执行：

python yolo11.py --model_path ../model/yolo11n.onnx --img_folder ../test_images --img_save 

运行后能得到正确的识别图片，说明 onnx 模型没问题。

接下来验证 rknn 模型，还是使用同样的代码进行验证。不过要注意的是，在 PC 端跑 rknn 时，脚本可能会要求连接设备，所以现在最好将设备与虚拟机连接。 同样在 python 目录下，打开命令行：

python yolo11.py --model_path ../model/yolo11.rknn --target rk3588 --img_folder ../test_images --img_save 

得到正确识别的图片则说明验证成功。

四、编译 RKNN C/C++ Linux Demo

1️⃣ 修改 Demo

由于我们使用的是自训练的 yolo11 模型，而 modelzoo 里提供的 examples 都是官方示例，所以会存在一些不同，有一些需要修改的地方。 其中，yolo11.py 已经修改过了。 在 model 目录下，测试图片为官方的 bus.jpg，我们这里需要改为我们数据集对应的识别图片，如 ship.jpg。（尺寸和图质量需要注意） model 目录下还有一个 coco_80_labels_list.txt 文件，我们需要将里面的内容修改为我们要识别的对象名称。我要识别的一共有七个对象，所以内容为： 另外，在 cpp 目录下，需要将 postprocess.h 中类别个数进行修改。 我这里还把 BOX_THRESH 改高了一些。不改也应该不影响。 改完这些就可以开始编译了。

2️⃣ 编译 YOLO11 Demo

先查看 build-linux.sh 用法，这个是将刚才我们的文件目录整个编译为可以传输到板子上的编译器。 在运行 build-linux.sh 之前，需要先：

export GCC_COMPILER=/opt/atk-dlrk3588-toolchain/bin/aarch64-buildroot-linux-gnu

如果不先将编译器使能，稍后执行代码会出错，现在执行：

./build-linux.sh -t rk3588 -a aarch64 -d myyolo11

-t 代表目标板子，-a 代表架构，-d 代表对 examples 里哪个目录进行编译。具体信息如下图所示： 编译完成后生成目录： install/rk3588_linux_aarch64/rknn_myyolo11_demo

五、拷贝 Demo 到 RK3588 板子

1️⃣ 使用 adb 拷贝

adb push install/rk3588_linux_aarch64/rknn_myyolo11_demo /userdata/aidemo

将文件传输到板子上。 在板子上查看：

adb shell ls /userdata/aidemo

2️⃣ 关于模型和标签（重要理解点）

关键理解：

build-linux.sh 只负责编译程序和拷贝资源

如果在 build 之前就已经把：model/yolo11.rknn label 文件（7 类）

换成了自己的

👉 那么 install 出来的 demo 已经是'自己的模型 + 自己的标签'

因此不需要再重复覆盖。

六、板子端运行 Demo

1️⃣ 运行命令

cd /userdata/aidemo ./rknn_yolo11_demo model/yolo11.rknn model/bus.jpg

我当时在做的时候，图片名称叫 ship 时似乎出了点问题，可能是代码里某个部分写的 bus，所以我将自己的图片先命名为 bus。 运行后会生成 out.png。 通过命令，在 pc 端将结果图片拉回。

adb pull /userdata/aidemo/out.png

结果图片在命令行目录下。

七、常见问题与解决方法（非常重要）

❌ 问题 1：图片报错，无法初始化模型

错误信息类似：

✅ 原因

RK3588 C++ Demo 使用 RGA 做图像预处理， 输入图片宽度必须是 4 或 16 的倍数。

✅ 解决方法（推荐）

提前把图片 resize 成 640×640： 针对自己的数据集图片，可以通过以下脚本进行处理，处理后传输到虚拟机内：

#!/usr/bin/env python3
"""
图像转换脚本 - 简洁版
直接将指定图片转换为 640x640 的 JPEG 格式
"""
from PIL import Image # 直接在代码中指定路径
src = 'ship.png' # 输入图片路径
dst = 'ship_640.jpg' # 输出图片路径
try: # 打开图片并转换为 RGB 模式
    img = Image.open(src).convert('RGB') # 调整尺寸为 640x640
    img = img.resize((640, 640)) # 保存为 JPEG，质量为 95
    img.save(dst, 'JPEG', quality=95, optimize=True) print(f"✅ 转换成功！") print(f" 输入：{src}") print(f" 输出：{dst}") print(f" 尺寸：{img.size[0]}x{img.size[1]}") except FileNotFoundError: print(f"❌ 错误：找不到文件 '{src}'") print("请确保 ship.png 文件在当前目录下") except Exception as e: print(f"❌ 错误：{str(e)}")

八、一些经验分享

• PC 上跑通 ≠ 板子上一定跑通
• C++ Demo 对图片尺寸更严格（RGA 对齐）
• 一定要先用官方 bus.jpg 验证
• 新手建议先用 FP 或 i8，流程跑通最重要