1. 为什么环境搭建这一步值得单独拿出来讲很多人拿到 RK3588 开发板之后第一反应是直接找现成的 RKNN 模型跑起来看效果。这个思路没错但实际走一遍就会发现真正卡住进度的往往不是模型转换本身而是环境搭建阶段的各种琐碎问题Python 版本冲突、PyTorch 装不上、ONNX 导出报错、RKNN-Toolkit2 依赖缺失。我在第一次部署 YOLOv5s 的时候光环境搭建就折腾了将近两天中间踩的坑足够写一篇避坑指南。这篇文章是系列的第二篇专门讲环境搭建与模型获取。核心目标很明确在一台开发机上准备好完整的模型转换工具链把 YOLOv5s 的 PyTorch 权重拿到手并且验证它能正常导出为 ONNX 格式。这一步做完后面转到 RKNN 就是水到渠成的事。适合的读者是手里有 RK3588 板子、想在 NPU 上跑目标检测模型、但对整个工具链还不太熟悉的开发者。如果你之前只在 PC 上跑过 YOLO没接触过端侧部署那这篇内容基本就是照着抄作业的节奏。整个流程我拆成了三大块开发机环境准备、YOLOv5s 源码与权重获取、ONNX 导出验证。每一块都会说清楚为什么这么做、有哪些替代方案、以及我实际踩过的坑。环境搭建这件事看起来是体力活但里面的选择逻辑其实挺多选错了后面会反复返工。2. 开发机环境准备选对工具链版本比什么都重要2.1 操作系统与 Python 版本的选择逻辑开发机用什么系统这个问题看起来简单实际上直接影响后面 RKNN-Toolkit2 能不能顺利装上。RKNN-Toolkit2 官方支持的平台是 Ubuntu 18.04 和 Ubuntu 20.04Python 版本要求 3.6 到 3.8 之间。我一开始图省事用了 Ubuntu 22.04 加 Python 3.10结果 RKNN-Toolkit2 的 wheel 包直接装不上报了一堆依赖不兼容的错误。后来我换了个思路用 Ubuntu 20.04 作为基础系统Python 锁定在 3.8。这个组合是经过验证最稳的。如果你手头只有 Windows 机器可以用 WSL2 装 Ubuntu 20.04实测下来和原生 Ubuntu 体验基本一致USB 设备透传也没问题。但要注意 WSL2 的内核版本太新的内核有时候会导致 RKNN-Toolkit2 的某些依赖编译失败建议用 WSL2 默认的 Ubuntu 20.04 镜像就行。Python 环境管理我强烈建议用 conda 或者 miniconda不要直接用系统自带的 Python。原因很简单RKNN-Toolkit2 对 numpy、protobuf 这些包的版本有严格要求系统 Python 里往往已经装了其他版本混在一起很容易出问题。用 conda 创建一个独立环境出问题了直接删掉重建成本很低。# 创建独立环境 conda create -n rknn_yolov5 python3.8 conda activate rknn_yolov5 # 验证 Python 版本 python --version # 应该输出 Python 3.8.x这里有个细节值得说一下为什么是 Python 3.8 而不是 3.6 或 3.7因为 YOLOv5 的某些依赖比如最新的 PyTorch 版本对 Python 最低版本有要求3.6 已经太老了很多包不再提供支持。3.8 是一个平衡点既能满足 RKNN-Toolkit2 的要求又能兼容较新的 PyTorch。2.2 PyTorch 安装的版本匹配与常见报错PyTorch 的安装是环境搭建里最容易出问题的环节。RKNN-Toolkit2 本身不依赖 PyTorch但我们需要 PyTorch 来加载 YOLOv5s 的权重并导出 ONNX。所以 PyTorch 的版本选择主要考虑两点一是能正常加载 YOLOv5s 的权重二是导出的 ONNX 算子集版本要兼容 RKNN 工具链。我实测下来PyTorch 1.10 到 1.13 之间的版本都比较稳。太新的版本比如 2.0 以上导出的 ONNX 有时候会引入一些 RKNN 不支持的算子太老的版本又可能缺少某些必要的功能。我最终用的是 PyTorch 1.12.1 加 torchvision 0.13.1这个组合在 YOLOv5s 导出 ONNX 时没有出现过算子兼容问题。安装命令根据是否有 GPU 会有所不同。如果你开发机有 NVIDIA 显卡可以用 CUDA 版本加速推理验证如果没有CPU 版本也完全够用因为导出 ONNX 这个过程本身不需要 GPU。# CPU 版本安装推荐兼容性最好 pip install torch1.12.1 torchvision0.13.1 --index-url https://download.pytorch.org/whl/cpu # 如果有 CUDA 11.3可以用这个 pip install torch1.12.1cu113 torchvision0.13.1cu113 --extra-index-url https://download.pytorch.org/whl/cu113装完之后一定要验证一下import torch print(torch.__version__) print(torch.cuda.is_available()) # 没有 GPU 的话输出 False 是正常的这里有个坑我踩过如果你之前装过其他版本的 PyTorchpip 可能不会自动卸载旧版本导致新旧版本混在一起。建议在安装前先执行pip uninstall torch torchvision把旧的清干净再装新版本。2.3 ONNX 与 ONNX Runtime 的安装要点ONNX 和 ONNX Runtime 是两个不同的东西很多人会搞混。ONNX 是一种模型格式标准定义了一套算子规范和文件结构ONNX Runtime 是一个推理引擎用来加载和运行 ONNX 模型。我们在导出阶段只需要 ONNX 这个包来支持torch.onnx.export的调用ONNX Runtime 则是用来在开发机上验证导出的模型能不能正常推理。安装命令很简单pip install onnx1.12.0 onnxruntime1.12.1版本选择上ONNX 1.12 对应的算子集版本是 17这个版本导出的模型在 RKNN-Toolkit2 里兼容性比较好。ONNX Runtime 用 1.12.1 是因为它和 ONNX 1.12 是配套的版本差太多可能会出现加载模型失败的情况。验证安装import onnx import onnxruntime as ort print(onnx.__version__) print(ort.__version__)如果这两个 import 都没报错说明基础环境已经就绪了。2.4 RKNN-Toolkit2 的安装与依赖处理RKNN-Toolkit2 是瑞芯微官方提供的模型转换工具负责把 ONNX 模型转成 RK3588 NPU 能执行的 RKNN 格式。这个工具的安装是环境搭建里最麻烦的一步因为它的依赖比较多而且对版本很敏感。首先去瑞芯微的 GitHub 仓库下载对应版本的 RKNN-Toolkit2。注意要选对版本RK3588 需要的是 RKNN-Toolkit2 1.4.0 或以上版本。下载下来是一个 whl 文件直接 pip 安装pip install rknn_toolkit2-1.4.0-cp38-cp38-linux_x86_64.whl安装过程中最常见的报错是 protobuf 版本冲突。RKNN-Toolkit2 依赖 protobuf 3.20 以下的版本但很多其他包会装更新的 protobuf。解决办法是先装 RKNN-Toolkit2再装其他包或者手动锁定 protobuf 版本pip install protobuf3.19.6还有一个常见问题是 numpy 版本。RKNN-Toolkit2 1.4.0 要求 numpy 低于 1.24如果系统里装了更新的 numpyimport rknn 的时候会报module numpy has no attribute object之类的错误。直接降级pip install numpy1.23.5验证 RKNN-Toolkit2 是否安装成功from rknn.api import RKNN print(RKNN Toolkit2 loaded successfully)如果这行能正常执行说明环境搭建的核心部分已经完成了。3. YOLOv5s 源码与权重获取别小看这一步的版本选择3.1 YOLOv5 仓库版本的选择与克隆YOLOv5 的官方仓库更新很频繁不同版本之间的代码结构和导出逻辑有差异。我建议锁定一个稳定的 tag不要直接用 master 分支因为 master 随时可能引入新的改动导致导出 ONNX 时出现意料之外的问题。我实测下来v6.2 和 v7.0 这两个版本比较稳。v6.2 的代码结构更简洁导出 ONNX 的默认参数对 RKNN 比较友好v7.0 增加了一些新功能但核心导出逻辑没变。我最终用的是 v6.2因为它的export.py脚本参数更少不容易配错。git clone https://github.com/ultralytics/yolov5.git cd yolov5 git checkout v6.2克隆下来之后先别急着装依赖。YOLOv5 的requirements.txt里列了一堆包但有些版本和我们之前装好的 PyTorch 可能冲突。我的做法是手动安装核心依赖跳过那些非必要的包pip install pyyaml matplotlib opencv-python pillow tqdm注意opencv-python建议装opencv-python-headless版本尤其是在服务器环境下避免 GUI 相关的依赖问题。3.2 权重文件的获取与校验YOLOv5s 的预训练权重可以从官方 release 页面下载也可以让脚本自动下载。自动下载的方式很简单在 YOLOv5 目录下执行python -c import torch; model torch.hub.load(ultralytics/yolov5, yolov5s, pretrainedTrue)但这行命令会同时下载仓库代码和权重有时候网络不稳定会失败。更稳妥的方式是直接下载权重文件wget https://github.com/ultralytics/yolov5/releases/download/v6.2/yolov5s.pt下载完之后一定要校验文件完整性。我遇到过一次权重文件下载不完整的情况加载的时候报unexpected EOF错误排查了半天才发现是文件没下完。校验方法很简单看文件大小是否在 14MB 左右ls -lh yolov5s.pt # 正常应该是 14M 左右如果文件大小明显偏小重新下载。另外可以用 PyTorch 加载一下确认没有报错import torch model torch.load(yolov5s.pt, map_locationcpu) print(type(model))正常输出应该是class dict或者模型对象如果报错说明文件有问题。3.3 权重加载验证与模型结构确认拿到权重之后建议先跑一次推理验证确认模型能正常工作。这一步看起来多余但实际上能提前发现很多问题比如权重和代码版本不匹配、依赖包缺失等。import torch from models.experimental import attempt_load model attempt_load(yolov5s.pt, map_locationcpu) model.eval() print(Model loaded successfully) print(fNumber of parameters: {sum(p.numel() for p in model.parameters())})YOLOv5s 的参数量大概在 720 万左右如果输出的数字差太多说明权重加载有问题。另外可以打印一下模型的输出层信息确认检测头是三个尺度for name, module in model.named_modules(): if detect in name.lower(): print(name, module)正常情况下应该能看到三个 Detect 层分别对应 stride 8、16、32 的特征图。这个信息在后面转 ONNX 和 RKNN 的时候会用到因为 RKNN 需要知道输出节点的名称和数量。4. ONNX 导出全流程参数配置与验证方法4.1 导出脚本的关键参数解读YOLOv5 自带的export.py脚本可以直接用来导出 ONNX但默认参数不一定适合 RK3588。我建议手动指定几个关键参数而不是直接用默认值。核心参数有这几个--weights指定权重文件路径--img-size输入图像尺寸RK3588 上常用 640x640--batch-size批处理大小端侧部署一般设为 1--opsetONNX 算子集版本建议用 12--include指定导出格式为 onnx--simplify是否简化模型建议开启导出命令python export.py --weights yolov5s.pt --img-size 640 640 --batch-size 1 --opset 12 --include onnx --simplify这里重点说一下--opset 12的选择理由。ONNX 算子集版本越高支持的算子越多但 RKNN-Toolkit2 对高版本算子集的支持有限。我试过 opset 13 和 15导出后在 RKNN 转换阶段都出现过算子不支持的问题。opset 12 是一个比较保守的选择覆盖了 YOLOv5s 需要的所有算子同时 RKNN 兼容性最好。--simplify参数会调用 onnx-simplifier 对模型进行简化去掉一些冗余的算子。这个步骤能显著减少 RKNN 转换时的报错概率强烈建议开启。但需要先安装 onnx-simplifierpip install onnx-simplifier4.2 导出过程中的常见报错与处理导出过程中最常见的报错是RuntimeError: Exporting the operator ... to ONNX opset version 12 is not supported。这个错误通常是因为 PyTorch 版本和 opset 版本不匹配导致的。解决办法有两个一是降低 opset 版本到 11二是升级 PyTorch 到 1.12 以上。我推荐后者因为 opset 11 对某些算子的支持不完整。另一个常见问题是AttributeError: Upsample object has no attribute recompute_scale_factor。这是 PyTorch 1.11 之后引入的一个兼容性问题YOLOv5 v6.2 的代码没有适配。解决办法是修改models/common.py里的 Upsample 类把recompute_scale_factor参数去掉或者直接升级 YOLOv5 到 v7.0。还有一个坑是导出后的 ONNX 模型输出节点名称。YOLOv5 默认导出的输出节点叫output但 RKNN 转换时需要明确指定输出节点。我建议在导出时用--output-names参数自定义输出节点名称方便后面 RKNN 配置python export.py --weights yolov5s.pt --img-size 640 640 --batch-size 1 --opset 12 --include onnx --simplify --output-names output0 output1 output24.3 ONNX 模型验证与推理测试导出完成后必须验证 ONNX 模型能不能正常推理。这一步能发现很多隐藏问题比如输出维度不对、算子计算错误等。import onnx import onnxruntime as ort import numpy as np # 加载模型 onnx_model onnx.load(yolov5s.onnx) onnx.checker.check_model(onnx_model) print(ONNX model check passed) # 创建推理会话 session ort.InferenceSession(yolov5s.onnx) # 查看输入输出信息 for inp in session.get_inputs(): print(fInput: {inp.name}, shape: {inp.shape}, type: {inp.type}) for out in session.get_outputs(): print(fOutput: {out.name}, shape: {out.shape}, type: {out.type}) # 构造随机输入测试 dummy_input np.random.randn(1, 3, 640, 640).astype(np.float32) outputs session.run(None, {session.get_inputs()[0].name: dummy_input}) for i, out in enumerate(outputs): print(fOutput {i} shape: {out.shape})正常情况下三个输出节点的 shape 应该是[1, 25200, 85]或者类似的格式。25200 是 80x80 40x40 20x20 三个尺度特征图的预测框总数85 是 4 个坐标 1 个置信度 80 个类别概率。如果 shape 不对说明导出参数有问题需要回头检查。4.4 模型轻量化与量化前的准备虽然这篇文章主要讲环境搭建和模型获取但既然提到了 ONNX顺便说一下量化前的准备工作。RK3588 的 NPU 对 INT8 量化支持最好FP16 也能跑但性能会打折扣。在转 RKNN 之前需要准备一组校准图片用来做量化校准。校准图片的准备原则是数量不用太多100 到 200 张就够内容要覆盖实际部署场景中的典型画面分辨率不需要和模型输入一致RKNN 工具会自动处理。我一般从训练集或者实际场景中随机抽一批图片放到一个文件夹里后面 RKNN 转换时指定这个文件夹路径就行。# 校准图片目录结构示例 calibration_images/ ├── img_001.jpg ├── img_002.jpg ├── ... └── img_200.jpg另外ONNX 模型在量化前最好先做一次简化去掉不必要的算子。除了前面提到的--simplify参数还可以用 onnx-simplifier 单独处理python -m onnxsim yolov5s.onnx yolov5s_sim.onnx简化后的模型在 RKNN 转换时成功率更高而且推理速度也会略有提升。5. 实操中的常见问题与排查技巧5.1 环境类问题速查表问题现象可能原因解决方法ImportError: libGL.so.1缺少 OpenCV 系统依赖apt install libgl1-mesa-glxModuleNotFoundError: No module named rknnRKNN-Toolkit2 未安装或环境不对确认 conda 环境已激活重新安装 whlprotobuf version conflictprotobuf 版本过高pip install protobuf3.19.6numpy has no attribute objectnumpy 版本过高pip install numpy1.23.5torch.onnx.export报算子不支持opset 版本不匹配降低 opset 到 12 或升级 PyTorchONNX 模型加载失败文件下载不完整重新下载校验文件大小5.2 我踩过的三个典型坑第一个坑是 conda 环境和系统环境的混淆。我在 conda 环境里装了 RKNN-Toolkit2但执行脚本的时候忘了激活环境用的是系统 Python结果一直报No module named rknn。排查了半天才发现是环境没激活。这个问题的教训是每次打开新终端第一件事就是conda activate rknn_yolov5养成习惯。第二个坑是 ONNX 导出时的动态轴设置。YOLOv5 的export.py默认会设置动态 batch 轴但 RK3588 部署时 batch 固定为 1动态轴反而会导致 RKNN 转换失败。解决办法是在导出时加--dynamic参数的反向操作或者手动修改导出脚本把 dynamic_axes 设为 None。我后来直接在导出命令里加了--batch-size 1并且确认导出的 ONNX 没有动态维度。第三个坑是权重文件的版本匹配。我有一次用 YOLOv5 v7.0 的代码加载 v6.2 的权重虽然能加载成功但推理结果完全不对。原因是两个版本的模型结构有细微差异权重对不上。后来我统一用 v6.2 的代码和 v6.2 的权重问题就消失了。所以版本一致性这件事在模型部署里怎么强调都不为过。5.3 验证环境是否就绪的完整检查清单在进入下一步 RKNN 转换之前建议按这个清单逐项检查conda 环境已激活Python 版本为 3.8PyTorch 能正常 import版本在 1.10 到 1.13 之间ONNX 和 ONNX Runtime 能正常 importRKNN-Toolkit2 能正常 importfrom rknn.api import RKNN不报错YOLOv5s 权重文件大小正常能正常加载ONNX 模型已导出onnx.checker.check_model通过ONNX Runtime 推理测试通过输出 shape 正确校准图片文件夹已准备好至少有 100 张图片这八项都确认无误之后环境搭建和模型获取这一步就算彻底完成了。后面转 RKNN 的时候如果遇到问题基本可以排除环境因素直接聚焦在转换参数和模型结构上。6. 关于工具链版本锁定的一点个人经验环境搭建这件事最怕的就是版本漂移。今天装好的环境过两个月重新装一遍可能因为某个包的版本更新了就跑不起来了。我的做法是把所有关键包的版本号记录在一个requirements_lock.txt文件里下次重建环境的时候直接按这个文件装。torch1.12.1 torchvision0.13.1 onnx1.12.0 onnxruntime1.12.1 numpy1.23.5 protobuf3.19.6 opencv-python-headless4.6.0.66这个文件看起来不起眼但在我后来换开发机、重装系统的时候省了大量时间。直接pip install -r requirements_lock.txt十分钟就能把环境恢复到位不用再一个个排查版本冲突。另外RKNN-Toolkit2 的 whl 文件建议本地备份一份。瑞芯微的 GitHub 仓库有时候会调整 release 页面旧版本的 whl 不一定能随时下载到。我习惯把 whl 文件和对应的 ONNX 模型放在同一个目录下标注好版本号和日期这样即使过了半年再回头看也能快速复现当时的环境。模型获取这一步权重文件同样建议本地存档。YOLOv5 的 release 页面虽然稳定但网络问题谁也说不准。我一般会把yolov5s.pt和导出的yolov5s.onnx一起放到项目目录的weights/文件夹下用 git-lfs 或者直接压缩备份。这样后面做 RKNN 转换、量化、精度对比的时候随时都能拿到原始文件不用重新下载。环境搭建和模型获取是整个部署流程的地基地基打牢了后面的转换和调优才能顺利进行。下一篇会讲 RKNN 转换的具体操作包括量化参数配置、精度对比方法、以及如何在 RK3588 上跑通第一次推理。如果你在环境搭建阶段遇到了这里没提到的问题大概率是某个依赖包的版本不对按上面说的版本锁定思路排查一遍基本都能解决。
1. 为什么环境搭建这一步值得单独拿出来讲很多人拿到 RK3588 开发板之后第一反应是直接找现成的 RKNN 模型跑起来看效果。这个思路没错但实际走一遍就会发现真正卡住进度的往往不是模型转换本身而是环境搭建阶段的各种琐碎问题Python 版本冲突、PyTorch 装不上、ONNX 导出报错、RKNN-Toolkit2 依赖缺失。我在第一次部署 YOLOv5s 的时候光环境搭建就折腾了将近两天中间踩的坑足够写一篇避坑指南。这篇文章是系列的第二篇专门讲环境搭建与模型获取。核心目标很明确在一台开发机上准备好完整的模型转换工具链把 YOLOv5s 的 PyTorch 权重拿到手并且验证它能正常导出为 ONNX 格式。这一步做完后面转到 RKNN 就是水到渠成的事。适合的读者是手里有 RK3588 板子、想在 NPU 上跑目标检测模型、但对整个工具链还不太熟悉的开发者。如果你之前只在 PC 上跑过 YOLO没接触过端侧部署那这篇内容基本就是照着抄作业的节奏。整个流程我拆成了三大块开发机环境准备、YOLOv5s 源码与权重获取、ONNX 导出验证。每一块都会说清楚为什么这么做、有哪些替代方案、以及我实际踩过的坑。环境搭建这件事看起来是体力活但里面的选择逻辑其实挺多选错了后面会反复返工。2. 开发机环境准备选对工具链版本比什么都重要2.1 操作系统与 Python 版本的选择逻辑开发机用什么系统这个问题看起来简单实际上直接影响后面 RKNN-Toolkit2 能不能顺利装上。RKNN-Toolkit2 官方支持的平台是 Ubuntu 18.04 和 Ubuntu 20.04Python 版本要求 3.6 到 3.8 之间。我一开始图省事用了 Ubuntu 22.04 加 Python 3.10结果 RKNN-Toolkit2 的 wheel 包直接装不上报了一堆依赖不兼容的错误。后来我换了个思路用 Ubuntu 20.04 作为基础系统Python 锁定在 3.8。这个组合是经过验证最稳的。如果你手头只有 Windows 机器可以用 WSL2 装 Ubuntu 20.04实测下来和原生 Ubuntu 体验基本一致USB 设备透传也没问题。但要注意 WSL2 的内核版本太新的内核有时候会导致 RKNN-Toolkit2 的某些依赖编译失败建议用 WSL2 默认的 Ubuntu 20.04 镜像就行。Python 环境管理我强烈建议用 conda 或者 miniconda不要直接用系统自带的 Python。原因很简单RKNN-Toolkit2 对 numpy、protobuf 这些包的版本有严格要求系统 Python 里往往已经装了其他版本混在一起很容易出问题。用 conda 创建一个独立环境出问题了直接删掉重建成本很低。# 创建独立环境 conda create -n rknn_yolov5 python3.8 conda activate rknn_yolov5 # 验证 Python 版本 python --version # 应该输出 Python 3.8.x这里有个细节值得说一下为什么是 Python 3.8 而不是 3.6 或 3.7因为 YOLOv5 的某些依赖比如最新的 PyTorch 版本对 Python 最低版本有要求3.6 已经太老了很多包不再提供支持。3.8 是一个平衡点既能满足 RKNN-Toolkit2 的要求又能兼容较新的 PyTorch。2.2 PyTorch 安装的版本匹配与常见报错PyTorch 的安装是环境搭建里最容易出问题的环节。RKNN-Toolkit2 本身不依赖 PyTorch但我们需要 PyTorch 来加载 YOLOv5s 的权重并导出 ONNX。所以 PyTorch 的版本选择主要考虑两点一是能正常加载 YOLOv5s 的权重二是导出的 ONNX 算子集版本要兼容 RKNN 工具链。我实测下来PyTorch 1.10 到 1.13 之间的版本都比较稳。太新的版本比如 2.0 以上导出的 ONNX 有时候会引入一些 RKNN 不支持的算子太老的版本又可能缺少某些必要的功能。我最终用的是 PyTorch 1.12.1 加 torchvision 0.13.1这个组合在 YOLOv5s 导出 ONNX 时没有出现过算子兼容问题。安装命令根据是否有 GPU 会有所不同。如果你开发机有 NVIDIA 显卡可以用 CUDA 版本加速推理验证如果没有CPU 版本也完全够用因为导出 ONNX 这个过程本身不需要 GPU。# CPU 版本安装推荐兼容性最好 pip install torch1.12.1 torchvision0.13.1 --index-url https://download.pytorch.org/whl/cpu # 如果有 CUDA 11.3可以用这个 pip install torch1.12.1cu113 torchvision0.13.1cu113 --extra-index-url https://download.pytorch.org/whl/cu113装完之后一定要验证一下import torch print(torch.__version__) print(torch.cuda.is_available()) # 没有 GPU 的话输出 False 是正常的这里有个坑我踩过如果你之前装过其他版本的 PyTorchpip 可能不会自动卸载旧版本导致新旧版本混在一起。建议在安装前先执行pip uninstall torch torchvision把旧的清干净再装新版本。2.3 ONNX 与 ONNX Runtime 的安装要点ONNX 和 ONNX Runtime 是两个不同的东西很多人会搞混。ONNX 是一种模型格式标准定义了一套算子规范和文件结构ONNX Runtime 是一个推理引擎用来加载和运行 ONNX 模型。我们在导出阶段只需要 ONNX 这个包来支持torch.onnx.export的调用ONNX Runtime 则是用来在开发机上验证导出的模型能不能正常推理。安装命令很简单pip install onnx1.12.0 onnxruntime1.12.1版本选择上ONNX 1.12 对应的算子集版本是 17这个版本导出的模型在 RKNN-Toolkit2 里兼容性比较好。ONNX Runtime 用 1.12.1 是因为它和 ONNX 1.12 是配套的版本差太多可能会出现加载模型失败的情况。验证安装import onnx import onnxruntime as ort print(onnx.__version__) print(ort.__version__)如果这两个 import 都没报错说明基础环境已经就绪了。2.4 RKNN-Toolkit2 的安装与依赖处理RKNN-Toolkit2 是瑞芯微官方提供的模型转换工具负责把 ONNX 模型转成 RK3588 NPU 能执行的 RKNN 格式。这个工具的安装是环境搭建里最麻烦的一步因为它的依赖比较多而且对版本很敏感。首先去瑞芯微的 GitHub 仓库下载对应版本的 RKNN-Toolkit2。注意要选对版本RK3588 需要的是 RKNN-Toolkit2 1.4.0 或以上版本。下载下来是一个 whl 文件直接 pip 安装pip install rknn_toolkit2-1.4.0-cp38-cp38-linux_x86_64.whl安装过程中最常见的报错是 protobuf 版本冲突。RKNN-Toolkit2 依赖 protobuf 3.20 以下的版本但很多其他包会装更新的 protobuf。解决办法是先装 RKNN-Toolkit2再装其他包或者手动锁定 protobuf 版本pip install protobuf3.19.6还有一个常见问题是 numpy 版本。RKNN-Toolkit2 1.4.0 要求 numpy 低于 1.24如果系统里装了更新的 numpyimport rknn 的时候会报module numpy has no attribute object之类的错误。直接降级pip install numpy1.23.5验证 RKNN-Toolkit2 是否安装成功from rknn.api import RKNN print(RKNN Toolkit2 loaded successfully)如果这行能正常执行说明环境搭建的核心部分已经完成了。3. YOLOv5s 源码与权重获取别小看这一步的版本选择3.1 YOLOv5 仓库版本的选择与克隆YOLOv5 的官方仓库更新很频繁不同版本之间的代码结构和导出逻辑有差异。我建议锁定一个稳定的 tag不要直接用 master 分支因为 master 随时可能引入新的改动导致导出 ONNX 时出现意料之外的问题。我实测下来v6.2 和 v7.0 这两个版本比较稳。v6.2 的代码结构更简洁导出 ONNX 的默认参数对 RKNN 比较友好v7.0 增加了一些新功能但核心导出逻辑没变。我最终用的是 v6.2因为它的export.py脚本参数更少不容易配错。git clone https://github.com/ultralytics/yolov5.git cd yolov5 git checkout v6.2克隆下来之后先别急着装依赖。YOLOv5 的requirements.txt里列了一堆包但有些版本和我们之前装好的 PyTorch 可能冲突。我的做法是手动安装核心依赖跳过那些非必要的包pip install pyyaml matplotlib opencv-python pillow tqdm注意opencv-python建议装opencv-python-headless版本尤其是在服务器环境下避免 GUI 相关的依赖问题。3.2 权重文件的获取与校验YOLOv5s 的预训练权重可以从官方 release 页面下载也可以让脚本自动下载。自动下载的方式很简单在 YOLOv5 目录下执行python -c import torch; model torch.hub.load(ultralytics/yolov5, yolov5s, pretrainedTrue)但这行命令会同时下载仓库代码和权重有时候网络不稳定会失败。更稳妥的方式是直接下载权重文件wget https://github.com/ultralytics/yolov5/releases/download/v6.2/yolov5s.pt下载完之后一定要校验文件完整性。我遇到过一次权重文件下载不完整的情况加载的时候报unexpected EOF错误排查了半天才发现是文件没下完。校验方法很简单看文件大小是否在 14MB 左右ls -lh yolov5s.pt # 正常应该是 14M 左右如果文件大小明显偏小重新下载。另外可以用 PyTorch 加载一下确认没有报错import torch model torch.load(yolov5s.pt, map_locationcpu) print(type(model))正常输出应该是class dict或者模型对象如果报错说明文件有问题。3.3 权重加载验证与模型结构确认拿到权重之后建议先跑一次推理验证确认模型能正常工作。这一步看起来多余但实际上能提前发现很多问题比如权重和代码版本不匹配、依赖包缺失等。import torch from models.experimental import attempt_load model attempt_load(yolov5s.pt, map_locationcpu) model.eval() print(Model loaded successfully) print(fNumber of parameters: {sum(p.numel() for p in model.parameters())})YOLOv5s 的参数量大概在 720 万左右如果输出的数字差太多说明权重加载有问题。另外可以打印一下模型的输出层信息确认检测头是三个尺度for name, module in model.named_modules(): if detect in name.lower(): print(name, module)正常情况下应该能看到三个 Detect 层分别对应 stride 8、16、32 的特征图。这个信息在后面转 ONNX 和 RKNN 的时候会用到因为 RKNN 需要知道输出节点的名称和数量。4. ONNX 导出全流程参数配置与验证方法4.1 导出脚本的关键参数解读YOLOv5 自带的export.py脚本可以直接用来导出 ONNX但默认参数不一定适合 RK3588。我建议手动指定几个关键参数而不是直接用默认值。核心参数有这几个--weights指定权重文件路径--img-size输入图像尺寸RK3588 上常用 640x640--batch-size批处理大小端侧部署一般设为 1--opsetONNX 算子集版本建议用 12--include指定导出格式为 onnx--simplify是否简化模型建议开启导出命令python export.py --weights yolov5s.pt --img-size 640 640 --batch-size 1 --opset 12 --include onnx --simplify这里重点说一下--opset 12的选择理由。ONNX 算子集版本越高支持的算子越多但 RKNN-Toolkit2 对高版本算子集的支持有限。我试过 opset 13 和 15导出后在 RKNN 转换阶段都出现过算子不支持的问题。opset 12 是一个比较保守的选择覆盖了 YOLOv5s 需要的所有算子同时 RKNN 兼容性最好。--simplify参数会调用 onnx-simplifier 对模型进行简化去掉一些冗余的算子。这个步骤能显著减少 RKNN 转换时的报错概率强烈建议开启。但需要先安装 onnx-simplifierpip install onnx-simplifier4.2 导出过程中的常见报错与处理导出过程中最常见的报错是RuntimeError: Exporting the operator ... to ONNX opset version 12 is not supported。这个错误通常是因为 PyTorch 版本和 opset 版本不匹配导致的。解决办法有两个一是降低 opset 版本到 11二是升级 PyTorch 到 1.12 以上。我推荐后者因为 opset 11 对某些算子的支持不完整。另一个常见问题是AttributeError: Upsample object has no attribute recompute_scale_factor。这是 PyTorch 1.11 之后引入的一个兼容性问题YOLOv5 v6.2 的代码没有适配。解决办法是修改models/common.py里的 Upsample 类把recompute_scale_factor参数去掉或者直接升级 YOLOv5 到 v7.0。还有一个坑是导出后的 ONNX 模型输出节点名称。YOLOv5 默认导出的输出节点叫output但 RKNN 转换时需要明确指定输出节点。我建议在导出时用--output-names参数自定义输出节点名称方便后面 RKNN 配置python export.py --weights yolov5s.pt --img-size 640 640 --batch-size 1 --opset 12 --include onnx --simplify --output-names output0 output1 output24.3 ONNX 模型验证与推理测试导出完成后必须验证 ONNX 模型能不能正常推理。这一步能发现很多隐藏问题比如输出维度不对、算子计算错误等。import onnx import onnxruntime as ort import numpy as np # 加载模型 onnx_model onnx.load(yolov5s.onnx) onnx.checker.check_model(onnx_model) print(ONNX model check passed) # 创建推理会话 session ort.InferenceSession(yolov5s.onnx) # 查看输入输出信息 for inp in session.get_inputs(): print(fInput: {inp.name}, shape: {inp.shape}, type: {inp.type}) for out in session.get_outputs(): print(fOutput: {out.name}, shape: {out.shape}, type: {out.type}) # 构造随机输入测试 dummy_input np.random.randn(1, 3, 640, 640).astype(np.float32) outputs session.run(None, {session.get_inputs()[0].name: dummy_input}) for i, out in enumerate(outputs): print(fOutput {i} shape: {out.shape})正常情况下三个输出节点的 shape 应该是[1, 25200, 85]或者类似的格式。25200 是 80x80 40x40 20x20 三个尺度特征图的预测框总数85 是 4 个坐标 1 个置信度 80 个类别概率。如果 shape 不对说明导出参数有问题需要回头检查。4.4 模型轻量化与量化前的准备虽然这篇文章主要讲环境搭建和模型获取但既然提到了 ONNX顺便说一下量化前的准备工作。RK3588 的 NPU 对 INT8 量化支持最好FP16 也能跑但性能会打折扣。在转 RKNN 之前需要准备一组校准图片用来做量化校准。校准图片的准备原则是数量不用太多100 到 200 张就够内容要覆盖实际部署场景中的典型画面分辨率不需要和模型输入一致RKNN 工具会自动处理。我一般从训练集或者实际场景中随机抽一批图片放到一个文件夹里后面 RKNN 转换时指定这个文件夹路径就行。# 校准图片目录结构示例 calibration_images/ ├── img_001.jpg ├── img_002.jpg ├── ... └── img_200.jpg另外ONNX 模型在量化前最好先做一次简化去掉不必要的算子。除了前面提到的--simplify参数还可以用 onnx-simplifier 单独处理python -m onnxsim yolov5s.onnx yolov5s_sim.onnx简化后的模型在 RKNN 转换时成功率更高而且推理速度也会略有提升。5. 实操中的常见问题与排查技巧5.1 环境类问题速查表问题现象可能原因解决方法ImportError: libGL.so.1缺少 OpenCV 系统依赖apt install libgl1-mesa-glxModuleNotFoundError: No module named rknnRKNN-Toolkit2 未安装或环境不对确认 conda 环境已激活重新安装 whlprotobuf version conflictprotobuf 版本过高pip install protobuf3.19.6numpy has no attribute objectnumpy 版本过高pip install numpy1.23.5torch.onnx.export报算子不支持opset 版本不匹配降低 opset 到 12 或升级 PyTorchONNX 模型加载失败文件下载不完整重新下载校验文件大小5.2 我踩过的三个典型坑第一个坑是 conda 环境和系统环境的混淆。我在 conda 环境里装了 RKNN-Toolkit2但执行脚本的时候忘了激活环境用的是系统 Python结果一直报No module named rknn。排查了半天才发现是环境没激活。这个问题的教训是每次打开新终端第一件事就是conda activate rknn_yolov5养成习惯。第二个坑是 ONNX 导出时的动态轴设置。YOLOv5 的export.py默认会设置动态 batch 轴但 RK3588 部署时 batch 固定为 1动态轴反而会导致 RKNN 转换失败。解决办法是在导出时加--dynamic参数的反向操作或者手动修改导出脚本把 dynamic_axes 设为 None。我后来直接在导出命令里加了--batch-size 1并且确认导出的 ONNX 没有动态维度。第三个坑是权重文件的版本匹配。我有一次用 YOLOv5 v7.0 的代码加载 v6.2 的权重虽然能加载成功但推理结果完全不对。原因是两个版本的模型结构有细微差异权重对不上。后来我统一用 v6.2 的代码和 v6.2 的权重问题就消失了。所以版本一致性这件事在模型部署里怎么强调都不为过。5.3 验证环境是否就绪的完整检查清单在进入下一步 RKNN 转换之前建议按这个清单逐项检查conda 环境已激活Python 版本为 3.8PyTorch 能正常 import版本在 1.10 到 1.13 之间ONNX 和 ONNX Runtime 能正常 importRKNN-Toolkit2 能正常 importfrom rknn.api import RKNN不报错YOLOv5s 权重文件大小正常能正常加载ONNX 模型已导出onnx.checker.check_model通过ONNX Runtime 推理测试通过输出 shape 正确校准图片文件夹已准备好至少有 100 张图片这八项都确认无误之后环境搭建和模型获取这一步就算彻底完成了。后面转 RKNN 的时候如果遇到问题基本可以排除环境因素直接聚焦在转换参数和模型结构上。6. 关于工具链版本锁定的一点个人经验环境搭建这件事最怕的就是版本漂移。今天装好的环境过两个月重新装一遍可能因为某个包的版本更新了就跑不起来了。我的做法是把所有关键包的版本号记录在一个requirements_lock.txt文件里下次重建环境的时候直接按这个文件装。torch1.12.1 torchvision0.13.1 onnx1.12.0 onnxruntime1.12.1 numpy1.23.5 protobuf3.19.6 opencv-python-headless4.6.0.66这个文件看起来不起眼但在我后来换开发机、重装系统的时候省了大量时间。直接pip install -r requirements_lock.txt十分钟就能把环境恢复到位不用再一个个排查版本冲突。另外RKNN-Toolkit2 的 whl 文件建议本地备份一份。瑞芯微的 GitHub 仓库有时候会调整 release 页面旧版本的 whl 不一定能随时下载到。我习惯把 whl 文件和对应的 ONNX 模型放在同一个目录下标注好版本号和日期这样即使过了半年再回头看也能快速复现当时的环境。模型获取这一步权重文件同样建议本地存档。YOLOv5 的 release 页面虽然稳定但网络问题谁也说不准。我一般会把yolov5s.pt和导出的yolov5s.onnx一起放到项目目录的weights/文件夹下用 git-lfs 或者直接压缩备份。这样后面做 RKNN 转换、量化、精度对比的时候随时都能拿到原始文件不用重新下载。环境搭建和模型获取是整个部署流程的地基地基打牢了后面的转换和调优才能顺利进行。下一篇会讲 RKNN 转换的具体操作包括量化参数配置、精度对比方法、以及如何在 RK3588 上跑通第一次推理。如果你在环境搭建阶段遇到了这里没提到的问题大概率是某个依赖包的版本不对按上面说的版本锁定思路排查一遍基本都能解决。
