1. 为什么环境搭建这一步值得单独拿出来讲很多人拿到 RK3588 开发板之后第一反应是直接找现成的镜像烧进去跑 demo能出画面就觉得大功告成。但真到要把 YOLOv5s 这种自定义模型塞进去跑的时候问题就全冒出来了PyTorch 版本对不上、ONNX 导出算子不支持、板端推理库和模型输入输出节点对不齐。我前后在 RK3588 上折腾过好几轮 YOLO 系列模型的部署踩过的坑基本都集中在“环境”和“模型获取”这两个看似最没技术含量的环节上。这篇是系列的第二部分专门讲环境搭建与模型获取。第一部分聊的是整体链路设计和硬件选型思路这一部分落地到具体操作PC 端怎么搭一个干净的 PyTorch 训练/导出环境YOLOv5s 的权重从哪来、怎么验证ONNX 怎么导出、导出时哪些参数必须盯死以及 RK3588 板端的基础运行环境怎么准备。整套流程走完你会得到一个可以在 PC 上正常推理、并且已经导出为 ONNX 的 YOLOv5s 模型为后续的 RKNN 转换和板端部署打好底子。适合谁看手上已经有 RK3588 开发板、想跑自己模型的人做过深度学习训练但没接触过端侧部署的人以及被 ONNX 导出各种报错折磨过的朋友。我尽量把每一步的“为什么”讲清楚而不是只丢一堆命令让你复制。2. 整体环境架构与方案选型思路2.1 三段式环境划分PC 训练端、转换端、板端在端侧部署这件事上最容易犯的错误就是把所有环境混在一台机器上。我的做法是明确分成三段PC 训练/导出端负责 YOLOv5s 的权重加载、验证、ONNX 导出。这台机器通常是带独立显卡的台式机或笔记本装完整的 PyTorch 生态。转换端负责把 ONNX 转成 RKNN。这一步可以在 PC 上做用 RKNN-Toolkit2也可以在板子上做用 RKNN-Toolkit-Lite2 或板端工具链。我倾向于在 PC 上转因为转换过程吃内存、需要反复调试PC 上效率高得多。板端运行端RK3588 上只装推理运行时RKNN Runtime和必要的系统依赖保持干净。为什么要这么分因为 PyTorch 的版本依赖非常“娇气”而 RKNN 工具链对 Python 版本、NumPy 版本又有自己的一套要求。混在一起装十有八九会出现“装了 RKNN 之后 PyTorch 导不出来了”或者“升级了 NumPy 之后 RKNN 转换报错”这类互相打架的问题。用 conda 或者 venv 把环境隔离是最省心的做法。2.2 为什么选 YOLOv5s 而不是 v8 或别的版本热词里能看到不少人在搜 rk3588部署yolov8YOLOv8 确实更新、精度也更好但我在 RK3588 上第一轮实践还是选 YOLOv5s原因很实际第一YOLOv5 的 ONNX 导出链路最成熟社区里针对 RKNN 的适配案例最多遇到问题好查。第二YOLOv5s 模型小约 7.2M 参数权重文件 14MB 左右RK3588 的 NPU 算力6 TOPS跑起来帧率很舒服。第三YOLOv8 的导出结构和后处理跟 v5 有差异第一次上手容易在“输出节点对不上”上卡住。等你把 v5 这条链路跑通了再换 v8 只是改几个导出参数的事。提示如果你明确只做 v8那环境搭建部分基本通用差异主要在导出脚本和后处理。建议先用 v5 把链路打通再迁移。2.3 版本锁定整个链路最容易被忽视的关键端侧部署最怕的就是“版本漂移”。我见过太多案例同样的代码今天能跑明天就报错原因就是某个依赖自动升级了。所以我的原则是所有关键依赖全部锁版本并且记录下来。下面这张表是我实测跑通的一套版本组合你可以直接参考环节组件版本说明PC 端Python3.8RKNN-Toolkit2 对 3.8 支持最好PC 端PyTorch1.13.1与 YOLOv5 兼容稳定PC 端torchvision0.14.1与 torch 1.13.1 配套PC 端ONNX1.12.0导出算子支持完善PC 端onnxruntime1.14.0用于验证 ONNX 推理转换端RKNN-Toolkit21.5.2支持 RK3588板端RKNN Runtime1.5.2与 Toolkit 版本对应板端系统Ubuntu 20.04官方适配成熟版本对应关系是硬约束尤其是 RKNN-Toolkit2 和板端 Runtime 必须版本一致否则会出现模型加载失败。这一点后面排查章节还会细说。3. PC 端 PyTorch 环境搭建实操3.1 用 conda 建一个干净的隔离环境我强烈建议用 conda 而不是系统 Python原因前面说了隔离。命令不复杂conda create -n yolov5_rknn python3.8 -y conda activate yolov5_rknn建完之后先确认 Python 版本python --version # 应该输出 Python 3.8.x这里有个小细节如果你用的是 WSL热词里 pytorch环境搭建wsl 搜索量很高conda 装完之后记得把 WSL 的内存限制调一下。默认 WSL2 会吃掉宿主机一半内存导出 ONNX 和后续转换时容易爆内存。在用户目录下建.wslconfig[wsl2] memory16GB processors8 swap8GB改完wsl --shutdown重启生效。这个配置我实测下来导出和转换过程稳定很多。3.2 安装 PyTorch 与依赖别直接 pip install torch新手最容易犯的错是直接pip install torch结果装了个最新版跟 YOLOv5 的代码不兼容。正确做法是去 PyTorch 官网找对应 CUDA 版本的安装命令。如果你机器没有 NVIDIA 显卡就装 CPU 版导出 ONNX 用 CPU 完全够。CUDA 11.7 对应的命令有显卡的情况pip install torch1.13.1cu117 torchvision0.14.1cu117 \ --extra-index-url https://download.pytorch.org/whl/cu117纯 CPU 的情况pip install torch1.13.1 torchvision0.14.1 \ --extra-index-url https://download.pytorch.org/whl/cpu装完验证一下import torch print(torch.__version__) print(torch.cuda.is_available()) # 有显卡应为 True然后装 YOLOv5 需要的其他依赖。这里注意不要直接pip install -r requirements.txt因为那个文件里会指定 torch 版本可能把你刚装好的覆盖掉。我的做法是手动装核心的几个pip install numpy1.23.5 opencv-python4.7.0.72 \ pyyaml6.0 tqdm4.65.0 matplotlib3.7.1 \ pandas1.5.3 seaborn0.12.2 onnx1.12.0 \ onnxruntime1.14.0NumPy 锁 1.23.5 是有原因的RKNN-Toolkit2 对 NumPy 版本敏感1.24 以上会有兼容性问题。这个坑我在转换阶段踩过提前锁好省事。3.3 获取 YOLOv5 源码与权重YOLOv5 的源码直接从官方仓库拉但要注意版本。我建议用 v6.2 或 v7.0 这两个 tag它们的导出逻辑稳定社区适配案例多。git clone https://github.com/ultralytics/yolov5.git cd yolov5 git checkout v7.0权重文件yolov5s.pt有两个来源一是官方 release 页面直接下载二是用脚本自动下载。我倾向于手动下载放到weights/目录因为自动下载有时候网络不稳下到一半断了还不好排查。mkdir -p weights # 把下载好的 yolov5s.pt 放到 weights/ 目录 ls -lh weights/yolov5s.pt # 正常应该是 14MB 左右拿到权重后第一件事是验证它能正常推理别急着导出。用官方自带的检测脚本跑一张图python detect.py --weights weights/yolov5s.pt \ --source data/images/bus.jpg --device cpu跑完在runs/detect/exp/下能看到带框的结果图。这一步能过说明 PyTorch 环境和权重都没问题。如果这一步就报错先别往下走把环境问题解决干净。注意detect.py 第一次运行会自动下载一些字体文件如果网络不通会卡住。可以提前把 Arial.ttf 放到缓存目录或者忽略这个警告不影响推理。3.4 环境自检清单在进入模型导出之前我习惯跑一个自检脚本把关键依赖的版本都打出来存成文件备查import torch, torchvision, numpy, onnx, onnxruntime, cv2 print(torch:, torch.__version__) print(torchvision:, torchvision.__version__) print(numpy:, numpy.__version__) print(onnx:, onnx.__version__) print(onnxruntime:, onnxruntime.__version__) print(opencv:, cv2.__version__) print(cuda available:, torch.cuda.is_available())把输出存成env_check.txt。后面如果出问题对照这个文件能快速定位是不是版本变了。这个习惯帮我省了无数次排查时间。4. YOLOv5s 模型获取与 ONNX 导出全流程4.1 导出前的模型结构确认导出 ONNX 之前得先搞清楚 YOLOv5s 的输出结构。很多人导出后板端跑不对就是因为不知道模型到底输出了什么。YOLOv5 默认导出三个输出头对应三个不同尺度的特征图形状分别是小目标[1, 255, 80, 80]中目标[1, 255, 40, 40]大目标[1, 255, 20, 20]这里的 255 是3 * (5 80)即 3 个 anchor、每个 anchor 5 个框参数xywh obj、80 个类别。输入是[1, 3, 640, 640]。为什么要在导出前确认这个因为 RKNN 转换时需要指定输入输出节点如果你不知道输出是什么形状后面根本没法配。而且 YOLOv5 的导出脚本有个--include onnx参数不同版本导出的输出节点命名可能不一样提前确认能避免踩坑。4.2 导出 ONNX 的关键参数逐个拆解YOLOv5 自带的export.py就能导出 ONNX但参数得配对。我常用的命令python export.py --weights weights/yolov5s.pt \ --include onnx \ --imgsz 640 640 \ --batch-size 1 \ --opset 12 \ --device cpu \ --simplify逐个说这些参数为什么这么设--imgsz 640 640输入分辨率。RK3588 的 NPU 对 640 这个尺寸支持很好而且 640 是 32 的倍数YOLOv5 的下采样要求输入能被 32 整除。如果你想用 320 或 416也可以但精度会降。--batch-size 1端侧推理基本都是单张batch 设 1 最省内存也避免动态 batch 带来的转换麻烦。--opset 12ONNX 算子集版本。这个很关键。opset 太高比如 17会引入 RKNN 不支持的算子太低比如 9又可能缺一些必要算子。opset 12 是我实测在 RK3588 上兼容性最好的版本。--device cpu导出用 CPU 就行用 GPU 导出有时候会有算子差异。--simplify调用 onnx-simplifier 做图优化去掉冗余节点。这个强烈建议开能显著减少转换时的算子问题。需要先装pip install onnx-simplifier0.4.17导出成功后会在weights/目录下生成yolov5s.onnx大小约 28MB。4.3 导出后的 ONNX 验证别跳过这一步导出完直接拿去转换是另一个常见错误。ONNX 文件可能“导出成功但推理错误”必须验证。我用 onnxruntime 跑一遍跟 PyTorch 的结果对比import onnxruntime as ort import numpy as np import torch # 加载 ONNX sess ort.InferenceSession(weights/yolov5s.onnx, providers[CPUExecutionProvider]) input_name sess.get_inputs()[0].name print(input name:, input_name) print(input shape:, sess.get_inputs()[0].shape) for out in sess.get_outputs(): print(output:, out.name, out.shape) # 造一个随机输入测试 dummy np.random.randn(1, 3, 640, 640).astype(np.float32) outputs sess.run(None, {input_name: dummy}) for i, o in enumerate(outputs): print(foutput {i} shape:, o.shape)正常应该打印出三个输出形状跟前面说的一致。如果输出数量不对或者形状是动态的显示为字符串而不是数字说明导出参数有问题得回去检查。提示如果输出形状里出现-1或batch这种动态维度转换 RKNN 时可能报错。解决办法是导出时确保 batch 固定为 1并且不要开 dynamic axes。4.4 用真实图片做端到端验证随机输入只能验证形状验证不了数值正确性。我还会用一张真实图片分别跑 PyTorch 和 ONNX对比输出差异import cv2 import numpy as np import torch import onnxruntime as ort img cv2.imread(data/images/bus.jpg) img cv2.resize(img, (640, 640)) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img img.transpose(2, 0, 1)[None].astype(np.float32) / 255.0 # PyTorch 推理 model torch.load(weights/yolov5s.pt, map_locationcpu)[model] model.eval() with torch.no_grad(): pt_out model(torch.from_numpy(img))[0].numpy() # ONNX 推理 sess ort.InferenceSession(weights/yolov5s.onnx, providers[CPUExecutionProvider]) onnx_out sess.run(None, {sess.get_inputs()[0].name: img})[0] # 对比最大差异 diff np.abs(pt_out - onnx_out).max() print(max diff:, diff)正常情况下 max diff 应该在 1e-4 到 1e-3 量级。如果差异很大比如 0.1 以上说明导出过程有问题可能是某个算子被错误转换了。这个验证步骤花不了几分钟但能帮你提前发现大问题。4.5 模型轻量化的一些前置考虑热词里 yolov5s模型轻量化 也是高频搜索。如果你后续打算做量化INT8在导出阶段就要留个心眼。INT8 量化需要校准数据集而校准数据的预处理方式必须和推理时完全一致。我的建议是导出 ONNX 时就把预处理归一化、resize固定下来别在板端再做额外处理。准备 100 到 200 张有代表性的校准图片覆盖你的实际场景。校准图片的尺寸、通道顺序、归一化方式跟推理输入严格对齐。这些在导出阶段想清楚后面量化会顺很多。量化本身是下一部分的内容这里先埋个伏笔。5. RK3588 板端基础环境准备5.1 系统选择与烧写要点RK3588 板端系统我推荐 Ubuntu 20.04官方适配最成熟RKNN Runtime 的安装包也最全。烧写用瑞芯微的烧录工具注意几个点第一烧写前确认板子的启动模式拨码开关在正确位置通常是 MaskROM 模式。第二USB 线要用质量好的劣质线会导致烧写中途断开。第三烧写完成后第一次启动会比较慢耐心等别以为卡死了就断电。系统起来之后先更新一下基础包sudo apt update sudo apt install -y python3-pip python3-dev cmake git \ libopencv-dev python3-opencv5.2 板端 Python 环境与 RKNN Runtime 安装板端的 Python 环境我建议直接用系统自带的 Python 3.8不要额外建 conda 环境因为 RKNN Runtime 的 wheel 包对系统 Python 支持最好。RKNN Runtime 的安装分两部分一是rknn_toolkit_lite2Python 接口二是底层的librknnrt.soC 库。安装包从官方仓库获取注意版本要和 PC 端 Toolkit2 一致。# 安装 Python 接口 pip3 install rknn_toolkit_lite2-1.5.2-cp38-cp38-linux_aarch64.whl # 底层库通常随系统镜像已包含确认一下 ls /usr/lib/librknnrt.so如果librknnrt.so不存在需要手动拷贝到/usr/lib/并执行sudo ldconfig。验证安装from rknnlite.api import RKNNLite rknn RKNNLite() print(RKNN Lite init ok)能打印出来就说明板端环境 OK 了。5.3 NPU 驱动版本确认RK3588 的 NPU 驱动版本会影响模型加载。查看驱动版本cat /sys/kernel/debug/rknpu/version输出的版本号要跟 RKNN Runtime 匹配。如果驱动太旧加载新版本转换的模型会失败。升级驱动通常需要重新烧写系统或者单独更新内核模块比较麻烦所以一开始就选对系统版本很重要。注意NPU 驱动版本和 RKNN Runtime 版本不匹配是板端部署最常见的失败原因之一。转换模型前先确认这两个版本能省掉大量排查时间。5.4 板端推理库的依赖检查RKNN Runtime 依赖一些系统库缺了会报libxxx.so not found。我习惯用ldd检查ldd /usr/lib/librknnrt.so | grep not found如果输出为空说明依赖齐全。如果有缺失根据提示装对应的库。常见的缺失是libgomp和libstdc一般apt install就能解决。6. 常见问题与排查技巧实录6.1 ONNX 导出报错速查表导出阶段的问题最集中我整理了一张速查表报错信息原因解决办法Unsupported ONNX opsetopset 版本过高降到 12Export failed: dynamic shape开了 dynamic axes关闭固定 batch1ModuleNotFoundError: onnx没装 onnxpip install onnx1.12.0simplify failedonnx-simplifier 版本不匹配装 0.4.17输出节点数量不对导出脚本版本问题换 v7.0 tagRuntimeError: CUDA out of memory用 GPU 导出加 --device cpu6.2 版本冲突的排查思路版本冲突是最难查的问题因为报错信息往往指向别处。我的排查顺序是第一步跑前面那个环境自检脚本把所有版本打出来。第二步对照官方文档的版本要求看哪个对不上。第三步用pip list看有没有重复安装的包比如同时装了 CPU 版和 GPU 版 torch。第四步如果还找不到新建一个干净环境重装往往比在原环境里修更快。我踩过最坑的一次是 NumPy 版本问题RKNN-Toolkit2 在 NumPy 1.24 上会报一个很隐晦的AttributeError查了半天才发现是版本问题。所以前面强调锁 NumPy 1.23.5。6.3 板端模型加载失败的排查板端加载 RKNN 模型失败常见原因和排查方法版本不匹配确认 Toolkit2 和 Runtime 版本一致。模型文件损坏重新转换一次或者用 md5 校验文件完整性。输入输出节点配置错误检查转换时的 config输入名字和形状要对。内存不足RK3588 内存有限大模型可能加载失败用free -h看内存。排查时打开 RKNN 的日志rknn RKNNLite(verboseTrue)verbose 打开后会打印详细的加载过程哪一步失败一目了然。6.4 几个我踩过的坑第一个坑导出 ONNX 时忘了--simplify结果转换 RKNN 时报了一堆算子不支持。加上 simplify 之后问题消失。所以这个参数别省。第二个坑用 GPU 导出 ONNX结果某些算子在 GPU 和 CPU 上的实现有细微差异导致板端结果和 PC 端对不上。后来统一用 CPU 导出问题解决。第三个坑板端系统自带的 OpenCV 版本太老读图后颜色通道顺序跟预期不一致导致检测框位置偏移。解决办法是统一用cv2.cvtColor显式转换别依赖默认行为。第四个坑校准数据集和推理输入预处理不一致量化后精度掉得厉害。这个在量化阶段才暴露但根子在导出阶段没统一预处理。所以前面强调预处理要固定。7. 环境搭建完成后的下一步衔接走到这里你应该已经拿到了一个验证过的yolov5s.onnxPC 端能正常推理板端 RKNN Runtime 也装好了。接下来就是把这个 ONNX 转成 RKNN 模型然后在板端跑起来。转换阶段的核心是 config 配置和量化校准这部分坑也不少尤其是 INT8 量化的精度问题。我个人在实际操作中的体会是环境搭建和模型获取这两步看似简单但决定了后面 80% 的顺利程度。版本锁死、导出验证、板端驱动确认这三件事做到位后面的转换和部署会顺畅很多。如果这三步偷懒后面会花几倍的时间去排查各种莫名其妙的问题。最后分享一个小技巧把整个环境搭建过程写成一个 shell 脚本包括 conda 环境创建、依赖安装、版本检查。下次换机器或者重装系统一条命令就能恢复环境比手动一步步装靠谱得多。这个脚本我用了大半年帮我省了不知道多少重复劳动。
1. 为什么环境搭建这一步值得单独拿出来讲很多人拿到 RK3588 开发板之后第一反应是直接找现成的镜像烧进去跑 demo能出画面就觉得大功告成。但真到要把 YOLOv5s 这种自定义模型塞进去跑的时候问题就全冒出来了PyTorch 版本对不上、ONNX 导出算子不支持、板端推理库和模型输入输出节点对不齐。我前后在 RK3588 上折腾过好几轮 YOLO 系列模型的部署踩过的坑基本都集中在“环境”和“模型获取”这两个看似最没技术含量的环节上。这篇是系列的第二部分专门讲环境搭建与模型获取。第一部分聊的是整体链路设计和硬件选型思路这一部分落地到具体操作PC 端怎么搭一个干净的 PyTorch 训练/导出环境YOLOv5s 的权重从哪来、怎么验证ONNX 怎么导出、导出时哪些参数必须盯死以及 RK3588 板端的基础运行环境怎么准备。整套流程走完你会得到一个可以在 PC 上正常推理、并且已经导出为 ONNX 的 YOLOv5s 模型为后续的 RKNN 转换和板端部署打好底子。适合谁看手上已经有 RK3588 开发板、想跑自己模型的人做过深度学习训练但没接触过端侧部署的人以及被 ONNX 导出各种报错折磨过的朋友。我尽量把每一步的“为什么”讲清楚而不是只丢一堆命令让你复制。2. 整体环境架构与方案选型思路2.1 三段式环境划分PC 训练端、转换端、板端在端侧部署这件事上最容易犯的错误就是把所有环境混在一台机器上。我的做法是明确分成三段PC 训练/导出端负责 YOLOv5s 的权重加载、验证、ONNX 导出。这台机器通常是带独立显卡的台式机或笔记本装完整的 PyTorch 生态。转换端负责把 ONNX 转成 RKNN。这一步可以在 PC 上做用 RKNN-Toolkit2也可以在板子上做用 RKNN-Toolkit-Lite2 或板端工具链。我倾向于在 PC 上转因为转换过程吃内存、需要反复调试PC 上效率高得多。板端运行端RK3588 上只装推理运行时RKNN Runtime和必要的系统依赖保持干净。为什么要这么分因为 PyTorch 的版本依赖非常“娇气”而 RKNN 工具链对 Python 版本、NumPy 版本又有自己的一套要求。混在一起装十有八九会出现“装了 RKNN 之后 PyTorch 导不出来了”或者“升级了 NumPy 之后 RKNN 转换报错”这类互相打架的问题。用 conda 或者 venv 把环境隔离是最省心的做法。2.2 为什么选 YOLOv5s 而不是 v8 或别的版本热词里能看到不少人在搜 rk3588部署yolov8YOLOv8 确实更新、精度也更好但我在 RK3588 上第一轮实践还是选 YOLOv5s原因很实际第一YOLOv5 的 ONNX 导出链路最成熟社区里针对 RKNN 的适配案例最多遇到问题好查。第二YOLOv5s 模型小约 7.2M 参数权重文件 14MB 左右RK3588 的 NPU 算力6 TOPS跑起来帧率很舒服。第三YOLOv8 的导出结构和后处理跟 v5 有差异第一次上手容易在“输出节点对不上”上卡住。等你把 v5 这条链路跑通了再换 v8 只是改几个导出参数的事。提示如果你明确只做 v8那环境搭建部分基本通用差异主要在导出脚本和后处理。建议先用 v5 把链路打通再迁移。2.3 版本锁定整个链路最容易被忽视的关键端侧部署最怕的就是“版本漂移”。我见过太多案例同样的代码今天能跑明天就报错原因就是某个依赖自动升级了。所以我的原则是所有关键依赖全部锁版本并且记录下来。下面这张表是我实测跑通的一套版本组合你可以直接参考环节组件版本说明PC 端Python3.8RKNN-Toolkit2 对 3.8 支持最好PC 端PyTorch1.13.1与 YOLOv5 兼容稳定PC 端torchvision0.14.1与 torch 1.13.1 配套PC 端ONNX1.12.0导出算子支持完善PC 端onnxruntime1.14.0用于验证 ONNX 推理转换端RKNN-Toolkit21.5.2支持 RK3588板端RKNN Runtime1.5.2与 Toolkit 版本对应板端系统Ubuntu 20.04官方适配成熟版本对应关系是硬约束尤其是 RKNN-Toolkit2 和板端 Runtime 必须版本一致否则会出现模型加载失败。这一点后面排查章节还会细说。3. PC 端 PyTorch 环境搭建实操3.1 用 conda 建一个干净的隔离环境我强烈建议用 conda 而不是系统 Python原因前面说了隔离。命令不复杂conda create -n yolov5_rknn python3.8 -y conda activate yolov5_rknn建完之后先确认 Python 版本python --version # 应该输出 Python 3.8.x这里有个小细节如果你用的是 WSL热词里 pytorch环境搭建wsl 搜索量很高conda 装完之后记得把 WSL 的内存限制调一下。默认 WSL2 会吃掉宿主机一半内存导出 ONNX 和后续转换时容易爆内存。在用户目录下建.wslconfig[wsl2] memory16GB processors8 swap8GB改完wsl --shutdown重启生效。这个配置我实测下来导出和转换过程稳定很多。3.2 安装 PyTorch 与依赖别直接 pip install torch新手最容易犯的错是直接pip install torch结果装了个最新版跟 YOLOv5 的代码不兼容。正确做法是去 PyTorch 官网找对应 CUDA 版本的安装命令。如果你机器没有 NVIDIA 显卡就装 CPU 版导出 ONNX 用 CPU 完全够。CUDA 11.7 对应的命令有显卡的情况pip install torch1.13.1cu117 torchvision0.14.1cu117 \ --extra-index-url https://download.pytorch.org/whl/cu117纯 CPU 的情况pip install torch1.13.1 torchvision0.14.1 \ --extra-index-url https://download.pytorch.org/whl/cpu装完验证一下import torch print(torch.__version__) print(torch.cuda.is_available()) # 有显卡应为 True然后装 YOLOv5 需要的其他依赖。这里注意不要直接pip install -r requirements.txt因为那个文件里会指定 torch 版本可能把你刚装好的覆盖掉。我的做法是手动装核心的几个pip install numpy1.23.5 opencv-python4.7.0.72 \ pyyaml6.0 tqdm4.65.0 matplotlib3.7.1 \ pandas1.5.3 seaborn0.12.2 onnx1.12.0 \ onnxruntime1.14.0NumPy 锁 1.23.5 是有原因的RKNN-Toolkit2 对 NumPy 版本敏感1.24 以上会有兼容性问题。这个坑我在转换阶段踩过提前锁好省事。3.3 获取 YOLOv5 源码与权重YOLOv5 的源码直接从官方仓库拉但要注意版本。我建议用 v6.2 或 v7.0 这两个 tag它们的导出逻辑稳定社区适配案例多。git clone https://github.com/ultralytics/yolov5.git cd yolov5 git checkout v7.0权重文件yolov5s.pt有两个来源一是官方 release 页面直接下载二是用脚本自动下载。我倾向于手动下载放到weights/目录因为自动下载有时候网络不稳下到一半断了还不好排查。mkdir -p weights # 把下载好的 yolov5s.pt 放到 weights/ 目录 ls -lh weights/yolov5s.pt # 正常应该是 14MB 左右拿到权重后第一件事是验证它能正常推理别急着导出。用官方自带的检测脚本跑一张图python detect.py --weights weights/yolov5s.pt \ --source data/images/bus.jpg --device cpu跑完在runs/detect/exp/下能看到带框的结果图。这一步能过说明 PyTorch 环境和权重都没问题。如果这一步就报错先别往下走把环境问题解决干净。注意detect.py 第一次运行会自动下载一些字体文件如果网络不通会卡住。可以提前把 Arial.ttf 放到缓存目录或者忽略这个警告不影响推理。3.4 环境自检清单在进入模型导出之前我习惯跑一个自检脚本把关键依赖的版本都打出来存成文件备查import torch, torchvision, numpy, onnx, onnxruntime, cv2 print(torch:, torch.__version__) print(torchvision:, torchvision.__version__) print(numpy:, numpy.__version__) print(onnx:, onnx.__version__) print(onnxruntime:, onnxruntime.__version__) print(opencv:, cv2.__version__) print(cuda available:, torch.cuda.is_available())把输出存成env_check.txt。后面如果出问题对照这个文件能快速定位是不是版本变了。这个习惯帮我省了无数次排查时间。4. YOLOv5s 模型获取与 ONNX 导出全流程4.1 导出前的模型结构确认导出 ONNX 之前得先搞清楚 YOLOv5s 的输出结构。很多人导出后板端跑不对就是因为不知道模型到底输出了什么。YOLOv5 默认导出三个输出头对应三个不同尺度的特征图形状分别是小目标[1, 255, 80, 80]中目标[1, 255, 40, 40]大目标[1, 255, 20, 20]这里的 255 是3 * (5 80)即 3 个 anchor、每个 anchor 5 个框参数xywh obj、80 个类别。输入是[1, 3, 640, 640]。为什么要在导出前确认这个因为 RKNN 转换时需要指定输入输出节点如果你不知道输出是什么形状后面根本没法配。而且 YOLOv5 的导出脚本有个--include onnx参数不同版本导出的输出节点命名可能不一样提前确认能避免踩坑。4.2 导出 ONNX 的关键参数逐个拆解YOLOv5 自带的export.py就能导出 ONNX但参数得配对。我常用的命令python export.py --weights weights/yolov5s.pt \ --include onnx \ --imgsz 640 640 \ --batch-size 1 \ --opset 12 \ --device cpu \ --simplify逐个说这些参数为什么这么设--imgsz 640 640输入分辨率。RK3588 的 NPU 对 640 这个尺寸支持很好而且 640 是 32 的倍数YOLOv5 的下采样要求输入能被 32 整除。如果你想用 320 或 416也可以但精度会降。--batch-size 1端侧推理基本都是单张batch 设 1 最省内存也避免动态 batch 带来的转换麻烦。--opset 12ONNX 算子集版本。这个很关键。opset 太高比如 17会引入 RKNN 不支持的算子太低比如 9又可能缺一些必要算子。opset 12 是我实测在 RK3588 上兼容性最好的版本。--device cpu导出用 CPU 就行用 GPU 导出有时候会有算子差异。--simplify调用 onnx-simplifier 做图优化去掉冗余节点。这个强烈建议开能显著减少转换时的算子问题。需要先装pip install onnx-simplifier0.4.17导出成功后会在weights/目录下生成yolov5s.onnx大小约 28MB。4.3 导出后的 ONNX 验证别跳过这一步导出完直接拿去转换是另一个常见错误。ONNX 文件可能“导出成功但推理错误”必须验证。我用 onnxruntime 跑一遍跟 PyTorch 的结果对比import onnxruntime as ort import numpy as np import torch # 加载 ONNX sess ort.InferenceSession(weights/yolov5s.onnx, providers[CPUExecutionProvider]) input_name sess.get_inputs()[0].name print(input name:, input_name) print(input shape:, sess.get_inputs()[0].shape) for out in sess.get_outputs(): print(output:, out.name, out.shape) # 造一个随机输入测试 dummy np.random.randn(1, 3, 640, 640).astype(np.float32) outputs sess.run(None, {input_name: dummy}) for i, o in enumerate(outputs): print(foutput {i} shape:, o.shape)正常应该打印出三个输出形状跟前面说的一致。如果输出数量不对或者形状是动态的显示为字符串而不是数字说明导出参数有问题得回去检查。提示如果输出形状里出现-1或batch这种动态维度转换 RKNN 时可能报错。解决办法是导出时确保 batch 固定为 1并且不要开 dynamic axes。4.4 用真实图片做端到端验证随机输入只能验证形状验证不了数值正确性。我还会用一张真实图片分别跑 PyTorch 和 ONNX对比输出差异import cv2 import numpy as np import torch import onnxruntime as ort img cv2.imread(data/images/bus.jpg) img cv2.resize(img, (640, 640)) img cv2.cvtColor(img, cv2.COLOR_BGR2RGB) img img.transpose(2, 0, 1)[None].astype(np.float32) / 255.0 # PyTorch 推理 model torch.load(weights/yolov5s.pt, map_locationcpu)[model] model.eval() with torch.no_grad(): pt_out model(torch.from_numpy(img))[0].numpy() # ONNX 推理 sess ort.InferenceSession(weights/yolov5s.onnx, providers[CPUExecutionProvider]) onnx_out sess.run(None, {sess.get_inputs()[0].name: img})[0] # 对比最大差异 diff np.abs(pt_out - onnx_out).max() print(max diff:, diff)正常情况下 max diff 应该在 1e-4 到 1e-3 量级。如果差异很大比如 0.1 以上说明导出过程有问题可能是某个算子被错误转换了。这个验证步骤花不了几分钟但能帮你提前发现大问题。4.5 模型轻量化的一些前置考虑热词里 yolov5s模型轻量化 也是高频搜索。如果你后续打算做量化INT8在导出阶段就要留个心眼。INT8 量化需要校准数据集而校准数据的预处理方式必须和推理时完全一致。我的建议是导出 ONNX 时就把预处理归一化、resize固定下来别在板端再做额外处理。准备 100 到 200 张有代表性的校准图片覆盖你的实际场景。校准图片的尺寸、通道顺序、归一化方式跟推理输入严格对齐。这些在导出阶段想清楚后面量化会顺很多。量化本身是下一部分的内容这里先埋个伏笔。5. RK3588 板端基础环境准备5.1 系统选择与烧写要点RK3588 板端系统我推荐 Ubuntu 20.04官方适配最成熟RKNN Runtime 的安装包也最全。烧写用瑞芯微的烧录工具注意几个点第一烧写前确认板子的启动模式拨码开关在正确位置通常是 MaskROM 模式。第二USB 线要用质量好的劣质线会导致烧写中途断开。第三烧写完成后第一次启动会比较慢耐心等别以为卡死了就断电。系统起来之后先更新一下基础包sudo apt update sudo apt install -y python3-pip python3-dev cmake git \ libopencv-dev python3-opencv5.2 板端 Python 环境与 RKNN Runtime 安装板端的 Python 环境我建议直接用系统自带的 Python 3.8不要额外建 conda 环境因为 RKNN Runtime 的 wheel 包对系统 Python 支持最好。RKNN Runtime 的安装分两部分一是rknn_toolkit_lite2Python 接口二是底层的librknnrt.soC 库。安装包从官方仓库获取注意版本要和 PC 端 Toolkit2 一致。# 安装 Python 接口 pip3 install rknn_toolkit_lite2-1.5.2-cp38-cp38-linux_aarch64.whl # 底层库通常随系统镜像已包含确认一下 ls /usr/lib/librknnrt.so如果librknnrt.so不存在需要手动拷贝到/usr/lib/并执行sudo ldconfig。验证安装from rknnlite.api import RKNNLite rknn RKNNLite() print(RKNN Lite init ok)能打印出来就说明板端环境 OK 了。5.3 NPU 驱动版本确认RK3588 的 NPU 驱动版本会影响模型加载。查看驱动版本cat /sys/kernel/debug/rknpu/version输出的版本号要跟 RKNN Runtime 匹配。如果驱动太旧加载新版本转换的模型会失败。升级驱动通常需要重新烧写系统或者单独更新内核模块比较麻烦所以一开始就选对系统版本很重要。注意NPU 驱动版本和 RKNN Runtime 版本不匹配是板端部署最常见的失败原因之一。转换模型前先确认这两个版本能省掉大量排查时间。5.4 板端推理库的依赖检查RKNN Runtime 依赖一些系统库缺了会报libxxx.so not found。我习惯用ldd检查ldd /usr/lib/librknnrt.so | grep not found如果输出为空说明依赖齐全。如果有缺失根据提示装对应的库。常见的缺失是libgomp和libstdc一般apt install就能解决。6. 常见问题与排查技巧实录6.1 ONNX 导出报错速查表导出阶段的问题最集中我整理了一张速查表报错信息原因解决办法Unsupported ONNX opsetopset 版本过高降到 12Export failed: dynamic shape开了 dynamic axes关闭固定 batch1ModuleNotFoundError: onnx没装 onnxpip install onnx1.12.0simplify failedonnx-simplifier 版本不匹配装 0.4.17输出节点数量不对导出脚本版本问题换 v7.0 tagRuntimeError: CUDA out of memory用 GPU 导出加 --device cpu6.2 版本冲突的排查思路版本冲突是最难查的问题因为报错信息往往指向别处。我的排查顺序是第一步跑前面那个环境自检脚本把所有版本打出来。第二步对照官方文档的版本要求看哪个对不上。第三步用pip list看有没有重复安装的包比如同时装了 CPU 版和 GPU 版 torch。第四步如果还找不到新建一个干净环境重装往往比在原环境里修更快。我踩过最坑的一次是 NumPy 版本问题RKNN-Toolkit2 在 NumPy 1.24 上会报一个很隐晦的AttributeError查了半天才发现是版本问题。所以前面强调锁 NumPy 1.23.5。6.3 板端模型加载失败的排查板端加载 RKNN 模型失败常见原因和排查方法版本不匹配确认 Toolkit2 和 Runtime 版本一致。模型文件损坏重新转换一次或者用 md5 校验文件完整性。输入输出节点配置错误检查转换时的 config输入名字和形状要对。内存不足RK3588 内存有限大模型可能加载失败用free -h看内存。排查时打开 RKNN 的日志rknn RKNNLite(verboseTrue)verbose 打开后会打印详细的加载过程哪一步失败一目了然。6.4 几个我踩过的坑第一个坑导出 ONNX 时忘了--simplify结果转换 RKNN 时报了一堆算子不支持。加上 simplify 之后问题消失。所以这个参数别省。第二个坑用 GPU 导出 ONNX结果某些算子在 GPU 和 CPU 上的实现有细微差异导致板端结果和 PC 端对不上。后来统一用 CPU 导出问题解决。第三个坑板端系统自带的 OpenCV 版本太老读图后颜色通道顺序跟预期不一致导致检测框位置偏移。解决办法是统一用cv2.cvtColor显式转换别依赖默认行为。第四个坑校准数据集和推理输入预处理不一致量化后精度掉得厉害。这个在量化阶段才暴露但根子在导出阶段没统一预处理。所以前面强调预处理要固定。7. 环境搭建完成后的下一步衔接走到这里你应该已经拿到了一个验证过的yolov5s.onnxPC 端能正常推理板端 RKNN Runtime 也装好了。接下来就是把这个 ONNX 转成 RKNN 模型然后在板端跑起来。转换阶段的核心是 config 配置和量化校准这部分坑也不少尤其是 INT8 量化的精度问题。我个人在实际操作中的体会是环境搭建和模型获取这两步看似简单但决定了后面 80% 的顺利程度。版本锁死、导出验证、板端驱动确认这三件事做到位后面的转换和部署会顺畅很多。如果这三步偷懒后面会花几倍的时间去排查各种莫名其妙的问题。最后分享一个小技巧把整个环境搭建过程写成一个 shell 脚本包括 conda 环境创建、依赖安装、版本检查。下次换机器或者重装系统一条命令就能恢复环境比手动一步步装靠谱得多。这个脚本我用了大半年帮我省了不知道多少重复劳动。
