保姆级教程：在Ubuntu 20.04上从YOLOv5 v5.0训练到RK3588 NPU部署的完整避坑指南

从零实现YOLOv5模型训练到RK3588 NPU加速部署的全链路实战

第一次接触嵌入式AI开发时，我被RK3588芯片的NPU算力吸引，但整个部署流程的复杂性让我踩了不少坑。本文将用最直白的方式，带你完整走通从Ubuntu环境配置、YOLOv5模型训练、ONNX转换到RKNN模型部署的全过程，特别针对那些官方文档没讲清楚的细节问题。

1. 环境准备与YOLOv5模型训练

在RK3588上部署AI模型的第一步，是准备好训练环境并生成符合要求的模型文件。这里我们选择YOLOv5 v5.0版本，因为它在精度和速度平衡性上表现优异，且与RKNN-Toolkit2的兼容性经过验证。

1.1 搭建Python训练环境

推荐使用conda管理环境以避免依赖冲突：

conda create -n yolov5 python=3.8 conda activate yolov5 pip install torch==1.8.0 torchvision==0.9.0 -f https://download.pytorch.org/whl/torch_stable.html git clone https://github.com/ultralytics/yolov5 -b v5.0 cd yolov5 pip install -r requirements.txt

常见问题排查：

• 如果遇到PyTorch安装失败，可以先尝试安装CPU版本
• OpenCV版本建议锁定在4.5.4以下，避免后续RKNN转换时的兼容性问题

1.2 数据集准备与训练技巧

YOLOv5支持多种标注格式，这里以COCO格式为例：

datasets/ └── custom/ ├── images/ │ ├── train/ │ └── val/ └── labels/ ├── train/ └── val/

训练命令示例：

python train.py --img 640 --batch 16 --epochs 100 --data data/custom.yaml --cfg models/yolov5s.yaml --weights '' --name my_model

关键参数说明：

注意：训练时不要修改yolo.py中的forward函数，这个hack只在模型转换阶段需要

2. 模型转换：从PyTorch到RKNN

2.1 PyTorch到ONNX转换

首先导出ONNX模型：

python export.py --weights runs/train/my_model/weights/best.pt --img 640 --batch 1 --include onnx

必须进行的代码修改： 在导出前，需要修改models/yolo.py中的Detect类forward函数：

def forward(self, x): z = [] for i in range(self.nl): x[i] = self.m[i](x[i]) # 删除所有后处理逻辑 return x

这个修改是为了适应RKNN的运算特性，但要注意：

1. 修改后模型不能直接用于训练
2. 如果出现检测框异常，可以尝试给输出加sigmoid

2.2 ONNX到RKNN转换环境搭建

创建独立conda环境：

conda create -n rknn python=3.8 conda activate rknn git clone https://github.com/rockchip-linux/rknn-toolkit2 -b v1.5.2 cd rknn-toolkit2 pip install -r doc/requirements_cp38-1.5.2.txt pip install packages/rknn_toolkit2-1.5.2*.whl

安装验证：

import rknn print(rknn.__version__) # 应输出1.5.2

2.3 模型转换实战

使用官方示例代码修改转换脚本：

rknn.config(mean_values=[[0, 0, 0]], std_values=[[255, 255, 255]], target_platform='rk3588') rknn.load_onnx(model='best.onnx') ret = rknn.build(do_quantization=True, dataset='./dataset.txt') ret = rknn.export_rknn('./yolov5s.rknn')

关键配置项：

提示：如果转换失败，尝试关闭量化(do_quantization=False)先测试流程

3. RK3588开发板环境配置

3.1 基础系统准备

推荐使用官方提供的Ubuntu 20.04镜像。连接开发板：

sudo apt install adb adb devices # 确认设备连接

常见连接问题：

1. 确保使用TypeC0接口
2. 开发板需开启USB调试模式
3. 虚拟机需配置USB设备直通

3.2 NPU驱动与服务部署

从rknpu2仓库获取运行时库：

adb push librknnrt.so /usr/lib/ adb push librknn_api.so /usr/lib/ adb push rknn_server /usr/bin/ adb shell chmod +x /usr/bin/rknn_server adb shell rknn_server &

验证服务运行：

adb shell pgrep rknn_server # 应返回进程ID

4. 模型部署与性能优化

4.1 部署YOLOv5演示程序

克隆官方示例并修改：

git clone https://github.com/rockchip-linux/rknpu2 cd rknpu2/examples/rknn_yolov5_demo

需要修改的关键文件：

1. include/postprocess.h中的类别数量
2. model/coco_80_labels_list.txt中的类别名称
3. 将转换好的RKNN模型放入model/RK3588/

编译与运行：

./build-linux_RK3588.sh adb push install/rknn_yolov5_demo_Linux /data adb shell cd /data/rknn_yolov5_demo_Linux ./rknn_yolov5_demo model/RK3588/yolov5s.rknn model/test.jpg

4.2 批量推理实现

创建batch_process.sh脚本：

#!/bin/bash RKNN_MODEL="./model/RK3588/yolov5s.rknn" IMAGE_DIR="./images" for img in $(ls $IMAGE_DIR/*.jpg); do echo "Processing $img" ./rknn_yolov5_demo $RKNN_MODEL $img done

赋予执行权限并运行：

chmod +x batch_process.sh ./batch_process.sh

4.3 性能对比测试

在不同硬件上运行相同模型的性能数据：

优化建议：

1. 使用rknn.config()调整计算图优化级别
2. 尝试不同的量化策略
3. 合理设置NPU核心分配

5. 高级技巧与问题排查

5.1 模型精度下降解决方案

如果发现部署后检测精度明显下降：

1. 检查预处理参数是否与训练一致
2. 尝试关闭量化重新转换模型
3. 调整后处理参数（conf_thresh, nms_thresh）

// 修改include/postprocess.h中的参数 #define CONF_THRESH 0.25 #define NMS_THRESH 0.45

5.2 内存优化技巧

对于内存受限的场景：

rknn.config( optimization_level=1, # 减少内存占用 force_builtin_perm=True # 避免额外内存拷贝 )

5.3 多线程推理实现

示例代码片段：

#include <thread> void inference_thread(RKNN_MODEL* model, cv::Mat img) { // 推理代码 } int main() { std::vector<std::thread> workers; for (int i = 0; i < 4; ++i) { workers.emplace_back(inference_thread, &model, images[i]); } for (auto& t : workers) t.join(); }

在实际项目中，我发现RK3588的NPU对YOLOv5的深度可分离卷积支持特别好，适当调整模型结构可以获得更好的性能表现。比如将Focus层替换为常规卷积，在精度损失不大的情况下能显著提升推理速度。