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

保姆级避坑指南在RK3588上从零部署YOLOv5模型含环境配置、模型转换全流程1. 环境配置避开版本冲突的雷区第一次在RK3588上部署YOLOv5时环境配置就像拆盲盒——你永远不知道下一个报错会是什么。我花了整整三天时间才摸清所有依赖库的版本玄机这里把踩过的坑全部总结出来。关键依赖版本清单组件名称推荐版本常见冲突版本报错示例numpy1.22.0≥1.24.0AttributeError: numpy.intpillow9.5.0≥10.0.0OSError: decoder erroropencv-python4.5.4.60自动安装最新版ImportError: undefined symbolonnxruntime1.12.0≥1.15.0TypeError: forward() got an unexpected keyword argument提示强烈建议使用conda创建隔离环境执行以下命令初始化基础环境conda create -n rk3588_yolo python3.8 conda activate rk3588_yolo pip install numpy1.22.0 pillow9.5.0GPU用户需要特别注意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 onnxruntime1.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_memory3.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)mAP0.5FP3242.31560.872INT818.7890.851未量化39.51430.8694. 视频流处理避开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