拿到RK3568开发板之后最容易被劝退的一步在我看来是PC端模型转换工具。很多人把板子烧好系统、接上屏幕、跑个demo都挺顺利一到“我要部署自己的模型”就卡住了模型用什么格式转换工具装在哪为什么教程里一会儿说PC、一会儿说板子还有那个rknn文件到底是个什么东西这篇文章是《RK3568 边缘 AI 从零上手》系列的第三篇核心解决三件事搞懂边缘AI部署的“三层分工”在PC上把RKNN-Toolkit2转换工具装起来以及把整个流程浓缩成15条命令跑通一个最小闭环。适合已经能开机、能连板子、准备把手里的检测模型或分类模型跑到NPU上的同学。看完之后你至少能清楚哪一层在PC上做哪一层在板子上做NPU又负责哪一块模型转换失败时先去查哪里。1. 边缘AI部署整体思路先把“三层分工”装进脑子RK3568这块SoC最值钱的地方不是CPU而是自带的NPU。0.8TOPS算力虽然跟服务器显卡没法比但做轻量级检测、分类、语音唤醒这类场景完全够用。问题在于这个NPU不是随便一个模型就能跑的它只认瑞芯微定义的RKNN格式。所以边缘AI开发天然就会被拆成三个不同的层次对应三种不同的工作环境。1.1 三层分工中的“谁负责什么”第一层是模型训练层发生在你的PC上。你用PyTorch、TensorFlow、PaddlePaddle这些框架训练出一个模型然后导出成ONNX或TFLite。这一层跟RK3568没有任何关系你做训练的时候完全不需要考虑NPU怎么执行只需要保证导出的模型结构正确、输入尺寸清楚。第二层是模型转换层同样发生在PC上但用的是瑞芯微的专用工具RKNN-Toolkit2。它会把ONNX或TFLite模型读进来解析计算图把不支持的算子做替换或优化然后做权值量化、激活值校准最后生成一个以.rknn后缀的模型文件。这一层是最容易出问题的地方因为训练框架的算子和NPU支持的算子不是一一对上的。你在PC上能跑通的模型到了转换工具这里可能报各种不支持的算子。第三层是模型运行层发生在RK3568板子上。板子上的RKNPU Runtime和驱动负责加载.rknn模型把前处理好的图片数据喂给NPUNPU完成卷积和矩阵计算后再把结果返回给CPU。CPU在这里承担的角色更像“调度员”读摄像头、缩放图片、做NMS后处理、把结果画框或通过串口上报真正的重计算都在NPU。理解这三层分工之后很多新手困惑就迎刃而解了。比如你问“为什么不能在板子上直接跑PyTorch模型”因为板端根本没有Torch运行时而且就算硬塞一个Torch进去模型计算走的是CPU效率极低NPU完全闲着。再比如“为什么转换工具必须安装在PC上”因为转换过程需要复杂的内存规划和指令调度这一步由PC端工具链在模型编译期间完成而不是板子运行期间完成。1.2 RKNN工具链的四个组件别把“全家桶”搞混跟RKNN相关的名词非常多我第一次接触时也被绕晕了。RKNN-Toolkit2、RKNN-Toolkit-Lite2、RKNN Runtime、RKNPU驱动这几个东西名字像一家人但实际职责完全不同。我整理了一个对比表建议收藏组件名称运行位置主要用途使用时机RKNN-Toolkit2PC端模型转换、量化、模拟器推理、性能评估开发前期在PC上完成RKNN-Toolkit-Lite2板端Python接口加载.rknn模型做推理板端Python脚本开发RKNN Runtime板端C/C接口(librknnmrt.so)底层推理引擎板端C/C应用集成RKNPU驱动板端内核对接NPU硬件提供计算能力系统启动后由内核自动加载经常有人问我RKNN-Toolkit2能不能安装在板子上理论上Python库能装但意义不大。因为PC端工具链包含完整的编译器前端资源开销大板子跑起来吃力而且真正的目标模型转换应该在PC上完成后把.rknn文件直接拷贝到板子。板子只需要安装RKNN-Toolkit-Lite2它的解析器会调用RKNN Runtime去加载模型。要是做量产级的C应用连Lite2都可以不装直接调Runtime的API就行。这套分工还有个好处模型转换和模型运行彻底解耦。PC上有8核16线程、48G内存编译模型只要几十秒板子上内存只有1G到4G你不可能让板子去承担编译任务。把鸡蛋放对篮子整个流程才跑得顺。2. PC端安装转换工具15条命令分组速查环境规划先说结论推荐用Ubuntu 20.04或22.04的64位系统Python用3.8或3.10建议创建独立的虚拟环境。RKNN-Toolkit2依赖的numpy版本和很多AI框架冲突要是直接装到系统Python里很可能会把TensorFlow或者PyTorch环境搞坏。我自己的习惯是无论在哪台机器上都先用venv隔离再装工具链。下面这15条命令是我在干净Ubuntu上从零搭建环境的完整过程分成三批。第一批是基础环境第二批装转换工具第三批跑通演示案例并部署到板子。# ---------- 第1批基础环境 ---------- 1 sudo apt update sudo apt install -y python3 python3-dev python3-pip python3-venv git unzip 2 python3 -m venv ~/rknn_env source ~/rknn_env/bin/activate 3 git clone https://github.com/airockchip/rknn-toolkit2.git 4 cd rknn-toolkit2/rknn-toolkit2/packages 5 pip install --upgrade pip # ---------- 第2批安装转换工具 ---------- 6 wget https://github.com/airockchip/rknn-toolkit2/releases/download/v1.6.0/rknn_toolkit2-1.6.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 7 pip install rknn_toolkit2-1.6.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl 8 pip install -r requirements_cp38-1.6.0.txt 9 python -c from rknn.api import RKNN; print(toolkit OK) # ---------- 第3批跑通演示案例并部署到板子 ---------- 10 cd ../examples/onnx/yolov5 11 python test.py 12 adb devices 13 adb push yolov5s_relu.rknn /userdata/ 14 adb push yolov5.py /userdata/ 15 adb shell cd /userdata python yolov5.py注意第6条命令里的wheel文件名实际下载时要看你安装的Python版本cp38对应Python3.8cp310对应Python3.10。GitHub Releases页面会把所有Python版本对应的wheel打包在一起挑一个和你Python版本匹配的下载就行。如果你的Python是3.10文件名就变成rknn_toolkit2-1.6.0-cp310-cp310-...。2.1 第1批命令把Python环境收拾干净第1到5条命令干的事情就是准备一个干净的“工作台”。为什么第一步是apt update和安装基础工具因为wget、git、unzip这些在最小化Ubuntu上不一定默认存在特别是python3-venv如果不装后面python3 -m venv会直接报错ensurepip is not available。我第一次在服务器上踩过这个坑卡了半小时才反应过来。第2条命令创建了虚拟环境并激活。~/rknn_env是虚拟环境的安装目录你可以改成任意路径。激活后命令行前面会出现(rknn_env)后面所有pip安装的包都会装进这个环境不会污染系统Python。关闭环境用deactivate下次使用再执行source ~/rknn_env/bin/activate。第3条命令把RKNN-Toolkit2官方仓库clone下来。为什么要clone仓库而不直接下载单个wheel文件因为仓库里有完整的examples目录、量化数据集、测试脚本和各种Python版本的依赖清单后面第10条命令的yolov5示例也要从这里用。如果你网络访问GitHub比较慢可以找一下国内镜像仓库把URL替换成镜像地址即可。第4条命令进入packages目录所有wheel文件和requirements文件都在这里。cd之后建议立刻用ls看一下文件名确认你下载的wheel是否和当前目录里的版本号对应。2.2 第2批命令安装RKNN-Toolkit2主程序第6到9条命令是安装工具链的核心。第6条用wget下载wheel到当前目录这里版本号1.6.0是我在2024年常用的版本不是唯一选择。如果你下载的版本更新后面第7、8条命令里对应的版本号也要改。第7条是真正的pip安装。这里有个细节wheel文件名里带有manylinux_2_17_x86_64表示这是一个Linux x86_64平台的预编译包包含所有底层依赖安装时不需要额外编译直接就是可执行状态。如果文件名里是aarch64那是给ARM平台用的这种包在PC上装不了。有人会把PC和板子的包下反一执行pip install就报“not a supported wheel on this platform”。第8条命令安装依赖文件。requirements_cp38-1.6.0.txt里锁定了numpy、opencv-python、onnx等依赖版本。这里特别提醒第7条已经装了一个wheel为什么还要再装requirements因为wheel只带RKNN本身的代码转换模型时还需要读ONNX、做图像预处理、处理numpy数组这些依赖没有全部打进wheel里需要单独安装。如果你看到numpy版本冲突不要手动改requirements里的版本先删掉现有的numpy让pip按照requirements重装。第9条命令是验证安装是否成功。如果环境正常会打印toolkit OK并且没有抛异常。这一步是整个安装流程的安全网没跑通之前不要往下走。2.3 第3批命令跑通演示用例验证工具链第10条命令进入yolov5示例目录。仓库里包含了下载好的或通过脚本下载的yolov5s.onnx模型、测试图片、转换脚本test.py和后处理脚本。如果你是从国内镜像clone的模型文件可能不完整需要先检查目录下有没有yolov5s.onnx没有就手动下载一个或者用脚本转换一个。第11条命令python test.py是整个流程的“试金石”。它会执行完整的转换流程加载ONNX、解析图结构、做量化、生成yolov5s_relu.rknn然后在PC端的模拟器上跑推理输出目标检测结果。看到test.py跑出几个目标框说明你的PC转换工具已经能正常工作了。这个脚本最终会在当前目录生成一个.rknn文件这就是我们要部署到板子的东西。第12到15条命令是板端部署部分。adb devices检查开发板是否连接成功第13、14条把模型文件和Python脚本推到板子的/userdata目录第15条直接远程在板子上执行推理脚本。执行第15条之前板端需要已经安装好RKNN-Toolkit-Lite2且yolov5.py脚本里的推理代码可以独立运行。如果你板子还没准备好可以先只跑到第11条等板端环境配好后再补这部分。3. 核心细节解析模型转换的关键环节很多教程只告诉你“运行test.py就行”但一旦报错或者转换出来的模型精度不对你立刻会不知道从哪里排查。所以这一段我想把模型转换的底层逻辑讲透。3.1 转换流程到底发生了什么当你调用load_onnx、build、export_rknn这三个API时工具链内部做了四件大事。第一步是解析计算图。工具链把ONNX的Conv、Relu、Concat等算子逐个读出来构建成一张中间表示图。如果遇到不认识的算子这一步就会报错。解决办法是替换模型结构或开启部分的算子兼容选项。第二步是算子映射。NPU不是万能的它内部有针对Conv、Pooling、Activation等算子的硬件单元工具链会把中间表示图中每个节点映射到NPU支持的指令上。映射不了的算子会退化成CPU执行也就是常说的“CPU fallback”。CPU fallback会造成严重性能下降因为数据需要从NPU内存搬到CPU内存再搬回来每次切换都有开销。所以转换日志里如果看到CPU字样就要警惕了。第三步是内存规划和指令调度。NPU的计算单元有固定的调度方式数据要按特定的排列存储在内存中。工具链会根据模型结构计算出每一层输入输出的内存布局、对齐方式生成可执行指令流。这也是.rknn文件比ONNX模型“聪明”的地方它已经不是单纯的模型参数列表而是带硬件指令集的“可执行程序”。第四步是量化校准。默认情况下你会执行build(do_quantizationTrue, datasetdataset.txt)工具链读取dataset.txt里指定的几十张图片通过网络计算每一层的激活值范围然后据此把FP32权重和激活值量化为INT8。这一步能大幅缩小模型体积、提升推理速度但也可能带来精度损失。3.2 量化为什么会掉点如何缓解RK3568的NPU对INT8量化支持最完善所以部署时我们通常会开启量化。但量化本身就是个“精度换速度”的过程。常见问题包括检测框变不准、分类置信度普遍偏低、某项任务指标掉了好几个点。掉点最直接的原因是校准集不行。dataset.txt里的图片应该尽量贴近真实业务场景比如你识别安全帽最好从现场采集几十张不同光线、不同角度的图片放进去做校准而不是随便找几张猫狗图。校准集数量一般20到100张就够太少的话统计出来的激活值范围失真太多则浪费时间。第二个原因是前处理参数没对齐。转换时rknn.config里的mean_values和std_values必须和训练时保持一致。很多人训练用Normalize(mean[0.485,0.456,0.406], std[0.229,0.224,0.225])转换时却填了mean_values[[0,0,0]], std_values[[255,255,255]]结果推理结果一塌糊涂。RKNN的均值方差参数顺序是“每个通道的均值、每个通道的方差”并且要填写的是模型输入层的实际预处理值不是训练中间层的值。另外量化后的模型对某些层特别敏感比如检测头里的Sigmoid和输出层的坐标解码。如果整体量化掉点严重可以尝试只量化部分层。RKNN-Toolkit2里有按层设置量化方式的选项可以配合文档做混合精度量化。3.3 模拟器和实际板端怎么选RKNN-Toolkit2在PC端自带一个模拟器转换完成后可以直接在PC上跑推理显示结果。这个模拟器的意义是快速验证模型的正确性在还没有连接板子之前先发现“转换后效果是否正常”。但模拟器和真实的NPU执行细节并不完全一样。模拟器跑出来的精度和延迟只能作为参考真实的NPU调度、内存带宽、驱动开销只有把模型放到板子上才能测出来。所以我的建议是先用模拟器做正确性验证再推送到板子上跑真实性能。如果你手头有开发板通过USB连接PC转换脚本里可以指定运行目标为板端NPU让工具链直接调用板端RKNN Runtime推理这种模式叫“target connection”比模拟器更接近真机效果。具体来说RK3568对应的target平台在代码里一般写成rk3566因为两款芯片NPU同类。代码大致是这样rknn.config(target_platformrk3566)如果是在开发板上做交叉编译而不是直接用Python API连接就需要在板端启动rknn_server服务然后PC端通过init_runtime(targetNone, device_idboard_ip)连接。这时板子上要能通过adb或网络被PC访问到。4. 实操过程从ONNX到.rknn再到板端推理理论讲完下面走一遍完整流程。我用最常见的YOLOv5s为例带着你把转换脚本和板端脚本都过一遍。4.1 准备ONNX模型要转换模型首先得有一个ONNX文件。如果你用ultralytics训练过YOLOv5可以用下面命令导出python export.py --weights yolov5s.pt --include onnx --opset 12如果没有现成模型也可以从开源仓库下载官方预训练的yolov5s.onnx。下载完成后放到刚才yolov5示例目录下替换掉原来的文件。注意导出ONNX时不要加太多后处理操作最好只导出包含Preprocess、Backbone、Neck、Detect头的模型后处理NMS放到板端自己写。4.2 编写转换脚本官方test.py已经写好了转换逻辑关键的代码段是这样的from rknn.api import RKNN rknn RKNN() rknn.config(mean_values[[0, 0, 0]], std_values[[255, 255, 255]], target_platformrk3566) ret rknn.load_onnx(modelyolov5s.onnx) ret rknn.build(do_quantizationTrue, datasetdataset.txt) ret rknn.export_rknn(yolov5s.rknn)mean_values和std_values我前面强调过这里再次确认如果你的训练代码里对输入做了归一化到0到1那么mean0, std255是正确的如果训练代码里用了ImageNet的均值和方差就要对应修改。target_platformrk3566即使是RK3568也填这个因为工具链里把RK3568和RK3566统一按rk3566处理。转换成功后当前目录会多出一个yolov5s_relu.rknn文件。用ls -lh看看它的体积会因为INT8量化大幅缩小通常只有模型原体积的1/4左右。4.3 板端部署验证板端推理脚本yolov5.py的核心代码大致是这个结构from rknnlite.api import RKNNLite from PIL import Image import numpy as np rknn_lite RKNNLite() rknn_lite.load_rknn(yolov5s.rknn) rknn_lite.init_runtime() img Image.open(test.jpg).resize((640, 640)) img np.array(img).astype(np.float32) img img[:, :, ::-1] # RGB - BGR img np.expand_dims(img, axis0) outputs rknn_lite.inference(inputs[img]) # outputs 就是模型输出的原始张量接NMS后处理板端用户要保证已经装好RKNN-Toolkit-Lite2以及numpy、Pillow、opencv-python。如果你是做C应用可以不装Lite2直接用librknnmrt.so提供的C接口但原理一样先初始化runtime再加载模型再推理。实际操作时我建议先用官方test.py生成的同一张测试图在板端跑一遍确认输出结果和PC端模拟器一致。如果一致说明整个链路没问题如果不一致优先检查输入预处理是否完全一致包括缩放方式、填充方式、通道顺序、归一化参数。5. 常见问题与排查技巧实录这一部分是我在实际调试过程中踩过的坑整理成速查表照着顺序排查能省很多时间。5.1 Python版本与wheel安装问题症状可能原因解决办法pip install提示not a supported wheel下载的wheel平台不对比如把aarch64的包装到x86_64重新下载对应x86_64且Python版本匹配的wheelfrom rknn.api import RKNN报错Python版本与wheel不匹配或依赖缺失确认python -V安装对应requirements导入时提示numpy版本过高或过低系统Python环境存在其他框架的依赖冲突使用全新venv按requirements固定版本安装执行示例时报libGL相关错误OpenCV依赖的图形库缺失sudo apt install -y libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev虚拟环境里装好工具链后每次打开终端都要先source ~/rknn_env/bin/activate再执行转换脚本。如果忘记了python可能直接使用系统默认环境导致rknn.api找不到。我在终端提示符里习惯把虚拟环境名写进PS1这样一眼就能看出来当前在哪个环境。5.2 模型算子不支持与量化异常转换日志里如果报Unsupported operator首先要确认当前版本的RKNN-Toolkit2是否支持该算子。查看官方docs的算子支持列表或者升级到更新版本。如果确实是新训练框架产生的新算子可以尝试在导出ONNX时换一种表达方式比如把一些自定义模块拆成ConvActivation的组合。量化后效果变差优先检查Order of Preprocessing。RKNN的前处理是在NPU加载数据之前由CPU完成的所以mean_values和std_values影响的是输入给模型的数值一旦填错整个网络都是错的但模型本身可能依然能输出“看起来合理”的结果只是精度很低。我见过最隐蔽的情况是训练时使用的是RGB通道顺序转换脚本里却用了BGR导致检测框位置全乱。RGB和BGR的转换及mean/std值最好在脚本里写清楚并注释。还有一点不要随便把dataset.txt里的图片路径修改成不存在的文件会导致量化阶段直接卡死或崩溃。校准图片路径始终使用相对当前工作目录的正确路径。5.3 板子连不上、设备树与rootfs问题adb连不上RK3568最常见的原因是使用的USB口不对。RK3568的USB口分Host和OTG通常只有标了OTG Type-C或烧录口的那一个支持adb。换一根数据线试试很多线只能充电不能传输数据。确认板子系统里开启了usb adbd如果不支持就用网络adb连接adb connect 192.168.x.x:5555。很多人在OpenHarmony或自定义Buildroot系统里会遇到“RK3568设备树怎么选”的问题。RK3568有大量的开发板变种比如核心板厂商不同、扩展板接口不同设备树dts也跟着不同。选择的核心原则是先看你的核心板型号再看底板外设。如果启动内核后用NFS挂载rootfs还需要特别留意设备树里ethernet节点的PHY地址和复位引脚配置否则网络可能不通NFS自然挂不上。修改设备树推荐在Ubuntu环境下直接用dtc工具反编译现有dtb改dts再重新编译不要凭感觉乱建新的设备树。板端运行时如果出现HardFault或段错误优先查PC寄存器和LR寄存器地址看崩溃点是落在NPU库调用里还是后处理代码里。常见原因包括模型输入尺寸与板端预处理尺寸不一致、图片数组的步长不对、np.ascontiguousarray漏写导致内存不连续。加上print定位到具体代码行问题往往几分钟就能找到。5.4 十五分钟自查清单我把自己调试新模型时的流程固定成一套清单遇到问题不会乱PC端先跑官方test.py确认工具链本身没有问题。用自己的ONNX替换模型文件保留原名字先跑通转换。检查转换日志中的performance和memory信息看是否有CPU fallback。在PC模拟器上推理官方测试图确认检测结果正常。推送到板端用同一张图跑板端推理逐行对比结果。如果板端结果与PC不一致按“输入预处理、模型输入尺寸、通道顺序”的顺序排查。如果板端帧率不达标优先考虑减少模型输入尺寸、换更轻量的Backbone、开启更多线程做预处理。这套流程看起来简单但能过滤掉80%以上的常见问题。剩下20%是硬件问题或驱动问题那就要结合dmesg和adb logcat去查了。最后再分享一个我自己用得很顺的小技巧PC端工具链装好之后先不要急着转换自己的模型把官方仓库里的所有examples都跑一遍。每个example对应一个常用模型类型比如yolov5、mobilenet、resnet、retinaface。跑通之后你会对支持哪些算子、各种模型转换的耗时、输出怎么解析有一个整体印象。之后遇到自己的模型迁移起来会顺手很多。工具链这个东西跑通一次后面全是熟路。