企业官网建设流程全解析

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建独立虚拟环境，不要污染系统 Python：

sudo 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 12：ONNX 算子集版本。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 环境搭建阶段的典型报错

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.txt

config.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_values：YOLOv5 通常是[[0,0,0]]和[[255,255,255]]
• target_platform：填rk3588
• quantized_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] memory=16GB processors=8

重启 WSL 之后稳定多了。

第二个坑是 ONNX 的输入节点名称。YOLOv5 导出的 ONNX 输入节点叫images，但有些转换脚本默认找input，导致报错。用 Netron 打开看一眼就能确认，不要凭猜。

第三个坑是模型文件路径。RKNN-Toolkit2 的某些版本对相对路径支持不好，转换脚本里最好用绝对路径。这个问题排查起来很费时间，因为报错信息不直接指向路径问题。

8. 后续可以扩展的方向

环境搭好、模型导出成功之后，下一步就是 RKNN 转换和板端部署。如果你想让模型跑得更快，可以研究一下 YOLOv5s 的轻量化——比如把 backbone 换成 MobileNet 系列，或者用剪枝工具压缩通道数。RK3588 的 NPU 算力虽然不错，但模型越小，帧率越高，功耗也越低。

另外，如果你要做多路视频输入，RK3588 的 MIPI 接口和 SPI 接口配置也需要提前规划。这些内容我会在后续的部署篇里展开。

最后分享一个小技巧：每次修改环境或模型之后，用pip freeze > requirements_lock.txt把当前依赖版本冻结下来。后面环境崩了，直接按这个文件重建，比重装一遍快得多。这个习惯帮我省了至少两次重装系统的时间。