1. 为什么环境搭建这一步值得单独拎出来讲很多人拿到 RK3588 开发板的第一反应是直接插电、烧系统、跑 demo觉得环境搭建不过是“装几个软件”的体力活。我一开始也这么想结果在 YOLOv5s 这条链路上来回折腾了整整三天才发现真正卡人的从来不是模型本身而是环境里那些看起来不起眼、但一旦错位就全盘报错的依赖关系。这一篇聚焦的是全链路的第二段在 PC 端把训练/转换环境搭好并把 YOLOv5s 的模型权重拿到手、导出成 ONNX。听起来简单但它决定了后面 NPU 转换能不能顺利跑通。RK3588 的 NPU 走的是 RKNN 工具链而 RKNN 对 ONNX 的算子、输入输出格式、动态维度都有比较明确的要求。如果前面 PyTorch 环境版本乱了、ONNX 导出参数没设对后面在 RKNN-Toolkit2 里就会遇到一堆“Unsupported op”或者维度对不上的报错排查起来非常痛苦。所以这篇我会把环境搭建拆成三块来讲PC 端 PyTorch 环境的搭建含 WSL 方案、YOLOv5s 官方模型的获取与验证、PyTorch 转 ONNX 的完整实操与参数解读。每一块我都会说清楚“为什么这么选”而不是只给一串命令让你照抄。适合正在做 RK3588 边缘部署、准备把 YOLO 系列模型往 NPU 上搬的开发者也适合刚接触模型转换、想搞清楚 ONNX 到底是个什么东西的朋友。先给一个整体判断环境搭建的核心不是装得多全而是版本对得上。PyTorch、torchvision、ONNX、onnxruntime 这几个包之间存在严格的版本兼容矩阵随便 pip install 最新版十有八九会在导出或推理时炸掉。这一点我在后面会给出具体的版本组合和验证方法。2. 环境整体设计与方案选型思路2.1 为什么选 WSL 而不是纯 Windows 或纯 Linux做 RK3588 部署PC 端环境有三种常见选择纯 Windows、纯 Linux 物理机/虚拟机、Windows WSL2。我最终选的是WSL2 Ubuntu 22.04理由很实际。纯 Windows 下装 PyTorch 本身没问题但 YOLOv5 官方仓库的很多脚本、依赖比如某些编译型包在 Windows 上会遇到路径分隔符、编译工具链的问题尤其是后面如果要装 RKNN-Toolkit2官方基本只提供 Linux 版本的 wheel 包Windows 上要么没有要么版本滞后。纯 Linux 物理机当然最干净但日常还要用 Windows 办公双系统切换太麻烦。虚拟机方案性能损耗大训练和转换时磁盘 IO 会拖后腿。WSL2 的好处是文件系统直通、性能接近原生 Linux、能和 Windows 共享剪贴板和文件同时 RKNN-Toolkit2 的 Linux wheel 可以直接在里面装。唯一要注意的是 WSL2 的网络和 USB 透传但模型转换阶段用不到 USB所以完全够用。提示WSL2 建议分配至少 8GB 内存和 100GB 磁盘。模型转换虽然不吃 GPU但 ONNX 导出和后续量化会占用不少内存内存太小容易在中途被 OOM kill 掉。2.2 Python 环境为什么用 conda 而不是系统自带Ubuntu 22.04 自带 Python 3.10直接用系统 Python 装包看似省事但有两个坑一是系统 Python 被 apt 管理某些包版本被锁死装 PyTorch 时容易和系统包冲突二是后面 RKNN-Toolkit2 对 Python 版本有要求一般是 3.8 到 3.10如果系统 Python 升级或降级会影响一堆系统工具。所以我用Miniconda 创建独立虚拟环境把 YOLOv5s 相关的所有依赖隔离在一个叫yolov5的环境里。这样即使装崩了删掉环境重建就行不会污染系统。conda 的另一个好处是能直接管理 Python 版本比如我可以指定python3.9避开一些新版本 Python 的兼容性问题。2.3 版本选型的核心逻辑这是整篇最关键的部分。我踩过的最大坑就是“无脑装最新版”。PyTorch 2.x 之后 API 有变动YOLOv5 某些老版本代码会报错ONNX 的 opset 版本如果太高RKNN-Toolkit2 可能还不支持。经过实测下面这套组合是最稳的组件推荐版本选择理由Python3.9RKNN-Toolkit2 兼容性好YOLOv5 官方支持PyTorch1.13.1稳定ONNX 导出算子支持完善torchvision0.14.1与 PyTorch 1.13.1 严格对应ONNX1.12.0opset 12/13 支持好RKNN 兼容onnxruntime1.14.0用于验证 ONNX 模型推理正确性numpy1.23.x避免 2.x 带来的兼容问题这里要特别说numpy 版本。numpy 2.0 之后有不少 API 变动很多老包包括某些版本的 onnx会直接报module numpy has no attribute之类的错。所以哪怕你其他都装对了numpy 装成 2.x 一样会翻车。我建议锁在 1.23 或 1.24。注意PyTorch 和 torchvision 必须版本对应不能一个 1.13 一个 0.15。对应关系可以去 PyTorch 官方历史版本页面查装之前先确认别凭感觉。3. 核心细节解析与实操要点3.1 WSL2 与 Ubuntu 环境的准备如果你已经在用 WSL2可以跳过安装部分但建议确认版本。在 Windows PowerShell 里执行wsl --list --verbose确认 Ubuntu 的 VERSION 是 2。如果是 1用wsl --set-version Ubuntu 2升级。WSL1 和 WSL2 的文件系统机制完全不同WSL1 下装 conda 和编译包会各种诡异报错这个坑我替你们踩过了。进入 Ubuntu 后先更新源并装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y build-essential cmake git wget curl unzipbuild-essential和cmake是后面编译某些 Python 包比如 pycocotools必需的不装的话 pip 安装时会报编译错误。这一步很多人会漏等到装依赖报错才回头补。3.2 Miniconda 安装与虚拟环境创建下载 MinicondaLinux 版wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh bash Miniconda3-latest-Linux-x86_64.sh安装过程中一路回车最后会问是否conda init选 yes。然后重开终端让 conda 生效。创建环境conda create -n yolov5 python3.9 -y conda activate yolov5创建完先确认 Python 版本python --version应该是 3.9.x。如果还是系统 Python说明 conda 没激活成功检查conda init是否执行、终端是否重开。3.3 PyTorch 与相关依赖的安装在yolov5环境里装 PyTorch。注意如果你 PC 有 NVIDIA 显卡可以装 CUDA 版加速训练如果只是做模型转换CPU 版足够。这里给 CPU 版命令更通用pip install torch1.13.1 torchvision0.14.1 --index-url https://download.pytorch.org/whl/cpu装完验证python -c import torch; print(torch.__version__); print(torch.cuda.is_available())输出1.13.1和FalseCPU 版就对了。接着装 ONNX 相关pip install onnx1.12.0 onnxruntime1.14.0 numpy1.23.5这里有个细节onnx 和 onnxruntime 是两个不同的东西。onnx 负责定义模型格式和提供导出/检查工具onnxruntime 负责实际执行推理。很多人搜“onnxruntime 和 onnx 区别”就是因为这俩名字太像。简单说导出模型用 onnx验证模型能不能跑用 onnxruntime。3.4 YOLOv5s 官方模型的获取YOLOv5 的官方仓库在 GitHub 上直接 clonegit clone https://github.com/ultralytics/yolov5.git cd yolov5然后安装仓库依赖pip install -r requirements.txt这里要注意requirements.txt 里可能会把 torch 版本覆盖掉。装完后重新确认一下 torch 版本如果被改了重新装回 1.13.1。模型权重有两种获取方式。第一种是直接下载官方预训练权重yolov5s.ptwget https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5s.pt第二种是如果你自己训练过用自己产出的.pt文件。这里我用官方yolov5s.pt做演示因为它是最标准的基线后面转换出问题也容易定位是环境问题还是模型问题。提示下载权重时注意版本。YOLOv5 有 v6.0、v7.0 等多个 release不同版本的模型结构略有差异。建议统一用 v7.0和当前仓库代码匹配。3.5 模型加载验证拿到yolov5s.pt后先别急着转 ONNX先验证模型能正常加载和推理。用仓库自带的 detect 脚本跑一张测试图python detect.py --weights yolov5s.pt --source data/images/bus.jpg --device cpu如果输出runs/detect/exp/下有标注好的图片说明 PyTorch 环境、模型、依赖全部正常。这一步是“基线验证”非常重要。很多人跳过这步直接转 ONNX结果 ONNX 报错时分不清是环境问题还是转换问题。先把 PyTorch 侧跑通后面排查范围就小了一半。4. PyTorch 转 ONNX 的完整实操4.1 导出脚本与关键参数YOLOv5 仓库自带export.py可以直接导出 ONNXpython export.py --weights yolov5s.pt --include onnx --opset 12 --img 640这条命令背后做了几件事加载 PyTorch 权重、构建模型、用一张 640x640 的假输入做前向推理、把计算图导出成 ONNX 格式。几个参数必须说清楚--opset 12ONNX 算子集版本。RKNN-Toolkit2 对 opset 的支持一般到 12 或 13太高会不认。选 12 是最稳的。--img 640输入分辨率。YOLOv5s 默认 640如果你后面要改输入尺寸这里要同步改否则 ONNX 的输入维度会和 RKNN 配置对不上。--include onnx指定导出格式可以同时导出多种。导出成功后会在yolov5s.pt同目录生成yolov5s.onnx。4.2 导出后的结构检查导出完别急着用先用 onnx 自带的工具检查模型结构python -c import onnx; m onnx.load(yolov5s.onnx); onnx.checker.check_model(m); print(check passed)输出check passed说明 ONNX 文件结构合法。然后看输入输出python -c import onnx m onnx.load(yolov5s.onnx) for i in m.graph.input: print(input:, i.name, [d.dim_value for d in i.type.tensor_type.shape.dim]) for o in m.graph.output: print(output:, o.name, [d.dim_value for d in o.type.tensor_type.shape.dim]) 正常应该看到输入是[1, 3, 640, 640]输出是三个不同尺度的特征图。如果输入维度里出现-1或dynamic说明导出时带了动态维度RKNN 转换时可能需要额外处理。YOLOv5 默认导出是固定维度的一般不会出这个问题。4.3 用 onnxruntime 验证推理一致性这一步是很多人忽略但极其重要的验证 ONNX 模型的输出和 PyTorch 是否一致。如果 ONNX 导出时算子映射出错模型可能“能跑但结果不对”这种问题在 RKNN 阶段很难发现。写个简单脚本对比import torch import onnxruntime as ort import numpy as np # PyTorch 推理 model torch.hub.load(ultralytics/yolov5, custom, pathyolov5s.pt) dummy torch.randn(1, 3, 640, 640) with torch.no_grad(): pt_out model(dummy)[0] # ONNX 推理 sess ort.InferenceSession(yolov5s.onnx) onnx_out sess.run(None, {images: dummy.numpy()}) # 对比 diff np.abs(pt_out.numpy() - onnx_out[0]).max() print(max diff:, diff)max diff在 1e-4 量级以内就算正常。如果差得离谱说明导出有问题需要检查 opset 或模型版本。注意YOLOv5 的model(dummy)返回结构可能因版本而异如果报错用model.forward或调整输入格式。核心目的是拿到 PyTorch 的原始输出张量做对比。4.4 关于模型轻量化的前置思考虽然这篇重点是环境搭建和模型获取但既然提到了 RK3588 部署有必要提前说一句YOLOv5s 直接转 RKNN 后在 RK3588 上的推理速度取决于 NPU 的算力分配和量化策略。如果你后面发现帧率不理想可以考虑模型轻量化比如剪枝、通道裁剪或者换更小的输入尺寸。但这些操作要在 ONNX 导出之前做因为 RKNN 工具链对已经量化过的模型再做修改会很麻烦。所以建议在环境搭建阶段就把“是否需要轻量化”想清楚。如果只是验证流程用官方yolov5s.pt就够如果要上生产可能需要在 PyTorch 侧先做一轮优化再导出。5. 常见问题与排查技巧实录5.1 环境类问题速查问题现象可能原因解决方法ImportError: libGL.so.1缺少 OpenCV 系统依赖sudo apt install libgl1-mesa-glxpip 安装 torch 极慢或超时默认源在国外换国内镜像源或加--index-urlnumpy相关 AttributeErrornumpy 版本过高降级到 1.23.xconda 激活后 python 版本没变conda init 未生效重开终端或手动 sourceWSL2 磁盘占满conda 缓存和 pip 缓存堆积conda clean -a和pip cache purge5.2 ONNX 导出类问题问题一导出时报Unsupported op。通常是 opset 版本和模型算子不匹配。YOLOv5 里有些算子比如 SiLU 激活在低 opset 下没有对应实现。解决办法是把 opset 提到 12 或 13或者用 YOLOv5 仓库自带的导出脚本它内部做了算子替换。问题二ONNX 模型能加载但推理结果全错。大概率是输入预处理不一致。PyTorch 侧输入是 RGB、归一化到 0-1、再减均值除方差ONNX 推理时如果直接喂原始像素结果肯定不对。验证一致性时一定要用同样的预处理。问题三输出维度对不上。YOLOv5 的输出是三个尺度的特征图拼接如果导出时--img和后面 RKNN 配置的输入尺寸不一致输出维度就会错位。养成习惯导出前确认输入尺寸导出后打印输入输出维度。5.3 我踩过的几个真实坑第一个坑是conda 环境和系统环境混用。有次我在没激活 conda 的终端里跑 export.py结果用的是系统 Pythontorch 版本不对报了一堆莫名其妙的错。后来养成习惯每次操作前先conda activate yolov5并在脚本开头打印sys.executable确认用的是哪个 Python。第二个坑是ONNX 文件路径。export.py 默认输出到权重同目录但如果你在别的目录执行可能找不到文件。建议用绝对路径或者导出后ls确认一下。第三个坑是onnxruntime 的 provider。默认 CPU provider 就够验证但如果你装了 GPU 版 onnxruntime可能会因为 CUDA 版本不匹配报错。验证阶段用 CPU 版最省心。5.4 关于模型文件格式的补充说明搜索热词里出现了“如何获取官方 ibis 模型文件.ibs 格式”这里顺带说一句.ibs是某些厂商工具链的中间格式和 ONNX 不是一回事。RK3588 这条链路走的是 ONNX → RKNN不涉及.ibs。如果你在别的平台看到.ibs那是那套工具链自己的封装不要混用。模型格式转换的核心原则是每一级转换都要验证不要跨级跳。PyTorch 验证完再转 ONNXONNX 验证完再转 RKNN这样出问题能快速定位。6. 环境搭建完成后的下一步衔接到这里PC 端的 PyTorch 环境、YOLOv5s 模型、ONNX 导出和验证都跑通了。你现在手里应该有一个经过 onnxruntime 验证、输入输出维度明确的yolov5s.onnx文件。这个文件就是下一阶段 RKNN 转换的输入。在进入 RKNN 之前建议再做一件事把 ONNX 模型的输入输出信息、opset 版本、文件大小记录到一个文档里。后面在 RKNN-Toolkit2 里配置mean_values、std_values、target_platform时都要参考这些信息。我自己的习惯是建一个model_info.md把每次导出的参数都记下来避免后面忘了当时用的什么配置。另外提醒一句RKNN-Toolkit2 建议装在单独的 conda 环境里不要和 YOLOv5 的环境混用。因为 RKNN 对 numpy、onnx 的版本要求可能和 YOLOv5 冲突混在一起容易互相干扰。我一般是yolov5环境负责导出rknn环境负责转换两个环境通过 ONNX 文件解耦这样最干净。最后分享一个我自己的小习惯每次环境搭好后用conda env export env_backup.yaml把环境导出备份。下次换机器或者环境崩了直接conda env create -f env_backup.yaml就能复现省去重新排查版本的时间。这个操作花不了一分钟但能救命。
