从YOLOv5到RKNN：零冲突转换YOLOv5模型至RK3588 NPU全指南

从YOLOv5到RKNN：零冲突转换YOLOv5模型至RK3588 NPU全指南

在嵌入式AI领域，将训练好的深度学习模型高效部署到边缘设备的NPU（神经网络处理器）上是提升性能的关键。本文将详细介绍如何在Ubuntu 20.04环境下，将YOLOv5l模型（.pt文件）通过ONNX中间格式，最终转换为适用于RK3588 NPU的RKNN模型（.rknn文件），并全程采用环境隔离技术确保无依赖冲突。

一、准备工作：构建干净的工作环境

环境污染是模型转换过程中最常见的问题之一，因此我们首先创建一个全新的工作区，确保所有操作在干净的环境中进行。

1. 清理与创建工作区

打开终端，执行以下命令清理可能存在的旧工作区并创建新的工作目录：

# 回到主目录
cd ~
# 删除旧的工作区（如果存在）
rm -rf rknn_workspace
# 创建新工作区并进入
mkdir rknn_workspace
cd rknn_workspace

2. 准备核心文件

在新工作区内，我们需要准备四个关键组成部分：YOLOv5源代码、预训练模型、校准图片集和图片列表文件。

# 1. 克隆YOLOv5官方仓库
git clone https://github.com/ultralytics/yolov5.git# 2. 下载yolov5l预训练模型
wget https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5l.pt# 3. 创建图片文件夹（用于模型量化校准）
mkdir images# 4. 生成图片列表文件（后续量化会用到）
find "$(pwd)/images" -name "*.jpg" > dataset.txt
find "$(pwd)/images" -name "*.png" >> dataset.txt

完成后，执行ls命令检查，确保工作区内包含以下内容：

• yolov5（文件夹）
• yolov5l.pt（模型文件）
• images（文件夹）
• dataset.txt（文件）

二、任务一：导出ONNX模型（隔离环境操作）

ONNX（Open Neural Network Exchange）是一种通用的模型中间格式，我们首先将PyTorch模型转换为ONNX格式。为避免依赖冲突，这一步将在独立的虚拟环境中进行。

1. 创建并激活虚拟环境

# 进入YOLOv5目录
cd yolov5
# 创建虚拟环境
python3 -m venv onnx_export_venv
# 激活虚拟环境
source onnx_export_venv/bin/activate

激活成功后，终端提示符前会显示(onnx_export_venv)，表示当前处于隔离环境中。

2. 安装依赖库

为加快下载速度并确保版本兼容，我们使用清华源并锁定特定版本的ONNX库：

# 配置清华源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 升级pip
pip install --upgrade pip
# 安装YOLOv5依赖
pip install -r requirements.txt
# 安装特定版本的ONNX（与RKNN工具兼容）
pip install onnx==1.12.0

3. 导出ONNX模型

将预训练模型复制到当前目录并执行导出命令：

# 复制模型文件到当前目录
cp ../yolov5l.pt .# 导出ONNX模型（指定opset 11以确保兼容性）
python export.py --weights yolov5l.pt --include onnx --opset 11

4. 整理结果并清理环境

导出成功后，会生成yolov5l.onnx文件。我们将其移至工作区根目录，然后销毁当前虚拟环境（使命已完成）：

# 将ONNX模型移至工作区根目录
mv yolov5l.onnx ../
# 退出虚拟环境
deactivate
# 返回工作区根目录
cd ..
# 删除虚拟环境（释放空间）
rm -rf ./yolov5/onnx_export_venv

此时，工作区根目录应已出现yolov5l.onnx文件，第一步转换完成。

三、任务二：转换为RKNN模型（独立隔离环境）

接下来，我们在全新的虚拟环境中使用RKNN-Toolkit2将ONNX模型转换为RK3588可识别的RKNN模型。

1. 创建并激活新虚拟环境

# 确保在rknn_workspace目录下
python3 -m venv rknn_convert_venv
# 激活环境
source rknn_convert_venv/bin/activate

终端提示符前会显示(rknn_convert_venv)，表示进入新的隔离环境。

2. 安装RKNN-Toolkit2

# 配置清华源
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 升级pip
pip install --upgrade pip
# 安装指定版本的RKNN-Toolkit2（与RK3588兼容）
pip install rknn-toolkit2==2.3.2

该命令会自动安装所有依赖的兼容版本库，无需手动干预。

3. 准备转换脚本

创建convert_rknn.py脚本，用于执行模型转换：

nano convert_rknn.py

复制以下代码到文件中：

from rknn.api import RKNNif __name__ == '__main__':rknn = RKNN(verbose=True)print('--> Config model')rknn.config(mean_values=[[0, 0, 0]],std_values=[[255, 255, 255]],target_platform='rk3588'  # 指定目标平台为RK3588)print('done')print('--> Loading model')ret = rknn.load_onnx(model='./yolov5l.onnx')if ret != 0:print('!!! Load yolov5l.onnx failed!')exit(ret)print('done')print('--> Building model')# 启用量化，并指定校准数据集ret = rknn.build(do_quantization=True, dataset='./dataset.txt')if ret != 0:print('!!! Build yolov5l.rknn failed!')exit(ret)print('done')print('--> Export rknn model')ret = rknn.export_rknn('./yolov5l.rknn')if ret != 0:print('!!! Export yolov5l.rknn failed!')exit(ret)print('done')rknn.release()

保存并退出（按Ctrl+O，回车，再按Ctrl+X）。

4. 准备量化校准图片

模型量化是提升NPU运行效率的关键步骤，需要20-30张代表性图片作为校准数据。如果没有现成图片，可以从视频中提取：

（1）安装OpenCV用于视频帧提取

pip install opencv-python

（2）创建视频帧提取脚本

nano extract_frames.py

复制以下代码：

import cv2
import os
import sys# 配置区 - 修改为你的视频路径
VIDEO_PATH = "/path/to/your/video.mp4"  # 替换为实际视频路径
OUTPUT_DIR = "images"
NUM_FRAMES_TO_EXTRACT = 30  # 提取30帧def extract_frames():if not os.path.exists(VIDEO_PATH):print(f"错误: 视频文件未找到! 路径: {VIDEO_PATH}")sys.exit(1)if not os.path.exists(OUTPUT_DIR):os.makedirs(OUTPUT_DIR)cap = cv2.VideoCapture(VIDEO_PATH)total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))if total_frames == 0:print("错误: 无法读取视频或视频为空。")cap.release()sys.exit(1)# 计算采样间隔，确保均匀取帧interval = total_frames // NUM_FRAMES_TO_EXTRACTif interval == 0:interval = 1print(f"视频总帧数: {total_frames}")print(f"计划提取 {NUM_FRAMES_TO_EXTRACT} 帧, 间隔 {interval} 帧。")frame_count = 0extracted_count = 0while cap.isOpened() and extracted_count < NUM_FRAMES_TO_EXTRACT:ret, frame = cap.read()if not ret:breakif frame_count % interval == 0:output_filename = os.path.join(OUTPUT_DIR, f"frame_{extracted_count:04d}.jpg")cv2.imwrite(output_filename, frame)print(f"已保存: {output_filename}")extracted_count += 1frame_count += 1cap.release()print(f"\n提取完成! 共保存 {extracted_count} 张图片到 '{OUTPUT_DIR}'。")if __name__ == "__main__":extract_frames()

（3）执行帧提取并更新数据集列表

# 修改脚本中的VIDEO_PATH为实际视频路径后执行
python3 extract_frames.py# 更新dataset.txt文件
find "$(pwd)/images" -name "*.jpg" > dataset.txt
find "$(pwd)/images" -name "*.png" >> dataset.txt

5. 执行RKNN转换

一切准备就绪后，运行转换脚本：

python3 convert_rknn.py

转换过程会持续几分钟，成功完成后会显示类似以下的日志：

I rknn-toolkit2 version: 2.3.2
...
I rknn building done.
done
--> Export rknn model
done

此时，工作区根目录会生成yolov5l.rknn文件，这就是RK3588 NPU可直接使用的模型文件。

四、常见问题与解决方案

1. 错误：Dataset file ./dataset.txt not found!

   • 原因：未生成数据集列表文件或文件路径错误
   • 解决：确保images文件夹中有图片，并重新执行dataset.txt生成命令

2. ONNX导出失败

   • 原因：YOLOv5版本与依赖库不兼容
   • 解决：使用本文指定的YOLOv5仓库和onnx==1.12.0版本

3. RKNN转换时量化失败

   • 原因：校准图片数量不足或与模型场景不匹配
   • 解决：确保提供20-30张与模型应用场景相符的图片（如检测交通场景则提供交通图片）

五、总结与后续步骤

通过本文介绍的两步隔离环境转换法，我们成功将YOLOv5l模型转换为RK3588 NPU适用的RKNN模型，全程避免了依赖冲突问题。转换后的yolov5l.rknn文件可直接部署到RK3588设备。

后续步骤建议：

1. 将yolov5l.rknn传输到已安装Ubuntu系统的RK3588开发板
2. 使用RKNN-Toolkit2或RKNN Runtime API编写推理脚本
3. 在RK3588上测试模型性能与精度，必要时进行优化调整

这种隔离环境的转换方法不仅适用于YOLOv5，也可推广到其他深度学习模型的RKNN转换过程，为嵌入式AI部署提供了可靠的技术参考。