YOLOv5模型→RKNN量化部署瑞芯微RK3588开发板完整流程

环境总览

硬件

瑞芯微 RK3588 开发板（8nm，NPU 6TOPS，RKNN Toolkit2 适配）

软件环境

1. PC 端（模型转换量化）：Ubuntu20.04/22.04

Python 3.8/3.9

YOLOv5 官方源码 v6.1/v7.0（推荐 v7.0）

RKNN Toolkit2 1.5.0+（RK3588 最低要求 1.4.0）

依赖：torch、torchvision、onnx、onnx-simplifier、opencv-python

2. 开发板端（推理运行）：Linux aarch64

RKNN API aarch64 库、OpenCV、gcc/g++、cmake

一、PC 端训练 / 导出 YOLOv5 ONNX 模型

1. 克隆 YOLOv5 源码

git clone https://github.com/ultralytics/yolov5.git

cd yolov5

pip install -r requirements.txt

2. 训练 / 使用预训练权重导出 ONNX

关键导出参数（适配 RKNN，消除后处理、适配 NPU）

# 导出onnx，关闭grid导出、固定输入尺寸、简化模型

python export.py --weights best.pt \

--img 640 640 \

--batch-size 1 \

--include onnx \

--opset 12 \

--simplify \

--no-grid \

--nms False

- --no-grid：不拼接 grid 层，RKNN 不支持复杂动态索引，后处理代码手动解析坐标

- --nms False：关闭模型内 NMS，板端 CPU 做 NMS 更稳定

- opset12：RKNN Toolkit2 兼容性最佳

3. ONNX 模型简化（必做，去除冗余节点）

pip install onnx-simplifier

python -m onnxsim best.onnx best_simplify.onnx

校验模型无报错、输入输出 shape 固定 (1,3,640,640)

二、RKNN Toolkit2 安装（PC Ubuntu）

1. 下载对应 RKNN Toolkit2

瑞芯微官网下载 RKNN_Toolkit_Linux_x86_64_V1.5.0.zip

unzip RKNN_Toolkit_Linux_x86_64_V1.5.0.zip

cd RKNN_Toolkit_Linux_x86_64_V1.5.0/packages

pip3 install rknn_toolkit2-1.5.0-cp39-cp39-linux_x86_64.whl

2. 环境校验

from rknn.api import RKNN

print(RKNN.__version__)

输出版本号即安装成功

三、YOLOv5 ONNX 转 RKNN+INT8 量化（核心步骤）

量化说明

RK3588 NPU 仅加速 INT8，FP16 仅少量算子支持，必须做 INT8 对称量化；需要校准图片集（50~200 张训练集图片即可）

完整转换量化脚本 yolov5_onnx2rknn.py

from rknn.api import RKNN

import os

# =====================配置区=====================

ONNX_MODEL = "best_simplify.onnx"

RKNN_MODEL = "yolov5_rk3588.rknn"

IMG_SIZE = 640

DATASET_TXT = "./calib.txt"  # 校准图片路径txt文件

TARGET_PLATFORM = "rk3588"

QUANTIZE_ON = True  # 开启INT8量化

# ===============================================

# 1. 创建RKNN对象

rknn = RKNN(verbose=True)

# 2. 全局配置

print("--> Config model")

rknn.config(

    mean_values=[[0, 0, 0]],        # YOLOv5归一化：x/255，均值0

    std_values=[[255, 255, 255]],   # 方差255

    target_platform=TARGET_PLATFORM,

    quant_algorithm="normal",       # 常规对称量化

    quant_input_type="uint8",

)

# 3. 加载ONNX模型

print("--> Load ONNX model")

ret = rknn.load_onnx(model=ONNX_MODEL)

if ret != 0:

    print("Load ONNX failed!")

    exit(-1)

# 4. 构建模型（转换算子适配RK NPU）

print("--> Build model")

ret = rknn.build(do_quantization=QUANTIZE_ON, dataset=DATASET_TXT)

if ret != 0:

    print("Build rknn failed!")

    exit(-1)

# 5. 导出rknn文件

print("--> Export RKNN model")

ret = rknn.export_rknn(RKNN_MODEL)

if ret != 0:

    print("Export rknn failed!")

    exit(-1)

# 6. PC端仿真推理测试（可选，验证量化精度）

print("--> Init runtime environment for pc simulate")

ret = rknn.init_runtime()

if ret != 0:

    print("Init runtime failed")

    exit(-1)

# 测试推理省略，自行读取图片预处理推理验证

# 释放资源

rknn.release()

print("Convert success, output:", RKNN_MODEL)

校准数据集 calib.txt 制作

1. 新建 calib 文件夹，放入 100 张训练原图

2. 生成 txt：每行一张图片绝对 / 相对路径

ls ./calib/*.jpg > calib.txt

运行转换

python yolov5_onnx2rknn.py

输出 yolov5_rk3588.rknn 量化模型文件

四、RK3588 开发板环境部署

1. 文件传输

将 yolov5_rk3588.rknn、测试图片、源码传到开发板（scp/U 盘）

2. 板端 RKNN API 库部署

RKNN Toolkit 包内 runtime/RKNN_Linux_aarch64 复制到开发板：

lib/librknn_api.so 放到 /usr/lib

include/rknn_api.h 保留给编译使用

3. 安装依赖

apt update

apt install gcc g++ cmake libopencv-dev python3-opencv

五、RK3588 端两种推理方案

方案 A：Python RKNN 推理（快速验证，适合调试）

板端安装 rknn_toolkit2_aarch64

复制对应 aarch64 whl 包到开发板安装

推理核心逻辑要点：

1. 图片预处理：resize 640×640 → BGR 转 RGB → 归一化 / 255

2. rknn.inference 输入 (1,3,640,640)

3. 输出 3 个检测头：80×80×3×(5+cls)、40×40、20×20

4. 手动解码 xywh 坐标、置信度过滤、NMS 抑制重复框

方案 B：C++ RKNN 高性能推理（量产推荐）

工程结构

rknn_yolov5_demo/

├── CMakeLists.txt

├── src/

│   ├── main.cpp        # 主推理流程

│   ├── yolov5.cpp      # 后处理解码+NMS

│   └── image_utils.cpp # opencv预处理

├── include/

│   ├── rknn_api.h

│   ├── yolov5.h

│   └── image_utils.h

├── lib/

│   └── librknn_api.so

└── model/yolov5_rk3588.rknn

CMakeLists.txt 关键配置

cmake_minimum_required(VERSION 3.10)

project(yolov5_rk3588)

set(CMAKE_CXX_STANDARD 11)

# OpenCV

find_package(OpenCV REQUIRED)

include_directories(${OpenCV_INCLUDE_DIRS})

# RKNN

include_directories(./include)

link_directories(./lib)

file(GLOB SRC src/*.cpp)

add_executable(demo ${SRC})

target_link_libraries(demo ${OpenCV_LIBS} rknn_api)

编译运行

mkdir build && cd build

cmake ..

make -j4

./demo

六、YOLOv5 后处理核心逻辑（RKNN 输出解码）

1. 检测头输出格式

每个输出通道：[x, y, w, h, conf, cls0, cls1...]

- x,y,w,h：相对于 640 尺寸的偏移，未做 sigmoid

2. 解码步骤

1. 对 x,y 执行 sigmoid，加上网格坐标

2. w,h 做 exp 缩放，乘以预设 anchor

3. conf× 类别得分 = 目标分数，阈值过滤（如 0.25）

4. 所有框集合做 NMS（iou 阈值 0.45）

RK3588 优化：NMS 使用 CPU，NPU 只做模型推理

七、常见报错与优化方案

1. ONNX 导出报错

- 解决：关闭 autoshape，固定 batch=1，--simplify 简化模型

2. RKNN build 量化失败

- 原因：校准图过少、归一化 mean/std 配置错误

- 修复：严格配置 mean[0,0,0] std[255,255,255]，校准图≥50 张

3. 板端推理框偏移、精度暴跌

1. 预处理通道顺序错误（RKNN 默认 RGB，OpenCV 读取 BGR 需转换）

2. 归一化和 rknn.config 均值方差不匹配

3. anchor 参数和训练时不一致

4. RK3588 NPU 跑不满、速度慢

1. 使用 INT8 量化，禁止 FP32 推理

2. 输入尺寸固定 640，不动态 resize

3. C++ 代码替代 Python 推理，减少数据拷贝

4. 开启 NPU 硬件调度：rknn_init 时指定 NPU 核心

八、完整流程总结

1. YOLOv5 训练 → export 导出简化 ONNX（无 grid、无内置 NMS）

2. RKNN Toolkit2 加载 ONNX，配置归一化 + 校准集做 INT8 量化生成 rknn

3. 传输 rknn 模型至 RK3588 开发板，部署 RKNN runtime 库

4. 板端 C++/Python 加载模型，图片预处理→NPU 推理→手动解码 YOLO 输出 + NMS

5. 调优 anchor、置信阈值、IOU 阈值提升检测精度与速度

家具维修培训