1. 整机规划与方案选型把 YOLOv5s 跑在 RK3588 上看起来就是“烧个系统、装个环境、放个模型”三步走实际走到一半你就会发现真正卡人的往往不是模型本身而是环境链条上的各种隐性依赖。这篇是系列第二篇重点是环境搭建和模型获取。在动手之前先把整机方案理清楚能省掉后面一大半的返工。先说我的目标场景RK3588 开发板8GB 内存版本要跑 YOLOv5s 做实时目标检测帧率目标是 30FPS 以上最终打算用 NPU 加速推理。因为板子要长期跑推理任务系统层我选了 Ubuntu 20.04 桌面版而非 Buildroot 或 Debian 精简系统。原因很简单桌面版自带完整的 GPU 驱动、USB 相机驱动和网络管理工具调试视觉应用时少踩很多坑。RK3588 的 NPU 算力有 6 TOPSINT8 推理 YOLOv5s 大概能跑到 60-90ms 一帧换成 OpenCL 走 GPU 反而更慢所以主力推理必须走 NPU环境搭建也围绕 RKNN 工具链展开。整体方案分为三条线并行开发板上的运行环境、主机上的交叉开发环境、以及模型转换链路。开发板环境负责最终推理主机环境负责训练或转换模型两者之间的衔接就是 RKNN-Toolkit2。很多新手只盯着板子上的环境忽略了主机侧的 RKNN 工具链结果模型文件拿到手之后才发现转不了又回头折腾浪费时间。热词里有人提到“rk3588 刚烧写的 ubuntu20.04 磁盘就没空间了”这个问题我在第一次烧写时也遇到过根因是官方镜像默认只给 root 分区分配了很小的容量而 eMMC 或 SD 卡剩余空间处于未分配状态。后面我会单独讲怎么扩分区这也是系统装完第一件要做的事。2. 开发板端系统环境搭建2.1 烧写 Ubuntu 20.04 系统镜像RK3588 的烧写方式取决于你的板子型号。我用的是基于 RK3588 公版设计的核心板加底板方案eMMC 存储官方提供 Loader 和 Ubuntu 镜像两大类文件。烧写工具用的是 RKDevToolWindows 下操作最方便Linux 下也有升级工具但不如 Windows 版直观。烧写前需要准备好这几样东西RKDevTool 烧写工具版本建议 3.15 以上旧版对 RK3588 支持不完整。官方 Ubuntu 20.04 镜像包包含update.img或Ubuntu-20.04-xxx.img文件。USB Type-C 数据线用于连接板子的 OTG 烧写口。电源适配器RK3588 满载功耗不低至少 12V/2A 起步供电不足会导致烧写中断。操作流程分三步先安装 RKDevTool 并加载驱动驱动安装成功后在设备管理器里能看到Rockusb Device设备然后拔掉板子电源按住 Recovery 按键不放插入 USB 线再到电脑最后上电此时 RKDevTool 会识别到 MASKROM 或 Loader 设备最后在 RKDevTool 的“升级固件”页签里选择镜像文件点击“升级”即可。烧写完成后第一次开机比较慢大概 2-3 分钟因为系统要完成分区初始化、首次启动配置。此时建议接 HDMI 显示器观察启动过程如果只接串口你只能看到内核日志看不到桌面是否起来。这里有个关键细节如果板子上已经有 Android 系统直接烧 Ubuntu 之前建议先执行“擦除所有 flash”操作否则旧系统的分区表可能干扰新镜像的分区布局导致 boot 分区无法正确挂载。擦除操作在 RKDevTool 的“高级功能”页签里点击“擦除 eMMC”等它跑完再烧新系统。2.2 系统初始化与磁盘扩容系统起来之后第一件事不是装 Python而是先看磁盘空间。RK3588 的官方 Ubuntu 镜像里rootfs 分区只分配了 8GB 左右剩余 eMMC 空间全部未使用。跑个 YOLOv5s 本身占不了多少空间但装完 RKNN 工具链、Python 依赖和模型文件之后8GB 很快就会捉襟见肘。先看当前分区情况df -h lsblk我的 eMMC 是 64GBlsblk显示mmcblk0p7rootfs只有 8GB后面还有大量空闲空间。官方推荐的扩容方式是使用resize2fs但前提是 rootfs 分区已经被扩展。不同版本的官方镜像做法不同有些镜像启动脚本会自动扩容有些不会。稳妥起见手动操作sudo parted /dev/mmcblk0在 parted 交互模式里先print查看分区表找到 rootfs 分区的编号然后resizepart指定新大小。注意parted操作分区表有风险操作前确认你改的是正确的磁盘设备别把 boot 分区搞坏了。扩展完分区之后再执行sudo resize2fs /dev/mmcblk0p7resize2fs会扫描文件系统并扩展到分区最大值整个过程大概几十秒到几分钟取决于 eMMC 容量和当前数据量。执行完再df -h确认空间已扩大。没把握的也可以直接用脚本方式自动扩容有些第三方工具提供了resize-helper脚本但我更推荐手动parted resize2fs因为你能清楚看到每一步在干什么出问题时也知道从哪里下手。2.3 换源、SSH 与基础工具链系统初始化完接下来是换软件源和安装基础工具。国内访问 Ubuntu 官方源很慢尤其装 Python 依赖时每个包都要等半天。换源操作sudo sed -i s/archive.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo sed -i s/security.ubuntu.com/mirrors.aliyun.com/g /etc/apt/sources.list sudo apt update换成阿里云源之后网络速度会快很多。然后安装基础工具链sudo apt install -y python3-pip python3-dev git cmake curl \ libopencv-dev libhdf5-dev libjpeg-dev libpng-dev \ htop iotop tree sshfs这里有个小坑Ubuntu 20.04 自带的 Python 是 3.8但 RK3588 的 NPU 工具链对 Python 版本要求比较严格RKNN-Toolkit2 官方支持 Python 3.8-3.103.8 刚刚够用。不要手贱升级系统默认的 Python否则系统组件会连环报错。SSH 服务在桌面版镜像里默认是开启的但有些第三方精简镜像会关闭。确认一下sudo systemctl status ssh sudo systemctl enable ssh我习惯用 SSH 连接板子开发而不是直接在板子上接键盘鼠标一方面是因为 HDMI 桌面在跑推理任务时会抢占 GPU 资源另一方面 SSH 调试更灵活。如果你的板子连不上 SSH检查一下网络配置确保板子和主机在同一个网段。3. 主机端 RKNN 工具链准备3.1 为什么必须在主机上跑 RKNN-Toolkit2很多人以为在板子上直接装 RKNN-Toolkit2 就能完成模型转换这是个常见的误解。RKNN-Toolkit2 的作用不是板端推理而是模型转换、量化、仿真和性能评估它需要在 x86 主机环境下运行。板端实际跑推理用的是rknn-toolkit-lite2或 RKNN Runtime这是两个不同的软件包。官方的工具链逻辑是这样的在主机上用 RKNN-Toolkit2 把 PyTorch/ONNX/TensorFlow 模型转换成 RKNN 格式转换过程中可以加入量化、算子优化等操作然后生成.rknn文件再把这个文件拷贝到开发板上用 Runtime API 加载推理。如果直接在板子上做转换一是板子性能不足以快速完成量化校准二是部分转换工具依赖的 x86 库在 ARM 上不支持。所以我建议的主机环境方案是准备一台 x86 Linux 机器或者 Windows WSL2Ubuntu 20.04安装 RKNN-Toolkit2单独作为模型转换和仿真平台。我个人用的是 WSL2因为主力电脑是 Windows不想装双系统或虚拟机WSL2 跑 RKNN-Toolkit2 完全没问题只要你配置好网络和 USB 透传后面仿真器不需要 USB直接连板子走网口。3.2 WSL 环境下的 RKNN-Toolkit2 安装如果你也用 WSL2先把 WSL 升级到最新版然后安装 Ubuntu 20.04wsl --install -d Ubuntu-20.04进入 WSL 后创建一个虚拟环境强烈建议用 venv 而不是直接用系统 Python因为 RKNN-Toolkit2 的依赖版本比较敏感装乱了很难恢复python3 -m venv ~/rknn-env source ~/rknn-env/bin/activate pip install --upgrade pip从 RK3588 的 SDK 的external/rknn-toolkit2/packages目录找到对应 Python 版本的 wheel 包或者从官方发布的rknn-toolkit2安装包中安装。安装命令很简单pip install rknn_toolkit2-*.whl安装过程会自动拉取 numpy、opencv-python、onnx、torch 等一堆依赖。这里有个非常容易踩的坑RKNN-Toolkit2 要求 numpy 版本通常低于 2.0但最新版 pip 默认会装 numpy 2.x导致导入时报_ARRAY_API not found之类的错误。我踩过之后现在固定装 numpy 1.24.4pip install numpy1.24.4同样的问题也出现在 OpenCV 上RKNN-Toolkit2 用的是opencv-python-headless而不是完整版 opencv避免桌面环境冲突。安装完成后验证一下python -c from rknn.api import RKNN; print(import ok)出现import ok说明基本环境没有问题了。如果报libopenblas.so.0找不到之类的库缺失执行sudo apt install -y libopenblas-dev libatlas-base-dev3.3 主机与板子的连接方式RKNN-Toolkit2 除了做离线模型转换还支持连接开发板进行板端推理和性能评估。连接方式有两种一种是通过 USB 连接另一种是通过以太网。USB 连接需要配置 adb 或者 rknn 的 USB 透传我用下来觉得以太网连接更稳定尤其是在跑量化评估时数据量较大USB 偶尔会断。以太网连接的配置方式是板子和主机连接到同一个路由器或交换机板子 IP 固定比如192.168.1.100主机侧通过 RKNN-Toolkit2 初始化时指定目标平台rknn RKNN(verboseTrue) ret rknn.init_runtime(targetrk3588, device_id192.168.1.100)这里注意target参数要填rk3588旧版本可能用rk3588或rk3588s不同版本工具链略有差异。如果连接成功工具会输出 Runtime 版本信息和 NPU 驱动版本你可以在主机端直接调用板子推理非常方便。4. 模型获取与 YOLOv5s 导出4.1 权重获取途径与选择逻辑YOLOv5s 的权重获取主要有三种途径官方仓库下载、自行训练、第三方预训练模型。官方仓库的yolov5s.pt是在 COCO 数据集上预训练的80 个类别输入分辨率默认 640x640模型大小约 14MB参数量 7.2M。对于大多数做目标检测验证的场景直接用官方权重就可以跑通全流程后续再替换成自己训练的模型。获取官方权重的方式git clone https://github.com/ultralytics/yolov5 cd yolov5 pip install -r requirements.txt然后下载预训练权重wget https://github.com/ultralytics/yolov5/releases/download/v6.0/yolov5s.pt或者从国内的镜像站下载速度更快这里不展开。下载完用 PyTorch 加载验证一下权重是否完整import torch model torch.load(yolov5s.pt, map_locationcpu) print(model.keys())注意 PyTorch 2.0 以上加载旧权重时torch.load默认启用了weights_only模式可能报错需要加weights_onlyFalse参数。这就是“模型获取”环节最容易卡住的地方很多人下载完权重一加载就报错不是权重坏了是 PyTorch 版本行为变化了。4.2 修改模型结构以适配 RKNN 转换直接拿官方的yolov5s.pt转 RKNN 是行不通的必须先把模型的输出层从 Detect 改成非结构化的三个输出张量。原因在于 RKNN 工具链对自定义算子支持有限YOLOv5 原生的 Detect 层包含了 anchor 生成、NMS 等逻辑这些在 NPU 上不是不能做但效率低且兼容性差。常规做法是把 Detect 层剥离只保留 backbone neck 的卷积部分输出三个尺度的特征图NMS 放到板端后处理里用 CPU 做。修改方式很简单在 YOLOv5 源码的models/yolo.py中找到Detect类的forward方法将其替换为一个只输出三个特征图的函数。这也是热词里“yolov5s模型轻量化”提到的一个方向剥离 Detect 层不仅是为了转 RKNN本身也能减少参数量和计算量。实际操作中我写了一个简单的导出脚本加载原始权重后把模型改成model.model[:-1]这样输出的就是 backboneneck 的特征图列表。但需要注意不同版本的 YOLOv5 结构变化很大v5.0 到 v6.0 的 neck 部分就改过所以导出前一定要明确你用的是哪个版本。4.3 导出 ONNX 的完整参数与验证导出 ONNX 是模型转换链路中最重要的一环RKNN-Toolkit2 对 ONNX 的支持成熟度远高于直接加载 PyTorch 模型所以业界通行做法都是pt - onnx - rknn。ONNX 导出使用 YOLOv5 自带的export.pypython export.py --weights yolov5s.pt --include onnx --opset 12 --simplify --dynamic False关键参数逐一说明--opset 12RKNN-Toolkit2 支持的 ONNX opset 范围通常在 11-15 之间opset 12 兼容性和算子覆盖都很好太高反而可能出现新算子不支持的问题。--simplify用 onnx-simplifier 清理掉冗余的 Identity 节点、Reshape 节点减小模型体积还能避免某些转换器对无效节点报错。--dynamic False固定输入尺寸RKNN 转换时输入尺寸必须是固定的动态尺寸在 NPU 上没有意义。--grid --end2end不要加这两个参数。加了之后 ONNX 里会包含 NMS 算子直接转 RKNN 极大概率算子不支持。导出完成之后用onnx.checker验证模型完整性import onnx model onnx.load(yolov5s.onnx) onnx.checker.check_model(model) print(onnx.helper.printable_graph(model))check_model通过并不代表一定没问题但它能发现结构层面的错误比如节点输入输出不匹配、缺少 initializer 等。更严格的验证是用 onnxruntime 在主机上跑一遍随机输入对比 PyTorch 模型的输出差异。两张图片、三个尺度的输出结果误差在 1e-3 量级说明导出没问题。4.4 模型轻量化与备用方案热词里出现了“yolov5s模型轻量化”这里多说一嘴。如果你的目标是在 RK3588 上达到更高帧率轻量化模型有几个方向一是用yolov5s基础上减少通道数比如把 width multiple 从 0.5 降到 0.25但这需要重新训练二是用结构重参数化模型比如 YOLOv5 的v6.0里支持--hyp调整训练超参模型推理速度会有变化三是转换时使用 INT8 量化这是最直接的提速手段RK3588 NPU 对 INT8 的支持最好模型体积还能缩小到原来的四分之一。我在部署 YOLOv5s 时最终采用的是 FP16 INT8 两套模型方案先用 FP16 跑通全流程验证功能再切到 INT8 优化性能。FP16 模型转 RKNN 快速简单但帧率提升有限INT8 模型需要准备校准集量化后精度会有一点下降但推理速度几乎翻倍。这一块我会在后续转换实践篇里细讲。5. 常见问题与排查技巧实录我把实操过程中遇到最典型的问题整理成了一张速查表这些问题在官方文档里不一定能找到直接答案但基本是每个 RK3588 YOLOv5s 部署者都会遇到的。问题现象可能原因解决方案烧写后空间不足分区未自动扩容parted扩展 rootfs 分区 resize2fsRKNN-Toolkit2 导入报 numpy 错误numpy 版本过高pip install numpy1.24.4ONNX 转 RKNN 报算子不支持Detect 层未移除或 opset 过高剥离 Detect 层opset 用 12配合 onnx-simplify板端推理速度慢使用了 FP16 或 GPU 推理切换 INT8 量化确认走 NPU板子连接工具链失败网络不通或 target 参数错误检查 IP 固定确认targetrk3588SSH 连不上板子ssh 服务未启动或网络配置错误systemctl enable ssh检查网段除了表格里的问题还有一个很容易忽视的坑Python 虚拟环境里 pip 装包时如果系统里存在多个 Python 版本pip可能指向了错误解释器。推荐使用python -m pip install而不是裸输入pip install前者能确保装进当前虚拟环境。还有一次我转换 RKNN 时卡在Loading in memory...阶段很久不动最后发现是主机内存不够。RK3588 的模型转换和量化过程需要加载整个模型到内存YOLOv5s 虽然只有 14MB 权重文件但 ONNX 图结构和量化校准时的中间数据可能要占好几 GB 内存建议主机内存至少 16GB否则直接卡死。我一开始用一台 8GB 内存的老笔记本跑转换连续两次 OOM换到主力机32GB之后就一次通过了。另一个容易被忽略的问题是板端和主机端工具链版本不一致。RKNN-Toolkit2 主机端的版本必须和板端 Runtime 版本匹配版本差太大会出现明明转换成功但板端加载报错的情况。检查版本的命令python -c from rknn.api import RKNN; print(RKNN.__version__)板端则运行pip show rknn-toolkit-lite2确认两个版本号一致不一致就统一升级到同一版本。我的做法是先从板子 SDK 的rknn-toolkit-lite2包版本反推主机端 RKNN-Toolkit2 的版本保证切换时不会因为版本差异浪费时间。关于模型获取还有一点经验如果你的场景需要检测特定目标类别比如工业零件、动物、车辆千万不要直接用官网预训练权重因为后面转 RKNN 再调训练的周期很长。建议先准备 100-200 张目标图片用 YOLOv5s 做迁移学习微调再导出转换这样做出来的效果远好于直接部署通用模型。这个环节虽然不在“环境搭建”范围内但对后续模型效果影响很大提前规划总比推倒重来好。6. 从环境到模型获取的完整流程总结整个环境搭建和模型获取环节我实际跑通的完整流程大致如下准备 RK3588 开发板、电源、USB 烧写线、HDMI 显示器。下载官方 Ubuntu 20.04 镜像和 RKDevTool烧写系统。首次启动后立即扩容 rootfs 分区确认空间充足。换国内源安装基础依赖固定 IP开启 SSH。在宿主机Windows WSL2创建 Python 虚拟环境安装 RKNN-Toolkit2。验证工具链导入成功与板子通过以太网建立连接。clone YOLOv5 仓库下载预训练权重或自己的微调权重。修改模型结构导出固定尺寸、无 NMS 的 ONNX 模型。用 onnxruntime 对比 PyTorch 输出确认导出无误。把 ONNX 模型拷贝到主机环境准备下一步 RKNN 转换。这一套流程看起来步骤不少但每一步都是后面转换、部署的基石。我最想强调的是不要跳过 ONNX 导出后的验证步骤很多算子对齐问题在 PyTorch 里看不出来只有用 onnxruntime 对比输出才暴露得出来。虽然 RKNN 转换工具本身会报很多算子错误但等到那一层再排查定位成本高得多。还有一个小技巧值得分享在主机上保存一份模型转换的 Python 脚本模板每次更新模型只需要改路径和量化参数不用重新写代码。我的模板里固定了rknn.config、rknn.load_onnx、rknn.build三段逻辑后续换模型几乎零成本。环境搭建到模型获取这是整个 RK3588 部署链路里面最不性感但最影响后续进度的部分。下一篇我会写 RKNN 转换的详细过程和踩坑记录包括 FP16 和 INT8 的对比、量化校准数据集的选择以及板端 C/Python API 的调用方式。