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

开篇

上一篇我聊了 RK3588 上部署 YOLOv5s 的整体思路和硬件准备，这篇接着往下走，重点落在环境搭建与模型获取这两个环节，这也是整个部署链路里最容易被轻视、却又最容易卡住人的地方。为什么把这两件事放在一起讲？因为环境没搭好，后面的模型转换和上板推理寸步难行；模型获取的方式，则直接决定你接下来要处理的是.pt文件还是.rknn文件，两条路线的工作量差别很大。

这篇内容适合手里已经有一块 RK3588 板子、准备从零跑起来 YOLOv5s 目标检测、但对工具链还不算熟的开发者。我会把整个部署链路先铺开，再逐段讲清楚环境怎么搭、模型从哪儿拿、拿到之后怎么变成 RK3588 NPU 能跑的格式。实际踩过的坑、验证过的版本组合、还有那些文档里不会明说的问题，我都会写出来。

1. 先把系统喂给RK3588：Ubuntu镜像烧写与开局避坑

环境搭建的第一步，不是你急着去装 PyTorch 或者 RKNN-Toolkit，而是先把板子的操作系统搞定。RK3588 这块 SoC 可以跑的系统不少，常见的有 Debian、Ubuntu、Buildroot，还有各种板卡厂商自己魔改的发行版。但如果你要做 YOLOv5s 部署，我的建议很直接：用官方或半官方的 Ubuntu 20.04 或 22.04 镜像，不要折腾 Buildroot，也不要拿一个来路不明的精简 Linux 去试。

1.1 为什么首选 Ubuntu 镜像，而不是其他系统

RKNN-Toolkit2 这个工具链，官方支持和验证得最充分的就是 Ubuntu 系统，而且 x86 主机端和 ARM 板端都是如此。你在板子上跑推理时，虽然理论上只需要一个librknnrt.so运行库就能加载模型，不需要完整的 Python 工具链，但实际开发过程中，你免不了要在板子上调试脚本、查看日志、用 OpenCV 读摄像头、甚至临时跑一段 Python 来做图像预处理。这时候一个 Ubuntu 系统能省掉大量 "这个库装不上、那个依赖找不到" 的时间。

还有一点很重要：RK3588 的 NPU 驱动和运行库版本，跟固件版本是绑定的。系统太老可能驱动太旧，跑不了新版 RKNN-Toolkit2 生成的模型；系统太新又可能出现内核和官方工具链还没适配的情况。目前 RK3588 生态里，Ubuntu 20.04 和 22.04 是兼容性最稳的选择。我手里这块板子最终用的是 Ubuntu 22.04，原因很简单：20.04 上 OpenCV 的 apt 源版本偏低，摄像头读取和图像处理的体验不如 22.04 顺手。

1.2 RKDevTool 烧写流程与常见失败

烧写系统这步，不同板卡厂商工具不同，但 RK3588 平台基本都绕不开 RKDevTool 这个烧写工具，流程大致是：

1. 下载对应板卡厂商发布的 Ubuntu 固件压缩包，解压后一般包含update.img或若干分区镜像。
2. 安装瑞芯微的驱动DriverInstall.exe，把板子通过 USB 线接到电脑的 USB 口。
3. 让板子进入 Loader 模式。通常做法是按住板子上的 Recovery 键不放，再上电启动，部分板卡也支持在 adb 环境下执行adb reboot loader。
4. 打开 RKDevTool，确认识别到设备后，选择固件或用分区表逐个指定镜像，点击执行。

这看起来不算复杂，但几乎每个人第一次都会在这里卡一阵子。我遇到的第一个坑是驱动没装上：板子插上电脑后，设备管理器里显示的是一个带感叹号的未知设备，RKDevTool 始终显示 "没有发现设备"。折腾了半天，发现是把 USB 线插到了板子的调试串口旁边的普通 USB Host 口，而烧写必须用板子上的 OTG Type-C 口。这类接口位置文档里不一定画得很清楚，建议拿到板子先看丝印，一般 OTG 口旁边会有 "OTG" 或 "烧录" 标识。

另一个高频问题是烧写进度条卡住或者中途报错。我遇到过两次，一次是 USB 线质量太差，数据传输不稳定；一次是固件解压路径带了中文和空格，工具解析路径出错。换了根短一点的品牌线、把固件放到纯英文路径之后，问题就消失了。烧写完成后第一次开机通常比较慢，有的板子要等两三分钟，屏幕上可能先黑屏一段时间再出系统，不要急着断电，给它一点时间。

注意：烧写前先把板子上外接的 TF 卡、SSD、摄像头都拔掉，只保留烧写需要的 USB 线和电源。外设干扰导致 USB 枚举异常的情况，我遇到过不止一次。

1.3 开机后的系统初始化三件套

系统起来之后，别急着装 YOLO 相关的任何东西，先做三件基础设置：联网、更新软件源、调整交换空间。

联网这步没什么好说的，有线连上路由器或者配好 WiFi。Ubuntu 镜像一般默认就能收到 DHCP 地址，ping一下外网验证即可。

软件源这里我个人不推荐一上来就换成所谓的 "国内镜像源"，除非你确定镜像站同步的架构和版本与板子系统完全一致。RK3588 的 Ubuntu 固件有些是厂商基于官方移植的，源指向可能已经配好。直接apt update && apt upgrade看情况，如果慢再考虑调整。这里有个小细节：升级内核和固件包时要慎之又慎，特别是带有rk字样、和 NPU 驱动相关的包，升级完可能和原有驱动不匹配，导致后面 RKNN 初始化直接报错。我一般是先把系统升完，再处理 NPU 相关组件。

交换空间这块往往被忽略。RK3588 板载内存常见的是 8GB 或 16GB，看着不小，但后续编译工具、转模型、跑预处理时，内存占用会被推到很高。给系统加一个 2GB 到 4GB 的 swapfile 是比较稳的做法。

# 在板子上创建 4GB 交换文件 sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # 写入 fstab，开机自动挂载 echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

做完这三件事，板子系统这块就算立住了。接下来你要面对的是真正的开发环境搭建。

2. 开发环境分两端布置：PC端工具链与板端运行库

这里的 "环境"，不是单指板子上的环境，而是两套：PC 端负责模型转换和调试，板端负责最终推理。很多新手容易犯一个错误，觉得 RK3588 性能不弱，就在板子上装一套完整的 RKNN-Toolkit2，试图把所有工作都在板子上完成。这个思路理论上可行，但实操起来会非常难受。

2.1 为什么不能只依赖板子环境

RKNN-Toolkit2 的完整版工具链，安装依赖很庞杂，包括 PyTorch、ONNX、OpenCV、NumPy、SciPy 等一大堆库，而且对 Python 版本和系统库有严格限制。RK3588 板子虽然 CPU 不弱，但内存带宽、存储速度和散热都有限，在板子上跑模型转换和量化校准，一次构建可能要等很长时间。更关键的是，工具链官方主要是在 x86 主机上验证的，你在 ARM 板子上装完整版工具链，容易碰到某些依赖库没有 aarch64 版本或者编译失败的问题。

正确做法是：PC 端做重活，板端只做轻量推理。模型获取、pt 转 onnx、onnx 转 rknn，全部在 PC 的 x86 环境完成；板子只需要装一个轻量运行接口rknn-toolkit-lite2，或者干脆只依赖底层librknnrt.so运行库和 Python 推理 API 就能跑起来。

这样做还有一个附带好处：后续如果换一块 RK3566 或者 RK3576 的板子，PC 端的转换环境不用动，只需要针对新板重新初始化运行环境即可。模型文件在大部分情况下可以跨同系列 NPU 平台使用，只要工具链和运行库版本对齐。

2.2 PC端：Python虚拟环境与 RKNN-Toolkit2 安装

PC 端环境搭建，我按下面的顺序来操作：

首先装好 Python 3.8 到 3.10 之间的某个版本。太新的 Python 在部分 RKNN-Toolkit2 版本下会有兼容问题，太旧的又带不动新版 ONNX。我用的 Python 3.10，配合 RKNN-Toolkit2 2.x 版本，整体比较顺利。

然后创建虚拟环境，强烈建议用 venv 而不是直接 pip install 到系统环境。RKNN-Toolkit2 会拉入一堆特定版本的依赖，直接装进系统环境，很容易把系统里其他 Python 项目搞坏。

python3.10 -m venv rknn-env source rknn-env/bin/activate pip install --upgrade pip pip install rknn-toolkit2

这里有个容易踩的坑：如果直接pip install rknn-toolkit2，默认可能会装到比较新的版本，但新版本转换出的模型格式可能需要更新版本的 NPU 运行库。RK3588 固件自带的librknnrt.so如果版本偏旧，就会出现 "模型初始化失败，版本不匹配" 之类的报错。为了避免这个麻烦，我建议在装工具链之前先确认板子固件里 NPU 驱动的版本，再选择对应版本的 RKNN-Toolkit2 安装。瑞芯微的 GitHub 仓库 release 页面一般会注明兼容关系。

装完后，验证一下导入是否正常：

from rknn.api import RKNN print("RKNN toolkit ok")

如果导入时报缺少某个动态库，不要慌，看下报错是缺哪个，用 apt 补上即可。Ubuntu 22.04 下常见的缺库是libxslt1-dev、libgl1-mesa-glx这类基础库。

2.3 板端：rknn-toolkit-lite2 与运行库

板端这边，不需要完整工具链，只需要安装rknn-toolkit-lite2。它是同一套 Python 接口的轻量版，保留了load_rknn、inference、init_runtime这些推理相关的方法，去掉了模型构建和量化功能。

# 板子上执行 pip install rknn-toolkit-lite2

但要注意，pip 包默认是从 PyPI 安装，部分版本的 rknn-toolkit-lite2 在 PyPI 上不一定及时更新，甚至可能找不到。这个时候需要直接从瑞芯微官方 GitHub 仓库下载 wheel 文件手动安装。安装命令是：

pip install rknn_toolkit_lite2-xxx-cpXX-cpXX-linux_aarch64.whl

这个 wheel 包的文件名里包含了 Python 版本信息，你一定要选和板子系统 Python 版本匹配的那个。我一开始没注意，装了一个 cp39 的包，结果 Python 3.10 环境下直接报错说不支持，白白浪费了时间。

安装完成后，板端还需要确认 NPU 运行库存在。一般 Ubuntu 固件里已经预装了/usr/lib/librknnrt.so，你可以用下面的命令确认一下：

ls -la /usr/lib/librknnrt.so

如果找不到这个库，需要从固件或官方 SDK 里提取对应架构的运行库放进去。这个文件是整个 NPU 推理的底层核心，后面所有 RKNN 模型在板子上跑都得靠它。

提示：librknnrt.so的版本要和 PC 端 RKNN-Toolkit2 的版本对得上。版本不匹配时，常见表现是init_runtime阶段报错或模型加载失败。排查方法很粗暴但有效：先看板端库版本，再选 PC 端对应版本的工具链。

2.4 版本雷区清单：我踩过的那些坑

开发环境搭建过程中，我遇到过的比较典型的版本和依赖问题，整理成了一张表：

我看到很多人在这一步反复折腾，说白了都是版本不匹配问题。你只要记住一条原则：工具链、运行库、固件驱动三者尽可能来自同一套发布版本，并且保证 wheel 包和 Python 版本严格匹配，环境这块基本就稳了。

3. YOLOv5s模型从哪儿拿：权重选择与数据准备

环境搭好之后，接下来就是模型获取。这里的 "获取" 不只是yolov5s.pt这个文件本身，还包括源码、权重验证、以及后续如果要换成自己数据集时的数据准备。因为你在 RK3588 上部署的最终目标，大概率不是只跑官方模型的 demo，而是要能换成自己的业务场景。

3.1 官方预训练权重的获取与校验

YOLOv5 的源码托管在 GitHub 的ultralytics/yolov5仓库里，预训练权重则发布在仓库的 Release 页面。你需要下载的权重文件是yolov5s.pt，大约 14MB 左右。下载方式可以是在 Release 页面点链接手动下载，也可以用命令行工具直接拉取：

wget https://github.com/ultralytics/yolov5/releases/download/v6.1/yolov5s.pt

但这里有个关键点：部署到 RK3588 上的 YOLOv5s，不一定非要用最新版本的源码权重。RKNN-Toolkit2 自带的示例和社区大量实践，大多基于 YOLOv5 的 v6.0 或 v6.1 版本，因为这两个版本的结构相对稳定，转 RKNN 的兼容性也最好。你如果直接拿 v7.0 或更高版本的权重，转换时虽然通常也能通过，但某些算子的支持可能会有偏差，后处理逻辑也会有点不同。

建议的做法是：把整个yolov5仓库 clone 下来，然后 checkout 到 v6.1 的 tag，保持源码和权重版本一致，避免后面导出 onnx 时出现函数签名不匹配的奇怪问题。

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

下载完权重后，最好做一次完整性校验，防止下载文件损坏。官方 Release 页面一般会提供对应权重的 SHA256 值，用sha256sum yolov5s.pt核对。这一步看着多余，但在网络传输不稳定时真的有必要。我就遇到过权重文件少了几 MB，加载时 PyTorch 直接报 "unexpected end of file" 的错误。

3.2 如果你要换成自己的数据集，这一步必须提前做

官方权重只能帮你跑通 demo，实际项目里你大概率会使用自己的业务数据重新训练。这里我建议你在这一篇就把数据准备工作一起做了，因为后文模型转换阶段的量化校准，也需要一批真实场景图片，而不是随便拿 COCO 上的猫猫狗狗应付。

自己训练需要准备三样东西：

第一，标注数据。YOLO 格式的标注，每个图片对应一个同名前缀的.txt文件，里面每一行是class_id x_center y_center width height，坐标是相对图片宽高的归一化值。

第二，数据集目录结构。通常是images和labels两个大目录，下面再分train、val子目录，或者直接用train.txt、val.txt文本文件列出所有图片路径。

第三，一个描述数据集的 yaml 配置文件，它定义了类别数和类别名。类似这样：

train: ./datasets/mydata/train.txt val: ./datasets/mydata/val.txt nc: 2 names: ['person', 'car']

准备好之后，在已在本地跑通的 yolov5 源码里执行训练：

python train.py --data mydata.yaml --weights yolov5s.pt --img 640 --epochs 100 --batch-size 16

训练这块不在本文展开，但你可以先收到一批训练完的best.pt权重文件。后续模型转换的输入，既可以是我刚才下载的官方预训练权重，也可以是你自己训练出的best.pt，两者的操作流程完全一样，无非是不同pt文件进入同一个导出管线而已。

3.3 模型许可证与后续用途的注意事项

这点很多人不注意，但我觉得作为技术分享有必要提一嘴：YOLOv5 的源码和部分权重涉及 GPL 许可证，如果你的项目是内部工具或学习用途，基本没影响；但如果是商业产品，就要认真看是否符合开源协议要求。尤其是你要把模型集成进自己的产品并分发时，许可证合规问题不能忽视。

另一个注意点是通过官方仓库下载的预训练权重，类别是 COCO 80 类。如果你的业务场景跟这 80 类差异很大，官方权重对你的量化校准帮助也是有限的，更合适的做法是拿你自己训练集的一批图片来做后续量化校准。这直接关系到 RKNN 模型转换的质量。

4. 让模型换一种形态：pt转onnx再转rknn的全过程

模型文件拿到手，环境也都就位，接下来就是整个部署流程中最核心的一步：把 PyTorch 训练出来的权重，变成 RK3588 NPU 能直接吃的.rknn模型。这一步涉及两次格式转换：.pt转.onnx，再.onnx转.rknn。两次转换各有各的道道。

4.1 为什么中间要有个 onnx，而不是直接 pt 转 rknn

这个问题是我第一次接触 RKNN 工具链时最想不通的地方。理论上工具链可以直接解析 PyTorch 模型，RKNN-Toolkit2 也确实支持直接加载 PyTorch 模型，但实际效果和稳定性，远不如先导出 onnx 再接续转换。

原因很简单：PyTorch 模型是一个 Python 对象，里面包含大量训练相关的辅助逻辑和动态控制流，而部署推理只需要静态计算图。ONNX 恰恰是一种静态的、开放的中间表示格式，它不依赖 PyTorch 运行时，可以和 PyTorch 版本解耦。先导出 onnx，再让 RKNN-Toolkit2 去解析 onnx，等于把 "动态 Python 模型" 和 "嵌入式 NPU 工具链" 这两个不同世界的东西，用一个标准接口隔离开。

所以整个转换链路是：

1. 用 PyTorch 环境加载.pt权重。
2. 调 YOLOv5 官方export.py，把模型导出为.onnx文件。
3. 在 PC 端用 RKNN-Toolkit2 读取.onnx，配置量化方式，构建并导出.rknn文件。
4. 把.rknn文件拷贝到板子上，用rknn-toolkit-lite2加载执行。

4.2 用官方 export.py 导出 onnx

在 YOLOv5 源码目录里，官方提供了一份export.py脚本，导出 onnx 的命令很简单：

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

这里我用了--opset 12，这个细节值得展开说一下。ONNX 的 opset 版本决定了算子集合的兼容范围。RKNN-Toolkit2 对 opset 12 左右的 onnx 解析是最成熟的，opset 太高反而可能遇到某些新算子不支持。YOLOv5 默认导出时可能用较高 opset，建议显式指定为 12。

另一个参数是输入分辨率--img-size。默认是 640x640，这是 YOLOv5s 的标准输入尺寸，你的图片预处理也按 640x640 来对齐。如果为了更快推理想用 416，那训练和转换都要保持 416 对齐，不能混用。对 RK3588 来说，我建议先用 640 跑通整个流程，之后再根据速度需要优化到 416 或 320。

有一点要特别提醒：YOLOv5 的export.py默认会尝试在导出的 onnx 里包含 NMS 后处理算子，这在边缘部署场景下往往不是我们想要的。RKNN 工具链更适合自己写解码和后处理，一方面是因为 RKNN 对 NMS 相关算子的支持不完整，另一方面自己写解码更灵活。导出时需要绕过模型的 NMS 部分，最可靠的方式是给export.py加--no-nms之类的参数，或者直接改源码里导出逻辑。我实测比较稳妥的是先查一下当前版本有没有这个参数，没有就在export.py中设置model.model[-1].export = False。

导出成功后，你会得到一个yolov5s.onnx。可以用onnxsim做一次简化，去掉一些冗余算子，减少后续 RKNN 转换失败的几率。

pip install onnx-simplifier python -m onnxsim yolov5s.onnx yolov5s_sim.onnx

4.3 用量化校准生成 rknn 模型

接下来进入 RKNN-Toolkit2 的环节。先写一个转换脚本，我把它叫做convert_rknn.py：

import os from rknn.api import RKNN ONNX_MODEL = 'yolov5s_sim.onnx' RKNN_MODEL = 'yolov5s.rknn' DATASET = 'dataset.txt' # 量化校准图片路径列表 if __name__ == '__main__': rknn = RKNN(verbose=True) # 第 1 步：配置模型参数 rknn.config( mean_values=[[0, 0, 0]], std_values=[[255, 255, 255]], target_platform='rk3588', quantized_dtype=' asymmetric_quantized-8' ) # 第 2 步：加载 onnx 模型 ret = rknn.load_onnx(model=ONNX_MODEL) assert ret == 0, 'load onnx failed' # 第 3 步：构建模型 ret = rknn.build(do_quantization=True, dataset=DATASET) assert ret == 0, 'build rknn failed' # 第 4 步：导出 rknn 模型 ret = rknn.export_rknn(RKNN_MODEL) assert ret == 0, 'export rknn failed' rknn.release()

这里几个配置项都值得说清楚。

mean_values和std_values是图像预处理的归一化参数。YOLOv5 推理时默认输入图像需要除以 255，所以 mean 为 0、std 为 255。也就是说，如果你在板端推理脚本里不额外做归一化，而是让 RKNN 运行时直接做预处理，就需要在这里配置成[0,0,0] / [255,255,255]。如果配置错了，跑出来的检测结果会非常离谱，比如置信度极低、框的位置错得离谱。

quantized_dtype指定量化类型，通常用 8bit 量化，这是 RK3588 NPU 的核心算力来源。RK3588 的 NPU 是支持 INT8 计算的，6 TOPS 算力也是在 INT8 条件下标称的。做 INT8 量化后，模型体积大约缩减到原来的四分之一，推理速度也明显提升，代价是精度会有轻微下降，但 YOLOv5s 在目标检测任务上这个下降通常是可以接受的。

dataset.txt放的是量化校准图片的路径列表，每行一张图片路径。为什么要这个文件？因为 INT8 量化不是直接把浮点权重四舍五入，而是需要统计真实输入数据的数值分布，确定最佳量化范围。这个环节叫量化校准。校准图片选择的原则是：贴近真实业务场景、覆盖亮度多样性、数量一般在 100 到 300 张之间。

校准图片路径的写法要注意，脚本里给出的是相对路径，我这个dataset.txt文件放在和convert_rknn.py同一目录下，每行写相对路径即可。

4.4 我踩过的转换失败与修复

整个转换过程的报错率，在我所有项目里是比较高的。下面这些是我实际遇到过并解决掉的典型问题，列出来给你参考。

最常见的是支持问题，报错信息形如 "Unsupported operator: xxx"。这种情况要么是 onnx 的 opset 版本过高，要么是模型里混入了一些 RKNN 不认识的算子。处理方案有几个层次：先试降低 opset 到 12，再试 onnxsim 简化，如果还不行，换个 YOLOv5 的版本重新导出。我遇到过一次导出的 onnx 里带了GridSample算子，排查后发现是用了一个非官方魔改的模型结构，换回官方结构后问题消失。

第二个常见问题是load_onnx阶段报 shape 错误，最常见的是输入 shape 是动态的，比如[None, 3, 640, 640]。RKNN 工具链不喜欢动态 shape，你需要在导出 onnx 时固定 batch size 为 1，并且确保 shape 是静态的。命令里--img-size 640 640已经帮我们做了这件事，但如果导出后发现原始 onnx 里 batch 维度不是 1，可以用onnxsim的 shape 推断来处理。

第三个问题来自量化阶段，表现是 "load dataset failed" 或 "read image failed"。这个多半是dataset.txt里的路径不对，或者是图片中存在损坏文件。校准图片最好先统一用 OpenCV 读一遍，确保每张都能正确解码。我在某次使用从网络上爬下来的图片做校准数据时，就遇到过几张图片虽然扩展名是.jpg，实际却是损坏文件的尴尬情况。

第四个问题比较隐蔽，发生在模型导出成功、板端加载也成功，但推理结果全为空时。排除了预处理配置问题后，发现是模型里 YOLO 层的输出通道数和后处理脚本不匹配。如果你手改过检测头结构，后处理的解析也要跟着改，这是很多二开场景翻车的地方。建议先用官方 yolov5s 权重完成完整链路，再做结构改动。

5. 上板验证：在RK3588上跑通第一个检测推理

模型转换完毕，拿到yolov5s.rknn，环境也都配好了。这时候你大概已经有点按捺不住，想把模型拷到板子上跑一跑。这步是验证前面所有工作的关键，也是监测心得整理的最后一个环节。

5.1 从 rknn_model_zoo 借一个现成 demo

瑞芯微官方在 GitHub 上维护了一个模型仓库airockchip/rknn_model_zoo，里面针对 RK3588 提供了 YOLOv5 的完整示例，包括 Python 和 C 版本的推理代码。我的建议是先把官方 demo 跑通，再改造成自己的代码。这样至少可以把“模型文件是否正常”“NPU 环境是否正常”这两个变量从业务代码里剥离开。

git clone https://github.com/airockchip/rknn_model_zoo.git

demo 的目录结构里，yolov5子目录下会有模型转换脚本和推理脚本。你把转换好的.rknn放进去，按 README 说明的路径配置好，运行推理脚本。如果官方 demo 能正常画框识别，说明你前面搭建的环境和转换出的模型都通过了验收。

这里有个很容易忽略的点：rknn_model_zoo里的 demo 代码和 YOLOv5 源码版本是有对应关系的。你用 v6.1 的权重配官方最新 demo，理论上没问题，但如果 demo 是面向特定 YOLOv5 分支魔改的代码，就可能出现输出的 anchor 解析不对、框偏了等情况。尽量选择和你的 YOLOv5 版本匹配的 demo 分支或 commit。

5.2 手写一个最小推理脚本

跑通 demo 之后，我建议自己动手写一个最精简的推理脚本，摆脱官方 demo 里一堆配置项的束缚，这样你能清清楚楚地知道每一步在干什么。一个最简单但完整的流程大概是这样：

import cv2 import numpy as np from rknn.api import RKNN rknn = RKNN() rknn.load_rknn('yolov5s.rknn') rknn.init_runtime(target='rk3588') img = cv2.imread('test.jpg') img_resized = cv2.resize(img, (640, 640)) # RGB 格式、HWC => CHW、数据对齐 img_input = cv2.cvtColor(img_resized, cv2.COLOR_BGR2RGB) img_input = np.expand_dims(img_input, axis=0) outputs = rknn.inference(inputs=[img_input])

inference返回的是模型的原始输出，YOLOv5s 有三个检测头，输出的是三个尺度的特征图。你后续需要自己实现 anchor 解码、置信度筛选、NMS 这些后处理逻辑。这里有个优化点：如果你的预处理配置里已经设置了 mean/std，在板端就不需要对图像再做归一化，直接喂原始像素值即可；如果你没在 rknn 配置里设置，就必须在推理前手动归一化，否则出来的结果就是乱的。

如果你希望推理流程完整一点，可以参考官方 demo 里的 postprocess 逻辑，但完全有必要手写一遍。只有当你亲手把 anchor、stride、conf threshold、iou threshold 这些参数理清楚之后，才算真正懂了 YOLOv5 在 NPU 上的部署，而不是只会调别人写好的函数。

5.3 速度参考与下一步规划

RK3588 的 NPU 跑 YOLOv5s INT8 量化模型，输入 640x640 分辨率，常见的推理耗时大约在 30ms 到 60ms 这个区间，换算成帧率就是 16 到 30 FPS 左右。实际速度取决于你的 NPU 核心配置、CPU 负载、图像采集方式等。如果你只是单纯走 CPU 推理，那速度会慢很多，这也是为什么我们一定要把模型转换成 rknn 格式交给 NPU 跑的原因。

木已成舟，环境搭建和模型获取这两个环节到这里就走完了。后续文章我大概率会聊一聊板端摄像头实时推理的优化、多线程流水线怎么设计、以及 C 接口部署这些更进阶的内容。不管怎样，先把这篇里的每一步真正跑通，确认模型检测效果和耗时都符合预期，再往下走不迟。

最后分享一个小习惯：我每次完成一次完整的 RKNN 部署，都会把 PC 端的转换脚本、量化校准图片列表、模型文件版本和板端运行库版本记录在同一个 README 里。这个习惯帮我省过很多次重新排查环境的痛苦。特别是当你隔了几周再回头维护项目时，一份版本对照表比任何代码注释都有用。