RK3588部署YOLOv11：模型转换与NPU加速实践

1. 项目概述

最近在RK3588开发板上成功部署了YOLOv11模型，整个过程涉及模型格式转换、环境配置和部署运行等多个环节。作为一款性能优异的边缘计算设备，RK3588搭载了强大的NPU（神经网络处理单元），能够高效运行深度学习模型。本文将详细介绍从PyTorch模型到RKNN模型转换的全过程，以及在RK3588上部署运行的具体步骤。

YOLOv11作为YOLO系列的最新成员，在目标检测任务中表现出色。但在边缘设备上部署时，需要将原始PyTorch模型转换为RKNN格式，才能充分利用RK3588的NPU加速能力。这个过程看似简单，实则暗藏不少坑点，特别是在模型转换和量化环节。

2. 模型转换（PyTorch到ONNX）

2.1 准备工作

首先需要从GitHub获取YOLOv11的官方代码库：

bash复制git clone https://github.com/airockchip/ultralytics_yolo11.git

这个仓库是基于Ultralytics YOLO的修改版，专门适配了RKNN转换需求。建议使用Python 3.8环境，因为后续的RKNN-Toolkit2对该版本支持最好。

注意：务必检查代码库的commit版本，不同版本可能在模型导出时存在差异。建议使用最新的稳定版本。

2.2 修改配置文件

模型转换前需要调整配置文件，指定自定义模型的路径。主要修改两个地方：

1. 模型结构配置文件（通常是yolov11.yaml）
2. 权重文件路径配置

在yolov11.yaml中，需要确保backbone和head的结构与你训练的模型一致。如果是自定义模型，这里必须与训练时的配置完全相同。

yaml复制# yolov11.yaml示例
backbone:
  # [from, repeats, module, args]
  [[-1, 1, Conv, [64, 6, 2, 2]],  # 0-P1/2
   [-1, 1, Conv, [128, 3, 2]],  # 1-P2/4
   ...]
head:
  [[-1, 1, nn.Conv2d, [na * (5 + nc), 1, 1]],  # 23 (P5/32-large)
   ...]

2.3 执行ONNX转换

转换命令如下：

bash复制cd ultralytics_yolo11
export PYTHONPATH=./  
python ./ultralytics/engine/exporter.py

关键参数说明：

• export PYTHONPATH=./：确保Python能找到本地模块
• 执行后会在pt文件同目录生成ONNX模型

常见问题：如果遇到shape不匹配错误，可能是因为模型结构定义与权重不匹配。检查yaml文件是否与训练时使用的完全一致。

3. ONNX到RKNN转换

3.1 准备量化数据集

这是最容易出错的关键步骤！必须使用训练时相同的正样本图像作为量化数据集，而不是COCO等通用数据集。

建议操作：

1. 从训练集中随机选取10-20张代表性图像
2. 创建subset目录存放这些图像
3. 生成subset.txt文件记录图像路径

提供的Python脚本可以自动完成这一过程：

python复制import os
import argparse

def write_subset():
    f_train = open(os.path.join(opt.input_path,'subset.txt'), 'w')
    img_dir = os.path.join(opt.input_path, 'subset')
    img_list = os.listdir(img_dir)
    
    for img in img_list:
        jpg_dir = r'./subset/'+ img
        f_train.writelines(jpg_dir)
        f_train.write('\n')
        
    f_train.close()
    print(f'total: {len(img_list)}')

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument('--input_path', type=str, 
                      default=r'/path/to/your/dataset/',
                      help='dataset path')
    opt = parser.parse_args()
    write_subset()

3.2 配置转换环境

RKNN-Toolkit2是模型转换的核心工具，环境配置步骤如下：

1. 创建conda环境：

bash复制conda create -n rknn230 python==3.8
conda activate rknn230

2. 安装依赖：

bash复制cd rknn-toolkit2/packages/x86_64/
pip install -r requirements_cp38-2.3.0.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install rknn_toolkit2-2.3.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

避坑指南：必须严格匹配Python 3.8和RKNN-Toolkit2 2.3.0版本，其他版本组合可能导致不可预知的问题。

3.3 执行模型转换

转换命令：

bash复制python convert.py best.onnx rk3588

可选参数：

• fp：不进行量化（如best.onnx rk3588 fp）
• qat：使用量化感知训练模型

转换过程可能持续几分钟，成功后会生成.rknn文件。建议首次尝试时不加fp参数，观察量化后的模型精度。

经验之谈：如果量化后精度下降严重，可以尝试以下方法：

1. 增加量化数据集图像数量（20-50张）
2. 确保量化图像具有代表性
3. 检查ONNX模型本身的精度

4. RK3588环境搭建

4.1 基础环境配置

在RK3588开发板上需要安装以下依赖：

bash复制sudo apt update
sudo apt install python3-pip cmake

4.2 RKNN运行时环境

1. 安装RKNN-Toolkit2的ARM版本：

bash复制cd /rknn-toolkit2/packages/arm
pip install -r arm64_requirements_cp38.txt -i https://mirrors.aliyun.com/pypi/simple
pip install rknn_toolkit2-2.3.0-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

2. 安装NPU运行时库：

bash复制git clone https://github.com/rockchip-linux/rknpu2
sudo cp rknpu2/runtime/RK3588/Linux/librknn_api/aarch64/librknnrt.so /usr/lib/

重要提示：librknnrt.so的版本必须与RKNN-Toolkit2版本匹配，否则会导致运行时错误。

5. 模型部署与运行

5.1 准备部署文件

从rknn_model_zoo获取YOLOv11的部署代码：

bash复制git clone https://github.com/airockchip/rknn_model_zoo
cd rknn_model_zoo/examples/yolov11/python

目录结构应包含：

• yolov11.py：主推理脚本
• utils.py：辅助函数
• model/yolov11.rknn：转换好的模型

5.2 运行推理

基本命令：

bash复制python yolov11.py --model_path ../model/yolov11.rknn --target rk3588 --img_show

参数说明：

• --model_path：RKNN模型路径
• --target：目标平台（必须为rk3588）
• --img_show：显示检测结果

5.3 性能优化技巧

1. 多线程推理：RK3588有6个CPU核心，可以使用多线程提高吞吐量
2. NPU频率调节：通过调节NPU频率平衡功耗和性能

bash复制echo performance > /sys/devices/platform/fdab0000.npu/devfreq/devfreq0/governor

3. 内存优化：减少不必要的内存拷贝，尽量复用内存

6. 常见问题与解决方案

6.1 模型转换失败

问题现象：ONNX到RKNN转换时报错

可能原因：

1. ONNX模型包含RKNN不支持的算子
2. 输入输出形状不匹配
3. 量化数据集问题

解决方案：

1. 检查ONNX模型是否包含非常规算子
2. 使用Netron可视化ONNX模型结构
3. 尝试不量化（加fp参数）

6.2 推理结果异常

问题现象：检测框错乱或置信度异常

可能原因：

1. 量化过程中精度损失过大
2. 预处理/后处理与训练时不匹配
3. 模型输出层解析错误

解决方案：

1. 增加量化数据集数量和多样性
2. 检查预处理代码（归一化、resize方法等）
3. 对比ONNX和RKNN模型的输出

6.3 NPU利用率低

问题现象：NPU使用率不足，性能不达预期

可能原因：

1. 输入数据准备成为瓶颈
2. 模型太小，无法充分利用NPU
3. 内存带宽限制

解决方案：

1. 使用多线程流水线
2. 增大batch size
3. 合并小模型

7. 实测性能数据

在RK3588上测试YOLOv11s模型（输入640x640）的性能：

从测试数据可以看出，适当增加线程数能显著提升NPU利用率，但也会增加功耗。实际部署时需要根据应用场景权衡。

8. 部署优化建议

1. 模型裁剪：针对具体应用场景，移除不必要的检测类别
2. 量化校准：使用场景特定的校准数据集，提高量化精度
3. 多模型流水线：将检测和后续任务（如分类）流水线化
4. 温度管理：长时间运行时注意散热，避免降频

经过实际项目验证，这套部署流程在RK3588上运行稳定，能够满足实时目标检测的需求。最大的经验教训是：量化数据集的质量直接决定最终模型的精度，务必重视这个环节。