RK3588部署YOLOv5s实战：环境搭建与模型转换全流程

这个系列做到第二篇了。上一篇我把从 RK3588 到 YOLOv5s 的整条部署链路整体透了一遍，这一篇开始真正动手：先解决环境搭建和模型获取两个前置问题。这里先把结论放在前面——别急着在板子上把一切都装齐，RK3588 部署 YOLOv5s 的正确姿势通常是“PC 端负责模型转换，板端只负责推理”的双机配合。我最初也试过把所有工具链都折腾到板子上，结果反而在 x86、ARM 两套架构之间来回踩坑。这篇我就按实际操作的顺序，把环境怎么搭、模型怎么拿、格式怎么转一步步写清楚，全程基于我手头这块 RK3588 开发板的真实过程，尽量让同样刚入手的同学能照着做。

1. 整体思路：为什么“PC 转换 + 板端推理”是最高效的组合

开始装软件之前，先用一小节把部署 YOLOv5s 到 RK3588 的整体流转讲清楚，避免后面装了半天发现装错了地方。

1.1 整套模型流转链路是怎样的

一个 YOLOv5s 模型要从 PyTorch 权重变成 RK3588 芯片上 NPU 能直接跑的模型，中间至少要经过两次格式转换：先是pt → ONNX，再由ONNX → RKNN。RKNN 是瑞芯微 NPU 专用的模型格式，RK3588 的 3 个 NPU 核只认这种格式，它内部会做算子映射、权重重排以及可能的 INT8 量化。

所以完整链路是：拿到yolov5s.pt权重 → 导出成yolov5s.onnx→ 用 RKNN-Toolkit2 转成yolov5s.rknn→ 把 rknn 文件丢到开发板上，用板端的推理库加载运行。其中第 2 步到第 3 步的转换工具是 PC 端（x86）的 Python 包，板端也有简化版，但实际体验差别很大。

这就自然引出了环境上的分工：PC 端负责模型转换和量化调试，板端负责最终推理和性能验证。如果你非要反着来，在板子上安装全套 RKNN-Toolkit2 和 PyTorch，倒也能跑，但 ARM 平台编译依赖容易出各种奇怪的问题，而且模型转换是重计算任务，PC 端明显更顺手。

1.2 系统与工具链选型：Ubuntu 20.04 + Python 3.8 最稳

拿我这次用的环境来说，PC 端我用的是 Ubuntu 20.04，Python 3.8，装了 RKNN-Toolkit2 和 YOLOv5 官方仓库；板端同样刷了基于 Ubuntu 20.04 的官方固件，板端只需要再装一个 RKNN Toolkit Lite2 和基本的 Python 环境。

为什么这么保守？因为 RKNN-Toolkit2 官方文档和社区反馈里，Ubuntu 20.04 + Python 3.8 的兼容性最好，依赖的多个底层库在 3.8 下都能找到合适版本。Python 3.10 或 Ubuntu 22.04 也能跑，但装 tensorflow、opencv 这些老依赖时容易遇到版本冲突，对新手很不友好。我这里不是建议你永远不用新版本，而是说第一遍跑通全流程时，请尽量复刻已经被验证过的环境组合，少消耗一点排查问题的时间。

如果你用的 Windows，想处理模型转换，正确的姿势也还是WSL 里装一个 Ubuntu 20.04，而不是直接在 Windows 上尝试跑 RKNN-Toolkit2。官方虽然也有 Windows 版本支持，但体验明显不如 Linux，一些依赖库在 Windows 上的坑更多。

在动手装之前，把链路想明白，能帮你省掉后面至少一半的折腾。

2. 板端环境：RK3588 烧录系统后的基础配置

先把板子这一侧搞定。RK3588 芯片本身是一颗 8 核 SoC，4 个 A76 大核加 4 个 A55 小核，NPU 算力 6 TOPS，跑 YOLOv5s 这种量级的模型绰绰有余。但芯片再强，系统起不来一切都是空谈。

2.1 烧录前要准备的东西：USB 线与 MaskRom 模式

拿到 RK3588 开发板以后，第一件事是把系统烧进去。多数开发板出厂会预装系统，但版本往往比较旧，或者自带了厂商一堆用不上的服务，所以我建议直接用自己下到的 Ubuntu 20.04 镜像重烧一遍。

你需要准备：一根质量靠谱的 USB Type-C 数据线（能传数据，不能是纯充电线）、一个 5V/4A 左右的电源（RK3588 满载功耗不低，便宜电源会让系统随机重启）、以及一台 Windows 或 Linux 电脑。

烧录前要让开发板进入 MaskRom 模式。做法一般是：先按住板上标着 MaskRom 或者 Recovery 的按键，再插 USB 线连接电脑，最后上电。具体按键位置不同板子不一样，但逻辑相同。进入成功后，Windows 设备管理器里会看到一个 USB 设备变化，Linux 下用lsusb也能看到新的设备。

2.2 RKDevTool 与 upgrade_tool 两种烧录方式

Windows 下我推荐用瑞芯微官方的 RKDevTool。打开软件后，进入“升级固件”页面，点击“选择文件”找到下载的update.img整包，然后点“执行”开始烧录。这里有个细节：如果之前烧过其他版本，先点一下“擦除 Flash”再烧，能避免底层分区不一致导致启动失败。

Linux 下对应的工具叫upgrade_tool，命令行操作，也差不多这个逻辑。烧录过程大约持续几分钟，期间不要拔线、不要断电，等进度条走完，板子会自动重启进入 Ubuntu。

如果你手头只有 SD 卡槽版本，也可以直接用balenaEtcher之类的工具把镜像写入 TF 卡，插入卡槽后从 SD 卡启动。两种方式本质没区别，我习惯用 USB 整包烧写，因为后面升级内核、换系统更方便。

2.3 开机后的基础环境调整：SSH、apt 源、Python

系统起来以后，先别急着装任何东西，按这个顺序把基础环境弄顺：

先登入桌面或串口终端，执行：

sudo apt update sudo apt install -y openssh-server sudo systemctl enable --now ssh

然后把开发板接到路由器上，查一下它的 IP，电脑上用 MobaXterm 或 Windows Terminal 直接 SSH 登录，后续都不需要再插显示器和键盘了。这一步很关键，因为我后续的所有操作都是在 SSH 里完成的。

接下来换 apt 源。Ubuntu 20.04 的默认官方源在国内更新速度太慢，我把sources.list换成了清华源，方法就是用 sed 批量替换：

sudo sed -i 's/archive.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list sudo sed -i 's/security.ubuntu.com/mirrors.tuna.tsinghua.edu.cn/g' /etc/apt/sources.list sudo apt update

然后装基础开发包：

sudo apt install -y python3-pip python3-venv cmake build-essential

Ubuntu 20.04 自带的 Python 版本就是 3.8，这一点非常重要。pip装包之前建议配置好国内镜像：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

到这里，板端的基础环境就绪了。

2.4 验证 NPU 驱动是否正常

RK3588 芯片的 NPU 驱动在官方固件里是默认编译进内核的，但最好确认一下。在 SSH 终端执行：

dmesg | grep rknpu

如果能看到类似rknn或rknpu初始化的日志，说明 NPU 驱动已经正常加载。部分固件在运行时还可以查看 NPU 负载：

cat /sys/kernel/debug/rknpu/load 2>/dev/null || cat /proc/rknpu/load 2>/dev/null

如果这些路径都不存在，也不要慌，先确认你是不是用的官方固件。非官方固件或精简固件可能把 NPU 驱动裁掉了，那后面运行 rknn 模型时会直接报“Cannot load rknn model”之类的错误。

NPU 驱动这一步很多人会忽略，但它决定了后面推理环节能不能跑起来。我建议一次性确认好，省得到时候排查半天找不到方向。

3. PC 端环境：RKNN-Toolkit2、PyTorch 与权重下载

板端只是运行环境，真正麻烦的模型转换工作都在 PC 端完成。这一节我把 PC 端环境的搭建细节写透。

3.1 用 conda 隔离环境，别污染系统 Python

RKNN-Toolkit2、PyTorch、OpenCV 这些库的依赖关系比较敏感。我强烈建议在 PC 端用 conda 单独建一个虚拟环境，不要往系统 Python 里硬塞。先装好 Miniconda，然后执行：

conda create -n rknn python=3.8 -y conda activate rknn

这里用 Python 3.8 的原因我在前面提过，是为了和 RKNN-Toolkit2 的依赖兼容。环境建好以后，后续所有包都装在这个环境里，出问题直接删掉重建，不影响系统。

Python 版本确认无误后，先把 pip 源也配置成国内镜像：

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

3.2 RKNN-Toolkit2 安装最容易踩的依赖坑

RKNN-Toolkit2 是以 whl 包形式提供的，从官方 GitHub 仓库或网盘下载后直接 pip 安装。假设你下载到的文件是rknn_toolkit2-2.0.0b0-cp38-cp38-linux_x86_64.whl，那就：

pip install rknn_toolkit2-2.0.0b0-cp38-cp38-linux_x86_64.whl

它会自动拉取一堆依赖。这里有一个非常经典的坑：依赖里的numpy如果被装到了 2.x 版本，大概率会在转换模型时报类似module 'numpy' has no attribute 'bool'的错误，因为在 numpy 1.24 以后，np.bool这个别名被移除了。RKNN-Toolkit2 内部有些旧代码还引用它。

解决办法就是把 numpy 降级：

pip install numpy==1.23.5

如果你不够走运，还遇到libGL.so.1: cannot open shared object file的报错，说明系统缺少 OpenCV 依赖的动态库，装一下就行：

sudo apt install -y libgl1 libglib2.0-0

装完之后，用一条命令确认导入成功：

python -c "from rknn.api import RKNN; print('rknn ok')"

能正常打印rknn ok，这一关就算过了。

3.3 YOLOv5 官方仓库与 yolov5s 权重下载

模型转换环节需要用到 YOLOv5 的官方仓库做 PT 到 ONNX 的导出，以及预训练权重。克隆仓库并安装依赖：

git clone https://github.com/ultralytics/yolov5.git cd yolov5 pip install -r requirements.txt

这里requirements.txt会装 PyTorch、torchvision、OpenCV 等。PC 端不需要 CUDA，CPU 版 PyTorch 足够完成推理和导出。国内如果拉取慢，可以找 gitee 上同步的镜像仓库，或者用git clone --depth 1只拉最新代码。

权重文件是官方在 COCO 数据集上预训练好的yolov5s.pt，目标检测入门常用它验证全流程。下载方式：

mkdir weights wget -c https://github.com/ultralytics/yolov5/releases/download/v7.0/yolov5s.pt -O weights/yolov5s.pt

如果 GitHub 下载速度太慢，到国内一些模型镜像站点也能找到同名文件，注意核对文件大小。yolov5s.pt大小在 14MB 上下（权重是 FP32 的），如果下载下来只有几 KB，那大概率是下载到了错误页面。

下载完可以先快速验证一下模型是否完好：

python detect.py --weights weights/yolov5s.pt --img 640 --conf 0.25 --source data/images/bus.jpg

能看到检测框正常出现，说明权重没问题，接下来就可以做导出转换了。

4. 模型获取到 RKNN 模型：从 PT 到 ONNX 再到 RKNN

环境准备好后，进入本篇的重头戏：把yolov5s.pt变成yolov5s.rknn。这里每一步都值得仔细看，因为后面板端推理时很多诡异问题都源自这一步的错误选择。

4.1 官方权重 vs 自训练模型：第一步就要想清楚

你手上要转的模型，是直接用官方 COCO 预训练权重，还是自己训练出来的自定义模型？这一步看似简单，实际影响后面的所有配置。

如果用官方权重，那么类别数固定是 80，anchors 也是 COCO 默认那组，YOLOv5 的导出脚本直接跑就行。如果用的是自己训练的模型，比如只检测 2 个类别的模型，那导出 ONNX 时类别数不同，后续 RKNN 转换脚本里的后处理逻辑也要同步改。很多人拿到自定义模型后不管类别数差异，转换倒是成功了，但板端推理结果全是乱的，就是这个原因。

另外，如果你的自定义模型是从某个旧版 YOLOv5 改出来的，anchors可能也不一样。转换 RKNN 模型本身不受 anchors 影响，但板端后处理如果你手工写了锚框解码，就务必保证数值与模型训练时一致。

4.2 导出 ONNX：官方 export.py 的正确用法

YOLOv5 官方仓库提供了一个现成的导出脚本，进入 YOLOv5 目录执行：

python export.py --weights weights/yolov5s.pt --img 640 --include onnx --opset 12

这里几个参数的含义：

• --img 640：导出模型的训练输入分辨率，跟训练时保持一致即可。
• --include onnx：只导出 ONNX，不导出其他格式。
• --opset 12：ONNX 算子集版本，RKNN-Toolkit2 对 opset 12 支持比较成熟。

导出成功后，会在目录下生成yolov5s.onnx，体积大概 30MB。建议用 Netron 打开看一眼结构。YOLOv5s 的 ONNX 会输出三个检测头，输出的 shape 一般是[1, 3, 80, 80, 85]、[1, 3, 40, 40, 85]、[1, 3, 20, 20, 85]，其中 85 = 5 + 80，对应 4 个框坐标、1 个置信度和 80 个类别分数。看明白了输出结构，后面写板端解码逻辑时心里就有数。

4.3 转成 RKNN：target_platform 与量化参数详解

RKNN-Toolkit2 自带 YOLOv5 示例，目录一般在rknn-toolkit2/examples/onnx/yolov5。我建议直接基于官方示例改，不要自己从零写脚本，因为官方脚本里已经包含了 YOLOv5 的输出后处理，能省很大功夫。

关键配置在代码里体现为这样一段：

from rknn.api import RKNN rknn = RKNN() rknn.config(target_platform='rk3588', mean_values=[[0, 0, 0]], std_values=[[255, 255, 255]]) rknn.load_onnx(model='yolov5s.onnx') rknn.build(do_quantization=True, dataset='dataset.txt') rknn.export_rknn('yolov5s.rknn')

这里每个参数都要理解：

• target_platform='rk3588'：明确告诉转换工具目标芯片是 RK3588，工具会据此选择算子映射和 NPU 指令集。
• mean_values和std_values：决定输入图片如何做归一化。YOLOv5 官方推理时是把图片像素除以 255，所以 mean 是 0，std 是 255。
• dataset.txt：量化校准图片列表文件。每行写一张图片的完整路径，至少要几十张，建议 100~200 张，图片内容尽量覆盖你后面要检测的场景。这些图片会被用来统计激活值分布，决定 INT8 量化参数。千万不要只放两三张图就量化，精度会掉得很厉害。
• do_quantization=True：启用 INT8 量化。如果设成 False，会生成 FP16 模型，精度更好一点，但模型体积更大、推理速度更慢，NPU 的优势也发挥不出来。

转换过程如果顺利，会生成yolov5s.rknn。INT8 量化后的模型体积基本在 7~8MB，相比 30MB 的 ONNX 小了很多，这也是模型部署时最直观的轻量化收益。

4.4 模型轻量化是怎么回事：INT8、输入分辨率与换结构

说到轻量化，很多新手会直接想到把模型换小、把图片分辨率调低，但实际部署 RK3588 时，轻量化是几个手段叠加的效果。

其实在模型选择上，YOLOv5s 本身就是 YOLOv5 系列里轻量化的代表。以 COCO 数据集为例，YOLOv5s 的参数量约 7.2M，计算量约 16.5 GFLOPs，检测精度 mAP 约 37.2，和更大的 YOLOv5m（参数量 21.2M，mAP 约 44.5）相比，换来的收益是推理速度成倍增加。而 RK3588 的 6 TOPS 算力跑 YOLOv5s 很从容，跑 YOLOv5m 就明显吃紧，所以 s 是板端部署的甜点型号。

量化的减重效果也很明显。同一个模型，FP16 的 RKNN 模型跑起来比 INT8 模型慢不少，因为 NPU 对 INT8 的矩阵计算有专门加速，INT8 量化还能把模型体积压到四分之一左右。代价是精度有小幅下降，如果实测掉点严重，可以先用do_quantization=False生成 FP16 对比一下，确定是量化掉点还是别的问题。

输入分辨率则是另一个杠杆。YOLOv5 默认--img 640，对 RK3588 来说算力是够的。如果你的检测场景里小目标不多，可以降到 416 或 320，推理速度立刻翻倍，但小目标漏检率也会明显上升。在我的实测里，640 和 320 对中大型目标的检测结果差别不大，但小目标差异悬殊，所以分辨率怎么选，取决于你的实际场景，没有绝对最优。

除了这些常规手段，还有一些进阶的轻量化路线，比如知识蒸馏、通道剪枝，以及干脆换成 YOLOv8n / YOLOv8s。RKNN-Toolkit2 对 YOLOv8 的支持也比较完整，转换链路和 YOLOv5 基本一致。新手第一次跑通建议先把 YOLOv5s 吃透，后面换结构时一通百通。

5. 实操中遇到的坑与排查方法

最后这部分我把自己实际操作中踩过的坑集中记下来。环境搭建和模型转换这两个阶段零零散散的问题非常多，但这些坑解决一次，后面就能少走很多弯路。

5.1 PC 端 pip 安装失败的典型报错

最常遇到的就是在 conda 环境里执行pip install rknn_toolkit2-xxx.whl时报ERROR: No matching distribution found。这个报错十有八九是 Python 版本不匹配，比如当前环境是 Python 3.11，而 whl 包只支持 cp38。先执行python --version确认当前环境，不对就用conda activate rknn切回正确环境。

还有一个高频报错是安装 OpenCV 相关依赖时出现Building wheel for opencv-python ... error。这个通常是因为 pip 在尝试从源码编译，耗时很长还容易编译失败。建议直接先sudo apt install -y python3-opencv装系统版 OpenCV，或者指定版本安装预编译好 aarch64/x86 的 wheel。在 Ubuntu 20.04 + Python 3.8 下，用opencv-python==4.8.1.78这种稍老一点的版本最省心。

5.2 RKNN 转换阶段的问题排查

转换时如果报E RKNN: RKNN API error: some ops are not supported或者类似算子不支持的错误，先检查 ONNX 是从哪个版本的 YOLOv5 导出的。有些最新版 YOLOv5 的导出脚本会加入一些新算子，而 RKNN-Toolkit2 还没完全覆盖。解决方式是把 ONNX opset 降到 12 或 11，重新导出。

另一个常见错误是转换过程中内存爆掉，报Killed或者 OOM。RKNN 转换在生成量化表时需要加载大量中间数据，PC 内存低于 8GB 时会比较吃力。实在不行，可以减少 dataset.txt 的图片数量，比如从 200 张降到 50 张，能明显降低内存消耗，但量化精度会有一定妥协。

转换成功率最高的方式，是把量化和不量化的转换测试分开跑。先用do_quantization=False验证模型能转通，再开量化。两件事混在一堆里排查，会浪费很多时间。

5.3 板端推理结果不对怎么办

模型转换成功后，把 rknn 文件用 scp 传到板子上，用 RKNN Toolkit Lite2 加载运行。如果发现检测结果完全不对，第一反应应该是检查输入预处理是否和转换时一致。

比如你在转换时设置了mean_values=[[0,0,0]]、std_values=[[255,255,255]]，那板端推理前就要把图片像素除以 255，不能自己在代码里再减 0.485、除 0.229 之类的 ImageNet 归一化，那样结果必然错乱。

如果框的位置基本对，但类别全乱，那就需要检查类别数是否匹配。用官方 COCO 权重时类别数是 80，后处理里类别循环也要是 80。这个 bug 比较隐蔽，因为模型能推理、能画框，但框上的标签完全对不上。

还有一个我自己调试时用过的小技巧：先在 PC 上跑通同样的 rknn 模型（用 PC 版的 RKNN-Toolkit2，它也能推理），和板端结果比对。两边结果一致，说明模型没转错；结果不一致，那就是板端推理库或输入输出的环节出了问题。这个二分定位法能快速把问题缩小到具体环节。

5.4 常见问题速查表

以上这些坑，我每一行都实际遇到或见群里有人遇到过。其实大部分问题都是版本和参数不一致引起的，所以我在前面反复强调环境复刻的重要性。

最后分享一个我个人的习惯：每次搭完环境，我都会把用到的版本号记录下来，写成一个requirements.txt和一个部署脚本，方便下次重建。模型转换这条链路，参数多、依赖多、版本关系盘根错节，靠记忆力去维护迟早翻车。下一篇我会写板端推理部分，就是把 rknn 模型真正跑起来，处理输入输出，并做一次性能测试，看看 RK3588 跑 YOLOv5s 实际能达到多少帧。到时候我会连后处理代码、NPU 占用观察方法一起放出来，继续沿着这条路往下走。