1. 为什么环境搭建这一步值得单独拿出来讲很多人拿到 RK3588 开发板之后第一反应是直接找现成的镜像烧进去跑个 demo看到摄像头出画面就觉得“部署完成了”。但真正要把 YOLOv5s 从零跑通环境搭建和模型获取这两步才是分水岭——它们决定了你后面是顺风顺水还是处处踩坑。我这次做的事情是在 RK3588 上从零部署 YOLOv5s 目标检测模型。整个链路包括PC 端训练环境准备、模型导出为 ONNX、ONNX 转 RKNN、板端推理验证。这一篇聚焦前两个环节环境搭建和模型获取。说白了就是把你写代码、训模型、导模型的那台机器先收拾利索再把 YOLOv5s 的权重文件拿到手并转成通用格式。适合谁看如果你手头有一块 RK3588 开发板想跑自己的检测模型但不确定 PC 端该装什么、模型该从哪来、ONNX 到底怎么导那这篇就是写给你的。如果你已经跑通过完整流程也可以对照看看有没有遗漏的细节。我自己的环境是 Windows 11 WSL2 Ubuntu 22.04这是目前比较主流的组合。纯 Linux 机器也可以步骤基本一致只是路径和包管理命令略有差异。2. 整体思路与方案选型2.1 为什么选 WSL2 而不是纯 Windows 或纯 Linux先说结论训练和模型导出放在 WSL2 的 Ubuntu 里板端操作通过串口或 SSH 在 Windows 侧完成。这个组合是我试过最顺手的。纯 Windows 下装 PyTorch 不是不行但 YOLOv5 官方仓库的依赖链在 Windows 上偶尔会出现编译问题尤其是pycocotools这类需要 C 扩展的包。纯 Linux 当然最干净但如果你日常办公在 Windows来回切换机器很麻烦。WSL2 的好处是文件系统互通、终端体验接近原生 Linux、GPU 直通如果你有 N 卡也支持。注意WSL2 默认的内存和 CPU 分配是动态的训练大模型时建议在.wslconfig里手动限制上限避免把 Windows 主机拖死。2.2 模型获取的两条路官方权重 vs 自己训练YOLOv5s 的模型获取有两种方式直接用官方预训练权重从 Ultralytics 的 release 页面下载yolov5s.pt适合快速验证部署链路。用自己的数据集训练基于官方权重做迁移学习得到针对你场景的best.pt。我建议第一次部署时先用官方权重跑通全链路确认 RKNN 转换和板端推理没问题之后再换成自己训练的模型。这样出问题时容易定位——是环境问题还是模型问题一目了然。2.3 为什么必须经过 ONNX 这一层RK3588 的 NPU 不能直接吃 PyTorch 的.pt文件。瑞芯微提供的 RKNN-Toolkit2 支持的输入格式里ONNX 是最通用、坑最少的一种。PyTorch → ONNX → RKNN 这条链路是目前社区验证最充分的方案。有人会问能不能跳过 ONNX 直接转 RKNN。理论上 RKNN-Toolkit2 也支持 Caffe、TensorFlow 等格式但 YOLOv5 的 PyTorch 实现转过去非常折腾ONNX 是中间表示里最稳的。而且 ONNX 本身可以用 Netron 可视化排查算子问题很方便。3. PC 端环境搭建实操3.1 WSL2 与 Ubuntu 的安装配置如果你还没装 WSL2在 Windows 终端里执行wsl --install -d Ubuntu-22.04装完之后建议做几件事第一更新系统包sudo apt update sudo apt upgrade -y第二安装基础编译工具sudo apt install -y build-essential cmake git wget curl第三配置 Python 环境。Ubuntu 22.04 自带 Python 3.10我建议用venv建独立虚拟环境不要污染系统 Pythonsudo apt install -y python3-pip python3-venv python3 -m venv ~/yolov5_env source ~/yolov5_env/bin/activate实操心得虚拟环境的名字不要用中文路径里也不要有空格。后面 RKNN-Toolkit2 的一些脚本对路径敏感中文路径会导致莫名其妙的报错。3.2 PyTorch 与 YOLOv5 依赖安装在虚拟环境激活状态下先装 PyTorch。如果你有 N 卡并且配置了 WSL2 的 CUDA 直通可以去 PyTorch 官网查对应 CUDA 版本的安装命令。如果没有 GPU装 CPU 版本也行只是训练会慢很多。pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu然后克隆 YOLOv5 仓库git clone https://github.com/ultralytics/yolov5.git cd yolov5 pip install -r requirements.txt这里有个细节requirements.txt里的onnx版本可能和你后面 RKNN-Toolkit2 要求的版本不一致。我的做法是先按 YOLOv5 的要求装导出 ONNX 成功之后再单独建一个环境装 RKNN-Toolkit2。两个环境分开避免依赖冲突。3.3 验证环境是否可用装完之后跑一下官方自带的检测脚本python detect.py --weights yolov5s.pt --source data/images/bus.jpg如果能在runs/detect/exp/下面看到带框的图片说明 PyTorch 环境和 YOLOv5 代码都没问题。这一步看起来简单但它是后面所有操作的基础。我见过有人跳过这步直接去导 ONNX结果报错时不知道是环境问题还是导出脚本问题。4. 模型获取与 ONNX 导出4.1 下载官方 YOLOv5s 权重官方权重在 Ultralytics 的 GitHub release 页面可以找到。直接下载yolov5s.pt放到 YOLOv5 仓库根目录即可。如果你要训练自己的模型把数据集按 YOLOv5 要求的格式组织好然后python train.py --img 640 --batch 16 --epochs 100 --data your_data.yaml --weights yolov5s.pt训练完成后最优权重在runs/train/exp/weights/best.pt。4.2 导出 ONNX 的关键参数YOLOv5 仓库自带export.py导出 ONNX 的命令是python export.py --weights yolov5s.pt --include onnx --img 640 --batch 1 --opset 12几个参数值得展开说--img 640输入分辨率。RK3588 的 NPU 对 640x640 支持很好不建议一上来就用更大的尺寸。--batch 1板端推理通常是单张batch 设 1 可以简化后续转换。--opset 12ONNX 算子集版本。opset 版本太高RKNN-Toolkit2 可能不支持某些算子太低又可能缺少必要算子。12 是我实测比较稳的版本。导出成功后会生成yolov5s.onnx。你可以用 Netron 打开看看网络结构确认输入输出节点名称。YOLOv5 默认的输出是三个检测头后面在 RKNN 转换时需要指定这些输出节点。4.3 ONNX 模型的检查与简化导出之后建议做两件事第一用onnxsim简化模型pip install onnxsim onnxsim yolov5s.onnx yolov5s_sim.onnx简化可以去掉一些冗余算子减小模型体积有时也能避免 RKNN 转换时的算子兼容问题。第二用 ONNX Runtime 验证模型能正常推理import onnxruntime as ort import numpy as np sess ort.InferenceSession(yolov5s_sim.onnx) input_name sess.get_inputs()[0].name dummy np.random.randn(1, 3, 640, 640).astype(np.float32) outputs sess.run(None, {input_name: dummy}) print([o.shape for o in outputs])如果输出形状符合预期通常是[1, 25200, 85]或三个分支说明 ONNX 模型是完好的。注意YOLOv5 不同版本的输出格式可能略有差异。有的版本输出是[1, 25200, 85]有的版本是三个独立输出。导出时留意终端打印的信息后面 RKNN 转换脚本要对应修改。5. 常见问题与排查技巧5.1 环境搭建阶段的典型报错问题现象可能原因解决方法pip install卡在 building wheel缺少编译依赖安装build-essential和对应开发库PyTorch 导入报 CUDA 相关错误CUDA 版本与 PyTorch 不匹配确认 WSL2 CUDA 直通配置或改用 CPU 版本git clone速度极慢网络问题配置代理或使用镜像源虚拟环境激活失败路径含中文或空格重建虚拟环境使用纯英文路径5.2 ONNX 导出阶段的坑最常见的问题是导出时报Unsupported operator。这通常是因为 opset 版本选得不对。我的经验是YOLOv5s 用 opset 12 基本不会出问题如果报错就降到 11 试试。另一个坑是动态轴。YOLOv5 的export.py默认会设置动态 batch 维度但 RK3588 部署时通常用固定 batch。可以在导出时加--dynamic参数控制或者导出后用onnxsim固定维度。5.3 模型文件管理的建议我习惯把模型文件按版本管理models/ yolov5s_v1/ yolov5s.pt yolov5s.onnx yolov5s_sim.onnx config.txtconfig.txt里记录导出参数、日期、对应的训练数据集版本。后面模型多了之后没有版本管理会非常混乱。6. 从 ONNX 到 RKNN 的衔接准备6.1 RKNN-Toolkit2 环境单独隔离前面说过RKNN-Toolkit2 的依赖和 YOLOv5 有冲突。我的做法是再建一个虚拟环境python3 -m venv ~/rknn_env source ~/rknn_env/bin/activate pip install rknn-toolkit2具体安装包从瑞芯微官方渠道获取注意选择与你的 Python 版本匹配的 wheel 文件。6.2 转换脚本的关键配置RKNN 转换的核心是配置文件里面要指定mean_values和std_valuesYOLOv5 通常是[[0,0,0]]和[[255,255,255]]target_platform填rk3588quantized_dtype首次转换建议先用w8a8或不做量化确认能跑通再尝试量化量化这一步坑很多尤其是 INT8 量化需要准备校准数据集。我建议第一次先导出非量化模型确认板端能推理之后再回头做量化优化。6.3 板端推理的初步验证RKNN 模型生成之后通过 ADB 或 SSH 推到板子上用瑞芯微提供的rknn_run示例程序跑一下。如果输出结果和 PC 端 ONNX Runtime 的结果接近说明整条链路是通的。这一步的验证非常重要。我见过有人 PC 端一切正常板端输出全是乱码最后发现是输入图像的预处理方式不一致——PC 端用了 letterbox板端直接 resize导致检测框全部偏移。7. 我踩过的几个印象深刻的坑第一个坑是 WSL2 的内存限制。默认配置下 WSL2 最多能用主机一半内存训练时如果 batch 设大了WSL2 会疯狂吃内存Windows 主机直接卡死。后来我在C:\Users\你的用户名\.wslconfig里加了[wsl2] memory16GB processors8重启 WSL 之后稳定多了。第二个坑是 ONNX 的输入节点名称。YOLOv5 导出的 ONNX 输入节点叫images但有些转换脚本默认找input导致报错。用 Netron 打开看一眼就能确认不要凭猜。第三个坑是模型文件路径。RKNN-Toolkit2 的某些版本对相对路径支持不好转换脚本里最好用绝对路径。这个问题排查起来很费时间因为报错信息不直接指向路径问题。8. 后续可以扩展的方向环境搭好、模型导出成功之后下一步就是 RKNN 转换和板端部署。如果你想让模型跑得更快可以研究一下 YOLOv5s 的轻量化——比如把 backbone 换成 MobileNet 系列或者用剪枝工具压缩通道数。RK3588 的 NPU 算力虽然不错但模型越小帧率越高功耗也越低。另外如果你要做多路视频输入RK3588 的 MIPI 接口和 SPI 接口配置也需要提前规划。这些内容我会在后续的部署篇里展开。最后分享一个小技巧每次修改环境或模型之后用pip freeze requirements_lock.txt把当前依赖版本冻结下来。后面环境崩了直接按这个文件重建比重装一遍快得多。这个习惯帮我省了至少两次重装系统的时间。