RK3588部署YOLOv5s：环境搭建与ONNX模型获取全指南

1. 为什么环境搭建这一步值得单独拎出来讲很多人拿到 RK3588 开发板之后第一反应是直接找现成的模型转换脚本跑通了就完事。我一开始也是这个思路结果在环境搭建上反复折腾了将近两天踩的坑比后面模型转换加起来还多。所以这一篇我打算把环境搭建与模型获取这个看起来最没技术含量的环节彻底讲透因为它是整条链路的地基地基没打牢后面每一步都会以各种奇怪的方式报错。先把这一篇要解决的问题说清楚我们要在一台开发主机上准备好能够把 YOLOv5s 的 PyTorch 权重导出成 ONNX 的完整工具链同时把 RK3588 板端的运行环境系统、NPU 驱动、推理库确认到位。这两件事一件在 PC 侧一件在板端中间靠 ONNX 这个格式做桥梁。关键词里的 RK3588、YOLOv5s、环境搭建、模型获取、ONNX基本就是这一篇的全部主线。适合谁看如果你手上有一块 RK3588 的板子不管是核心板加底板还是整机想跑目标检测但不确定从哪一步开始动手那这篇就是给你写的。如果你已经跑通过一次但每次换机器都要重新查文档这篇也可以当作一份可复现的清单。我不假设你有嵌入式背景但假设你会基本的 Linux 命令行操作。在正式开始之前先明确一个心态上的问题环境搭建不是装完就行而是装完要能验证。我见过太多人装完 PyTorch 就以为万事大吉结果导出 ONNX 的时候发现 torch 版本和 onnx 版本不匹配或者导出成功但算子不被支持。所以这一篇的每一个环节我都会给出对应的验证方法装完立刻验不要攒到最后一起调。2. PC 侧工具链PyTorch 与 ONNX 导出环境的搭建逻辑2.1 为什么推荐在 WSL 或原生 Linux 下做导出先说一个很现实的问题YOLOv5 的官方仓库在 Windows 原生环境下虽然能跑但导出 ONNX 这一步经常会遇到路径分隔符、文件锁、编码之类的小毛病。我实测下来最省心的方案是在 WSL2Windows Subsystem for Linux里做或者直接用一台 Ubuntu 机器。WSL 的好处是你不用装双系统Windows 的文件还能通过/mnt/c/访问导出完的 ONNX 直接拖到 Windows 侧用工具看结构。这里要澄清一个常见误解WSL 不是虚拟机它和 Windows 共享内核接口所以 GPU 直通如果你要用 CUDA 加速训练或导出在 WSL2 里是支持的但需要装对应的驱动。不过对于 YOLOv5s 这种小模型导出 ONNX 这一步其实用 CPU 就够了没必要折腾 GPU。我自己的做法是训练和导出都在 WSL 里用 CPU 跑YOLOv5s 导出一次也就十几秒完全能接受。如果你坚持用 Windows 原生环境也不是不行但建议把项目放在纯英文、无空格的路径下比如D:\work\yolov5避免中文路径带来的编码问题。这个坑我在早期项目里踩过导出的 ONNX 文件名带中文后面板端加载直接报找不到文件。2.2 Python 环境隔离conda 还是 venvPython 环境隔离这件事我的建议是如果你已经在用 conda就继续用 conda如果没装过直接用 Python 自带的 venv 就够了没必要为了这一个项目去装一个几百兆的 conda。YOLOv5 的依赖不算复杂venv 完全能hold住。具体操作上我习惯在项目根目录下建一个虚拟环境这样环境跟着项目走删项目的时候环境一起删不会污染全局。命令大概是这样cd ~/work python3 -m venv yolov5_env source yolov5_env/bin/activate激活之后命令行前面会出现(yolov5_env)的标识这时候装的包都只在这个环境里生效。这里有个细节Python 版本建议用 3.8 到 3.10 之间。3.11 及以上在某些老版本的 torch 上会有兼容问题我实测 3.9 和 3.10 最稳。你可以用python3 --version先确认一下。提示如果你用的是 Ubuntu 22.04系统自带的 Python 是 3.10直接用就行。如果是 20.04自带 3.8也没问题。不要为了追新去装 3.12YOLOv5 的某些依赖在 3.12 上还没跟上。2.3 安装 PyTorch版本选择的取舍PyTorch 的安装是这一步的核心。很多人直接去官网复制最新的安装命令结果装了个 2.x 的最新版然后发现 YOLOv5 的某些老代码不兼容。我的建议是不要盲目追新选一个经过验证的稳定组合。我目前用得比较顺的组合是 PyTorch 1.13.1 torchvision 0.14.1CPU 版本。安装命令CPU 版是pip install torch1.13.1 torchvision0.14.1 --index-url https://download.pytorch.org/whl/cpu为什么选这个版本因为 YOLOv5 的官方 requirements 里对 torch 的版本要求比较宽松但导出 ONNX 用到的torch.onnx.export接口在 1.13 这个版本上非常稳定算子导出行为也和我后面要用的转换工具对得上。如果你装的是 2.x导出出来的 ONNX 可能会带一些新的算子属性后面转换工具不认反而增加麻烦。当然如果你有 GPU 并且想用 GPU 导出可以把--index-url换成对应的 CUDA 版本地址。但如前所述YOLOv5s 导出用 CPU 足够我建议先用 CPU 版把流程跑通有需要再换。装完之后立刻验证python -c import torch; print(torch.__version__); print(torch.cuda.is_available())如果输出了版本号并且cuda.is_available()返回 FalseCPU 版正常说明装好了。2.4 ONNX 与 onnxruntime两个容易混淆的包这里要专门讲一下 ONNX 和 onnxruntime 的区别因为关键词里也提到了这个概念而且我见过不少人搞混。ONNX 本身是一个格式标准你可以把它理解成一种模型交换格式就像图片里的 PNG。而onnx这个 Python 包是操作 ONNX 格式的工具库用来加载、检查、修改 ONNX 模型。onnxruntime则是推理引擎用来实际运行 ONNX 模型做推理。一个是编辑工具一个是播放器职责完全不同。在我们的链路里onnx包主要用来做导出后的模型检查和简化onnxruntime用来在 PC 侧验证导出的模型能不能正常推理。两个都要装pip install onnx1.14.0 onnxruntime1.15.1版本上onnx 1.14 和 torch 1.13 配合得很好。onnxruntime 1.15 支持 CPU 推理验证足够用。装完之后可以这样验证python -c import onnx; print(onnx.__version__) python -c import onnxruntime; print(onnxruntime.__version__)2.5 获取 YOLOv5 源码与权重环境装好之后接下来是拿代码和权重。YOLOv5 的官方仓库直接 clone 下来就行git clone https://github.com/ultralytics/yolov5.git cd yolov5 pip install -r requirements.txt这里有个坑requirements.txt里会尝试安装它指定版本的 torch可能会把你刚装好的版本覆盖掉。我的做法是先注释掉 requirements 里的 torch 和 torchvision 两行再执行安装这样就不会动我已经装好的版本。装完之后再确认一次 torch 版本没变。权重方面YOLOv5s 的预训练权重可以从官方 release 页面下载文件名是yolov5s.pt。下载后放到项目根目录。验证权重能不能正常加载python -c import torch; m torch.load(yolov5s.pt, map_locationcpu); print(type(m))如果输出的是一个字典或者模型对象说明权重没问题。这一步看起来简单但我遇到过下载不完整导致加载报错的情况所以验一下不亏。3. 从 PyTorch 到 ONNX导出这一步的细节决定成败3.1 导出命令背后的参数含义YOLOv5 仓库自带导出脚本一条命令就能导出 ONNXpython export.py --weights yolov5s.pt --include onnx --img 640 --batch 1 --opset 12这条命令看着简单但每个参数都有讲究我逐个拆开讲。--weights指定权重文件这个不用多说。--include onnx表示导出 ONNX 格式YOLOv5 还支持导出其他格式但我们这条链路只要 ONNX。--img 640指定输入图片尺寸YOLOv5s 默认是 640x640这个尺寸要和后面板端推理时保持一致否则精度会对不上。--batch 1指定 batch size 为 1因为板端推理通常是单张图batch 设大了反而增加内存占用。--opset 12是 ONNX 的算子集版本这个非常关键。为什么选 opset 12因为 RK3588 的 NPU 转换工具对 opset 版本有要求太高了不支持太低了某些算子表达不出来。opset 12 是一个比较稳妥的中间值我实测下来转换成功率最高。如果你用默认的 opset可能是 17 或更高转换工具大概率会报不支持的算子。3.2 导出后的模型检查别跳过这一步导出完成后会在yolov5s.onnx旁边生成一个文件。这时候不要急着拿去转换先用 onnx 包检查一下模型结构import onnx model onnx.load(yolov5s.onnx) onnx.checker.check_model(model) print(输入:, [i.name for i in model.graph.input]) print(输出:, [o.name for o in model.graph.output])check_model会检查模型是否符合 ONNX 规范有问题会直接报错。打印输入输出是为了确认模型的输入输出节点名字后面板端推理时要靠这些名字来喂数据和取结果。我踩过的一个坑是导出时如果用了--dynamic参数动态 batch输出节点的名字会带一些动态维度标记后面转换工具处理起来更麻烦。所以除非你确实需要动态 batch否则不要加这个参数固定 batch 1 最省事。3.3 用 onnxruntime 做一次 PC 侧推理验证检查完结构还要验证模型真的能跑。用 onnxruntime 加载模型喂一张测试图看能不能输出结果import onnxruntime as ort import numpy as np sess ort.InferenceSession(yolov5s.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(输出数量:, len(outputs)) for o in outputs: print(输出形状:, o.shape)如果这一步能正常输出说明模型本身是健康的。YOLOv5s 的输出通常是三个不同尺度的特征图形状类似(1, 25200, 85)这种具体取决于版本。这一步的意义在于把模型问题和板端问题隔离开。如果 PC 侧都跑不通那板端肯定也跑不通先在这里解决掉。注意这里用的是随机数据只是为了验证模型能跑通不代表推理结果有意义。真正的精度验证要等板端跑起来之后用真实图片做。4. RK3588 板端环境系统、驱动与推理库的确认4.1 系统镜像的选择与烧写板端环境的第一步是确认系统。RK3588 常见的系统有 Ubuntu 20.04 和 Ubuntu 22.04 两种我建议用 Ubuntu 20.04因为 Rockchip 官方提供的 NPU 相关工具和库在 20.04 上验证得最充分。22.04 也能用但偶尔会遇到依赖版本对不上的问题。烧写系统用 Rockchip 的烧录工具具体流程是板子进入烧录模式通常是按住某个按键再上电然后用 USB 线连到 PC烧录工具识别到设备后选择镜像文件写入。这个过程各个板厂的操作略有差异以你手上板子的文档为准。烧写完成后第一次启动建议接串口或者 HDMI 显示器确认系统能正常起来网络能通。网络这一步很重要因为后面装推理库、传模型文件都要靠网络或者 U 盘。4.2 确认 NPU 驱动是否就位RK3588 的 NPU 是它的核心卖点但 NPU 要能用驱动必须就位。确认方法很简单看设备节点ls /dev/rknpu*如果能看到类似/dev/rknpu的设备节点说明驱动加载了。如果没有可能需要更新内核或者手动加载驱动模块。不同板厂的镜像在这块差异较大有的出厂就带有的需要自己编译内核。另一个确认方式是看内核日志dmesg | grep -i rknpu如果能看到 NPU 初始化的日志说明驱动工作正常。这一步如果过不了后面所有 NPU 推理都无从谈起所以务必先确认。4.3 推理库的安装rknpu2 与相关运行时RK3588 上跑 ONNX 模型实际上不是直接跑 ONNX而是要把 ONNX 转换成 RKNN 格式然后用 RKNN 的运行时来推理。所以板端需要装的是 RKNN 的运行时库也就是 rknpu2 相关的组件。这些库通常以 deb 包或者预编译的 so 库形式提供。安装方式取决于你的镜像有的镜像已经预装了有的需要手动拷贝。确认方法是ls /usr/lib/librknn*如果能看到librknnrt.so之类的文件说明运行时库在。同时还要确认 Python 的 rknn 包能不能导入python3 -c from rknnlite.api import RKNNLite; print(ok)注意这里用的是rknnlite这是轻量级的 Python 接口适合在板端做推理。如果导入报错说明 Python 侧的 rknn 包没装好需要从对应的 whl 文件安装。4.4 板端 Python 环境的注意事项板端的 Python 环境不建议搞得太复杂。我的做法是直接用系统自带的 Python3装必要的包就行不要再去建虚拟环境因为板端资源有限多一层环境反而增加不确定性。需要装的包主要是 numpy 和 opencv 的 Python 绑定用来读图和预处理。opencv 在板端建议用系统包管理器装不要用 pip 装完整版因为 pip 版会带一堆用不上的依赖编译还慢sudo apt install python3-opencv python3-numpy装完之后验证一下python3 -c import cv2; import numpy; print(cv2.__version__, numpy.__version__)能打印出版本号就说明板端的基础环境齐了。到这里PC 侧和板端的环境就都准备好了下一篇就可以进入真正的模型转换环节。5. 环境搭建中那些文档不会告诉你的坑5.1 版本矩阵一张表说清楚各组件的关系环境搭建最怕的就是版本乱配。我把这一篇涉及的关键组件和推荐版本整理成一张表你照着对就行组件推荐版本作用验证命令Python3.9 / 3.10运行环境python3 --versionPyTorch1.13.1模型加载与导出python -c import torch; print(torch.__version__)torchvision0.14.1配套视觉库随 torch 一起验证onnx1.14.0ONNX 模型操作python -c import onnx; print(onnx.__version__)onnxruntime1.15.1PC 侧推理验证python -c import onnxruntime; print(onnxruntime.__version__)opset12导出算子集版本导出命令参数板端系统Ubuntu 20.04板端运行环境lsb_release -arknnlite随镜像板端推理接口python3 -c from rknnlite.api import RKNNLite这张表里的版本组合是我实测跑通的如果你用其他版本大概率也能跑但遇到问题时优先怀疑版本不匹配。5.2 网络问题pip 装包慢怎么办pip 装包慢是常态尤其是 torch 这种大包。我的建议是配置国内镜像源能快很多。配置方法是在~/.pip/pip.conf里写入[global] index-url https://pypi.tuna.tsinghua.edu.cn/simple但要注意torch 的 CPU 版本如果从镜像源装有时候会装到不匹配的版本。所以我的做法是torch 和 torchvision 从官方源装用前面给的--index-url其他小包从镜像源装。这样兼顾速度和准确性。5.3 导出时的常见报错与处理导出 ONNX 时最常见的报错是算子不支持比如某个算子在当前 opset 下没有对应的实现。遇到这种报错第一反应是降 opset 版本从 12 降到 11 试试。如果还不行可能是 YOLOv5 的某个新版本引入了新算子这时候可以换一个稍旧的 YOLOv5 版本。另一个常见问题是导出后模型文件特别大比如几百兆。这通常是因为导出时没有做常量折叠或者带了训练相关的节点。YOLOv5 的导出脚本默认会做简化如果没做可以手动用onnxsim工具简化pip install onnxsim onnxsim yolov5s.onnx yolov5s_sim.onnx简化后的模型通常能小不少而且结构更干净后面转换更顺利。5.4 板端文件传输别用 U 盘来回插板端和 PC 之间传文件最方便的方式是 scp 或者 rsync前提是板端开了 ssh 服务。命令很简单scp yolov5s.onnx user板子IP:/home/user/如果板端没开 ssh可以用 Python 起一个临时 HTTP 服务板端用 wget 下载# PC 侧 python3 -m http.server 8000 # 板端 wget http://PC的IP:8000/yolov5s.onnx这个方法我用了很多次比插 U 盘快多了尤其是模型文件不大的时候。6. 环境就绪的判断标准与下一步衔接怎么判断环境真的搭好了我给自己定了一个检查清单全部通过才算过关PC 侧torch、onnx、onnxruntime 都能 import版本符合预期。PC 侧YOLOv5s 权重能加载导出 ONNX 成功onnxruntime 能跑通推理。板端系统正常启动网络通NPU 设备节点存在。板端rknnlite 能导入opencv 和 numpy 能用。这四条都过了环境搭建这一关就算过了。任何一条没过都不要急着往下走因为后面的模型转换会放大这些问题。我个人在实际操作中的体会是环境搭建最忌讳差不多就行。我见过太多人因为 torch 版本差了一个小版本导出 ONNX 时算子行为不一致最后在板端排查了半天才发现是源头的问题。所以宁可在这里多花半小时把版本对齐、把验证做全也不要带着隐患往下走。下一篇会进入模型转换的核心环节把导出的 ONNX 转成 RKNN这里面涉及到量化、算子支持、精度对齐等一堆细节也是整条链路里最容易出问题的部分。环境这一关过了后面的路会顺很多。