保姆级避坑指南：在RK3588上从零部署YOLOv5模型（含环境配置、模型转换全流程）-三亩地-编程学习日记

保姆级避坑指南：在RK3588上从零部署YOLOv5模型（含环境配置、模型转换全流程）

1. 环境配置：避开版本冲突的雷区

第一次在RK3588上部署YOLOv5时，环境配置就像拆盲盒——你永远不知道下一个报错会是什么。我花了整整三天时间才摸清所有依赖库的版本玄机，这里把踩过的坑全部总结出来。

关键依赖版本清单：

组件名称	推荐版本	常见冲突版本	报错示例
numpy	1.22.0	≥1.24.0	AttributeError: numpy.int
pillow	9.5.0	≥10.0.0	OSError: decoder error
opencv-python	4.5.4.60	自动安装最新版	ImportError: undefined symbol
onnxruntime	1.12.0	≥1.15.0	TypeError: forward() got an unexpected keyword argument

提示：强烈建议使用conda创建隔离环境，执行以下命令初始化基础环境：

conda create -n rk3588_yolo python=3.8 conda activate rk3588_yolo pip install numpy==1.22.0 pillow==9.5.0

GPU用户需要特别注意CUDA工具链的匹配问题。我的血泪教训是：先装CUDA再装PyTorch！典型错误流程会导致torch.cuda.is_available()永远返回False。正确的安装顺序应该是：

通过nvidia-smi确认驱动支持的CUDA版本
到PyTorch官网获取对应版本的安装命令
单独安装torch后再处理其他依赖

2. 模型转换：从PyTorch到RKNN的生死时速

2.1 PT→ONNX转换的隐藏陷阱

使用官方export.py转换时，90%的失败都源于这两个参数：

python export.py --weights best.pt --img 640 --batch 1 --include onnx --rknpu RK3588

必须添加--rknpu RK3588参数！否则生成的ONNX模型会缺少NPU专用算子。转换成功后，用Netron检查输出层应该看到三个检测头（如下图示）。如果只有一个输出节点，说明转换过程有问题。

常见错误排查表：

错误现象	可能原因	解决方案
ONNX模型无法加载	onnxruntime版本不匹配	pip install onnxruntime==1.12.0
输出维度异常	未指定RK3588目标平台	添加--rknpu RK3588参数
转换过程卡死	显存不足	添加--batch 1参数降低负载

2.2 ONNX→RKNN的量子力学

这个阶段最大的坑在于：转换环境和推理环境必须完全隔离！我强烈建议新建一个纯净的Python3.10环境，因为RKNN Toolkit 2对依赖版本极其敏感。

转换脚本的典型配置示例：

# yolo_ppyolo.yml关键配置 model_path: ./best.onnx target_platform: rk3588 quantize: True dataset: ./dataset.txt # 量化用的校准数据集 output_dir: ./output

警告：量化过程需要准备至少100张校准图片，建议从训练集随机抽取。空跑量化会导致模型精度暴跌！

3. RK3588部署实战：那些手册没写的细节

3.1 系统级依赖的暗礁

开发板上必须安装这两个关键库：

# NPU驱动库 git clone https://github.com/rockchip-linux/rknpu2 # 图像处理库 git clone https://github.com/airockchip/librga

编译时最容易被忽略的是内存分配问题。RK3588的NPU需要连续内存空间，建议在运行前执行：

echo 2048 > /proc/sys/vm/overcommit_memory

3.2 推理性能调优秘籍

通过实测发现的黄金参数组合：

// 在yolo.h中调整这些参数 #define CONF_THRESH 0.25 // 置信度阈值 #define NMS_THRESH 0.45 // NMS阈值 #define OBJ_CLASS_NUM 80 // 类别数必须准确 #define PROP_BOX_SIZE 85 // 每个检测框数据长度

性能对比数据：

量化类型	推理耗时(ms)	内存占用(MB)	mAP@0.5
FP32	42.3	156	0.872
INT8	18.7	89	0.851
未量化	39.5	143	0.869

4. 视频流处理：避开MPP库的天坑

处理视频流时，99%的人都会卡在librockchip_mpp.so这个幽灵文件上。正确的处理姿势是：

# 进入MPP库目录 cd /usr/lib/aarch64-linux-gnu/ # 删除无效软链接 sudo rm librockchip_mpp.so # 重建有效链接 sudo ln -s librockchip_mpp.so.1 librockchip_mpp.so

视频推理的黄金命令模板：

# H264视频流处理 ./rknn_yolov5_video_demo model.rknn input.h264 264 # 实时摄像头处理 ./rknn_yolov5_video_demo model.rknn /dev/video0 0

记得提前用ffmpeg转换视频格式：

ffmpeg -i input.mp4 -c:v libx264 -preset fast -crf 23 output.h264

日记详情

保姆级避坑指南：在RK3588上从零部署YOLOv5模型（含环境配置、模型转换全流程）