1. 为什么我劝你先搞清楚RK3568和RK3588的NPU差异再动手老实说RKNN这套东西本身不难真正卡住人的往往是第一步你手上的芯片到底是哪个。RK3568和RK3588虽然都是Rockchip的NPU方案都走RKNN工具链但它们的NPU架构细节和实际算力表现差得不是一点半点。如果一上来就照搬别人的配置大概率会在板子上跑出让你怀疑人生的结果。RK3568的NPU算力标称0.8 TOPSINT8RK3588则是6 TOPS。这个数字差距不是简单的快7倍这么粗暴因为二者的NPU内部架构完全不同。RK3588的NPU由三个独立的核心组成支持动态负载均衡你在rknn.config里能看到一个叫npu_core_mask的参数可以指定用哪个核或者全部核。RK3568没有这个参数它就是一个整体调度策略简单得多。实际开发中我遇到过不少人拿着RK3588的Demo工程直接烧到RK3568上结果模型加载直接报错。原因大多集中在两点一是rknn.config里的某些设置比如target_platform写的是rk3588不支持3568二是模型的输入分辨率或者算子组合对3568的NPU单元利用率极低跑出来的帧率甚至不如纯CPU优化后的结果这时候你根本分不清是模型问题还是板子问题。还有个容易忽视的点是算力之外的显存带宽和CPU协同能力。RK3588的CPU是四核A76加四核A55RK3568是四核A55。做端到端延时优化时CPU负责的预处理resize、归一化、色彩空间转换和后处理NMS、解码往往比NPU本身的推理还耗时。同样的YOLOv5s模型3588上NPU推理可能只要20毫秒但加上CPU的预处理后处理整体能达到较高帧率3568上如果预处理不做优化NPU推理40毫秒CPU处理再吃掉30毫秒帧率直接掉到不可用的程度。所以接到这类项目我第一件事就是确认芯片型号、系统版本、RKNN-Toolkit2版本三者之间的兼容关系。官方文档给的兼容性表一定要看但只看那个还不够——你必须在目标板子上先跑通一个最简单的分类模型比如mobilenet_v1确认NPU驱动和Runtime工作正常再谈后续的复杂模型对接。这一步能帮你把环境问题和模型问题彻底隔离。顺便说一下选型建议如果你的应用场景是轻量级检测比如单路视频流、门禁考勤RK3568完全够用没必要上3588如果是多路摄像头、大分辨率输入或者Transformer类模型3588的性价比优势就体现出来了。2. 环境准备RKNN-Toolkit2的安装比你想的更抠细节2.1 Python版本和依赖冲突是第一个大坑RKNN-Toolkit2目前对Python版本的支持是有限制的官方推荐的是Python 3.8到3.11这个区间不同版本的工具链对Python版本要求还有细微差异。我见过太多人直接在系统全局环境里pip install然后被numpy、opencv的版本冲突搞到心态炸裂。我的建议是永远用独立虚拟环境也就是conda或者venv。具体步骤其实很固定conda create -n rknn python3.8 conda activate rknn pip install rknn-toolkit2装完之后立刻验证一下启动Python输入from rknn.api import RKNN如果不报错说明基本环境通了。这一步很多人跳过了结果后面写脚本时才发现import失败再回头排查环境问题浪费时间。这里还有个隐藏坑RKNN-Toolkit2依赖的onnx版本如果和你的模型导出环境不一致转换时会出现各种莫名其妙的解析错误。比如你在训练机上用onnx 1.14导出的模型RKNN-Toolkit2里装的是onnx 1.12转换时可能报Unsupported operator或者直接段错误。解决方案是转换环境和你导出onnx的环境尽量一致或者至少在转换前用onnx.checker先把模型验证一遍。2.2 板端Runtime和PC端工具的版本必须对齐这套工具链分两部分PC端的RKNN-Toolkit2负责模型转换、量化、模拟推理和板端的RKNN Runtime负责在NPU上真正跑模型。这两个东西的版本必须配套否则你在PC上转换出来的rknn模型拷贝到板子上加载时会报版本不匹配的错。具体版本对应关系每次发布都会变我的习惯是以板端固件里预装的Runtime版本为基准然后去下载对应版本的RKNN-Toolkit2。怎么确定板端的Runtime版本跑一下板子上的librknnrt.so库strings librknnrt.so | grep -i version或者直接调rknn_init接口时它会打印版本日志。拿到版本号之后再去PC端装对应版本的Toolkit2这样最稳。2.3 Ubuntu版本也会影响转换结果这个坑比较隐蔽。RKNN-Toolkit2在Ubuntu 18.04、20.04、22.04上的表现不完全一样尤其是在依赖的libstdc版本上。我自己在20.04上一切正常换到22.04上同样的代码、同样的版本号转换时居然抛出了GLIBCXX_3.4.30 not found的错误。这是因为系统库版本和工具链里预编译的二进制不匹配。如果你也遇到这类怪问题先别急着重装看看是不是系统库的事。ldd rknn_toolkit2-1.6.0-cp38-cp38-linux_x86_64.whl如果输出里有not found那就说明缺库。别折腾系统的库那是另一个深渊我推荐直接用Docker。Rockchip官方提供了带RKNN-Toolkit2的Docker镜像拉下来直接用省掉所有环境问题。docker pull rockchip/rknn-toolkit2不过用Docker有个注意点容器内的路径映射和USB设备透传要处理好。如果你用RKNN-Toolkit2的板端模拟器RKNN类的init_runtime里targetrk3568之类的选项不需要连板子那Docker非常舒服如果要连板子做联调记得加--device /dev/usb之类的参数把USB透传进去。3. 模型转换YOLO系列、Vision Transformer这些新模型最容易翻车3.1 转换流程主线和完整代码骨架先说主流程无论什么模型RKNN转换的骨架代码都是这一套from rknn.api import RKNN rknn RKNN() # 1. 配置 rknn.config( mean_values[[0, 0, 0]], std_values[[255, 255, 255]], target_platformrk3588 ) # 2. 加载模型以onnx为例 ret rknn.load_onnx(modelmodel.onnx) if ret ! 0: print(Load model failed!) exit(-1) # 3. 构建模型这一步会做算子映射和优化 ret rknn.build(do_quantizationTrue, datasetdataset.txt) if ret ! 0: print(Build model failed!) exit(-1) # 4. 导出rknn文件 ret rknn.export_rknn(model.rknn) if ret ! 0: print(Export rknn failed!) exit(-1) # 5. 用模拟器做精度验证 rknn.init_runtime(targetrk3588) outputs rknn.inference(inputs[img]) rknn.release()这段代码看起来简单但每一步都能翻车。mean_values和std_values如果和训练时不一致模型输出直接漂移检测框全偏。很多人喜欢套用YOLO那套0-255的归一化参数实际上不同模型训练时的预处理逻辑差别很大必须从训练代码里把预处理参数抄过来不能想当然。dataset.txt是量化用的校准图片列表每行一个图片路径。这个文件的编写有讲究图片数量不用太多100到200张有代表性的就行但一定要覆盖模型实际使用场景的分布。比如做行人检测你量化数据集里全是白天、晴天、正面视角的图片换到晚上、逆光场景效果就会崩。3.2 算子不支持的排查方法转换时最常见的报错就是Unsupported operator。这个问题的本质是RKNN工具链只支持一部分ONNX算子直接映射到NPU硬件指令剩下的要么通过CPU算子在NPU上拆分成可执行片段由CPU协同计算兜底要么完全不支持。遇到算子不支持的报错先把rknn_build的日志完整读一遍。它会明确告诉你是哪个节点、什么算子。这时候通常的处理路径是先查官方文档的算子支持列表看这个算子是否被支持。如果支持大概率是你的模型里用了某个很新或很特殊的onnx opset版本尝试用onnxsim简化模型后再转。如果官方就不支持尝试修改模型结构把不支持的运算替换成等价的支持算子组合。比如某些模型里用Gather加Concat实现动态shape操作可以重写为固定shape的Slice加Reshape。实在绕不过去就退一步把不支持的这部分算子拆出来放到CPU上跑NPU跑主体网络。虽然带来额外的数据拷贝开销但总比完全跑不了强。3.3 YOLO系模型的常见转换问题和预处理对齐YOLOv5、YOLOv8这些模型是RKNN用户用得最多的网上教程也多但坑依然不少。最典型的问题是版本差异YOLOv8的导出onnx中输出层已经带了解码逻辑DFL部分而YOLOv5不带需要在后处理里自己解码。这个差异会影响你在RKNN中是否要额外做后处理算子融合做不好就会导致精度正常但检测框错位。以YOLOv8为例onnx导出时建议把nms去掉只保留原始输出。RKNN这边不需要在模型里带NMS因为rknn.inference拿到raw output之后NMS用CPU做反而更灵活。如果非要把NMS塞到模型里大概率会遇到算子兼容问题而且NMS输出是动态shapeRKNN对动态shape的支持目前是有限且反人类的别自找麻烦。预处理对齐方面YOLO系列通常用Letterbox做等比缩放填充。但Rockchip官方给的一些Demo里直接用的是cv2.resize拉伸到输入分辨率这个预处理差异会导致模型精度明显下降。正确的做法是在板端代码里先做Letterbox再做cv2.cvtColor转RGB最后做归一化。如果你嫌麻烦想把Letterbox放到模型内部通过rknn.config的inputs参数直接指定输入尺寸那就必须在训练推理时也保持一致否则精度一样会崩。3.4 从YOLO26到DINOv3新模型转RKNN的经验教训热词里有人搜yolo26转rknn、dinov3转rknn说明现在大家关注的都是新模型。YOLO26这类目标检测新模型的变体有很多不少结构里带了注意力模块、变形卷积或者动态上采样转换时容易出问题。我的实测体验是YOLO26的某些变体在rknn.build阶段会报不支持BilinearSample算子的错误。解决思路是把它降级成Resize算子前提是上采样倍数固定不涉及动态坐标。DINOv3这种Vision Transformer模型转RKNN最大的问题倒不是算子而是模型参数量大、计算图复杂转出来的rknn文件动不动就上百MB板端加载时间长、内存占用高。转换时建议打开optimization_level为1默认是1并把不需要的辅助输出节点用rknn.config的outputs参数裁剪掉。新模型转RKNN我的习惯性做法是先在PC端用模拟器init_runtime里不接target走默认模拟做一次inference对比对比对象是onnxruntime在同输入下的输出。两者的相对误差如果在1%以内尤其是输出tensor绝对误差分布再上板子不迟。这一步能筛掉大量低级错误。3.5 量化别随便用混合量化除非你真的懂默认的量化策略是全INT8量化do_quantizationTrue。对于大多数检测和分类模型效果都能接受。但有两种情况建议用混合量化模型的某些层对数值非常敏感比如检测框回归的最后一层全量化后精度掉得厉害模型里同时有卷积层和全连接层FC层对量化误差更敏感。混合量化的配置方式是在rknn.config里指定custom_quantize_layers把敏感层的名字加进列表中。但说实话除非你对模型的数值分布有很深的了解否则我不建议盲目上混合量化。我见过不少项目混合量化设置不当反而比全量化精度更低而且排查起来极其痛苦因为问题不再是你量化了还是没量化而是哪一层被影响了。量化校准数据集的代表性比量化算法本身更影响最终精度。一旦发现量化后精度崩了我首先怀疑的是你的dataset.txt选图垃圾而不是去调量化参数。4. Android平台接入RKNN RuntimeJNI、权限和内存分配的连锁坑4.1 库文件放置和JNI封装RKNN在Android上的接入方式本质上就是通过JNI调用librknnrt.so。Rockchip官方提供了一份Android Demo里面包含了编译好的JNI库和Java层的API封装。但是实际项目里几乎不可能直接拿来用——你需要的不是Demo的界面和逻辑而是理解它的调用链。核心依赖是两个so文件librknnrt.soRuntime主库和librknn_api.soC API封装库。Android工程里要放到jniLibs/arm64-v8a目录下。注意这俩库必须和你的板载系统版本严格匹配拿3588的库放到3568上接口可能一致但底层调度完全不兼容跑起来要么报错要么性能异常。JNI封装建议自己写一层不要直接用Java层反射调用性能差而且接口难维护。用C封装RKNN类的核心调用暴露给Java的接口就四个public native boolean init(String modelPath); public native float[] inference(byte[] inputData, int width, int height); public native void release();C侧用AImageReader或者Bitmap拿到输入图像的像素数据通过env-GetByteArrayElements拷贝到native侧做预处理再喂给rknn_inputs_set和rknn_run。4.2 targetSdkVersion和Android系统权限问题Android平台接入RKNN时有个很容易被忽略的坑targetSdkVersion。如果你targetSdkVersion设在28以上系统对/data目录的访问权限会收紧而RKNN Runtime初始化时可能会尝试访问某些系统路径来创建工作目录或缓存文件。我遇到过的情况是Debug包targetSdkVersion28跑得好好的Release包targetSdkVersion34一到rknn_init就返回RKNN_ERR_PARAM_INVALID。排查半天发现是/data/local/tmp下没有写权限导致的。解决方案是rknn_init之前先确保工作目录存在且可写File dir new File(activity.getExternalFilesDir(null), rknn_cache); if (!dir.exists()) dir.mkdirs(); System.setProperty(rknn.cache.dir, dir.getAbsolutePath());另外如果你在Android 10以上的设备上做摄像头实时推理别忘了申请CAMERA权限并且要在onResume里动态请求而不是只在Manifest里声明。这个和普通Android开发的权限逻辑一致但实际项目中确实会有人在这里翻车。4.3 RKNN内存分配:rt_mem和rmem的调参经验RKNN Runtime加载模型时会申请两类内存一个是rt_mem运行时内存一个是rmem中间计算结果内存。这两个值的默认分配策略在多数设备上没问题但在RK3588上如果你同时加载多个模型或者模型输入分辨率较大就很容易出现rknn_init后内存占用暴增甚至OOM。更关键的是Android系统对单进程可用的内存有限制/proc//oom_score_adj会动态调整RKNN Runtime是native层内存分配不占用Java堆但它计入PSS。如果你的app同时还有Camera2的图像流一块1080p的YUV帧缓冲区差不多3MB叠加多个模型实例很容易触发系统的low memory killer。调参的方式有两个方向通过rknn_init的flag参数设置RKNN_FLAG_MEM_ALLOC_OUTSIDE把模型权重和中间内存放到外部显式管理的内存池里计算模型峰值内存方法是在PC端转换后用rknn_build日志里输出的Total Memory: xx MB做参考然后在板端用/proc/meminfo做前后对比。我实际项目里的策略是推理线程单独放在一个android:process:rknn的独立进程里。这样RKNN的native内存崩了不会拖垮主进程而且独立进程的内存回收策略更宽松。缺点是IPC有开销但用MemoryFile传图数据实测下来开销可控。4.4 摄像头分辨率对推理性能的隐藏影响很多人做完模型转换和推理之后发现帧率上不去就开始怀疑NPU能力。其实很多时候瓶颈根本不在NPU而在摄像头预览数据的处理链路。以RK3588为例Camera2的ImageReader拿到的YUV数据format通常是YUV_420_888而模型需要的是RGB输入。这个YUV转RGB的步骤如果没有用RenderScript或者OpenGL做GPU加速而是纯CPU跑一张1080p的图要吃掉20到30毫秒。再加上缩放、归一化CPU直接成为瓶颈。我的优化建议是把分辨率降到模型输入分辨率再转RGB。比如模型输入是640x640那Camera2就直接用640x640的流去预览推理虽然预览显示效果差点但省掉了缩放步骤。如果你的模型输入是动态分辨率尽量选一个和摄像头传感器输出的对齐值避免多一次缩放。另一个优化点是ImageReader的回调里不要做耗时操作先把Image的ByteBuffer拷贝出来再交给推理线程否则会卡帧。这个Buffer拷贝用ByteBuffer.allocateDirect在native层做性能好很多。5. 板端实测跑分和真实帧率之间的差距哪里来5.1 perf_debug是排查性能问题的第一步RKNN Runtime提供了一个很好的调试工具rknn.query接口里的RKNN_QUERY_PERF_DETAIL。你可以在每次rknn_run之后调用rknn_query(ctx, RKNN_QUERY_PERF_DETAIL, perf, sizeof(perf)); printf(NPU inference time: %ld us\n, perf.time_on_npu);这个时间就是纯NPU推理耗时不包括预处理和后处理。拿到这个数字之后你才能客观评估模型在NPU上的表现而不是笼统地说卡或流畅。实测下来同一个小模型在3568上跑30毫秒、在3588上跑15毫秒是正常的。但如果3588上跑的还是30毫秒那多半是模型没有充分利用三核。这时候检查rknn.config里的npu_core_mask是不是只用了单核或者改成RKNN_NPU_CORE_AUTO让调度器自动分配。5.2 CPU协同和流水线重叠处理端到端性能问题时一定要记住NPU不是唯一的瓶颈预处理和后处理的耗时往往被严重低估。我做过一个rk3568的项目模型推理NPU耗时28毫秒看起来不错但端到端跑起来只有15帧。加log定位后发现YUV转RGB8毫秒Letterbox缩放5毫秒归一化和数据拷贝4毫秒Numpy风格的解码在Java层做的9毫秒其余杂项5毫秒算下来光CPU就吃了31毫秒和NPU推理加起来接近60毫秒帧率自然上不去。优化思路是流水线重叠把预处理放到推理线程ANPU推理放到线程B后处理放到线程C做成三级流水线。理想状态下整体帧率由最慢的一级决定而不是三级耗时叠加。用BlockingQueue或者Android的HandlerThread都能实现关键是Buffer复用避免每次都重新分配内存。5.3 零拷贝零拷贝API的实际收益和适用场景RKNN的零拷贝0-copy接口指的是通过rknn_create_mem和rknn_set_io_mem直接操作设备内存跳过rknn_inputs_set和rknn_outputs_get内部的拷贝逻辑。零拷贝的实际收益取决于你的数据链路。如果你从Camera2拿到的图本身就是GPU或硬件编码器的buffer并且能和RKNN的rknn_set_io_mem直接共享内存收益非常显著。但如果你从Java层拿到一个普通的ByteArray在native侧做GetByteArrayElements之后还是要做一次memcpy到设备内存那零拷贝就没太大意义反而增加代码复杂度。我的经验是项目第一版先用标准接口跑通再根据profiling的结果决定要不要上零拷贝。不要一上来就追求极致性能否则代码写不下去性能还没提上来先被调试搞崩溃了。零拷贝的官方Demo在RKNN SDK的examples目录里有rknn_zero_copy_demo建议跑一遍感受一下数据流转。注意这个Demo里的输入是dma_buf也就是说你要有办法拿到dmabuf fd这在Android的Camera2 HAL层才能拿到应用层直接用的场景并不多。6. 从能跑到跑好模型优化和算法侧配合的实用经验6.1 模型结构要和NPU特性对齐既然要走RKNN部署模型结构在训练阶段就要考虑NPU的偏好。Rockchip NPU对以下算子组合支持得特别好普通3x3卷积和1x1卷积ReLU / ReLU6 / LeakyReLU这些激活函数会被算子融合优化标准BatchNorm转onnx时可以直接fold进卷积固定stride的下采样而以下几种结构容易被NPU拆开处理性能下降明显动态shape的操作包括动态batch、动态分辨率特殊的上采样方式比如PixelShuffle在某些版本上支持不佳大量小的、非标准卷积核比如5x5、7x7的卷积NPU要拆成多个指令完成多分支的ADD/CONCAT虽然支持但分支过多会导致计算图调度开销增大在训练阶段做结构选择时优先选轻量且对NPU友好的backbone。举例来说检测头里的DFLDistribution Focal Loss在YOLOv8里用得多它包含的卷积和softmax在RKNN上支持没问题但如果你把后处理里的argmax也放进模型就会遇到不小的麻烦。我建议训练时只保留主干和检测头把最后的解码和NMS全部放到CPU后处理。6.2 量化感知训练比你想的值钱如果你的项目对最终精度要求高而且训练资源允许强烈建议做量化感知训练QAT而不是训练完再拿PTQ硬量化。RKNN的PTQ对大多数模型来说精度损失可控但Transformer类模型比如DINOv3、一些ViT变体在PTQ下经常出现精度掉2到5个点的情况。QAT能把这部分损失压回0.5个点以内。用PyTorch做QAT的流程是训练到最后阶段把模型转成torch.quantization的QAT模式用一个小学习率继续微调几个epoch然后导出onnx时保留量化节点再进RKNN-Toolkit2转换。RKNN-Toolkit2会自动识别这些QAT节点并利用它们做量化。但注意一点QAT模型的onnx导出配置和普通模型不一样需要在导出时指定qat_onnx的配置确保量化节点被正确保留。否则你导出的模型和普通模型没区别QAT等于白做了。6.3 多模型串并联和线程池调度有些项目需要在端侧跑好几个模型比如先做人脸检测再对检测到的区域做关键点识别或者做属性分类。这时你面临两个选择是把两个模型合并成一个多输出的模型还是分别加载串行推理。如果两个模型有共享的backbone合并成一个模型可以减少内存占用和NPU初始化的开销。但如果两个模型结构差异大比如一个CNN检测器加一个Transformer分类器合并后的模型在RKNN里转换可能碰到奇怪的算子问题而且rknn_build的时间会很长调试成本高。我的建议是分别加载、串行推理。用两个RKNN实例各自独立分配内存在Java层做一个简单的线程池调度。这种方案代码清晰、调试方便性能上损失的那一点主要是模型切换时的内存加载开销完全可以通过合理调度抵消。实测中更优的做法是让两个RKNN实例分别跑在不同的NPU core上RK3588支持多核分配。运行时用rknn_init的flag参数或者config里的core_mask指定各自使用的核这样两个模型可以并行推理互不干扰。3568上没这个条件就只能用CPU线程切换来模拟并行效果一般但至少不会妨碍主流程。6.4 板端浮点数和定点数混合精度的思考回到实践层面很多人在模型落地时会陷入全INT8或者全FP16的两难。RKNN架构里量化后的模型默认是INT8推理。但有一些层如果留在FP16/FP32对精度帮助很大比如最后的检测头。Rockchip SDK里有个隐藏技巧转换的时候不用把所有层都强制INT8某些层可以显式保留浮点计算这就是我前面提的混合量化。但这里的混合颗粒度比较粗只能按层设置不能细粒度控制某个通道或某个维度。如果你的精度问题出现在特定层先尝试调整该层的量化参数比如给该层的输入输出设置不同的量化范围通过custom_quantize_layers配合量化表。如果调参解决不了再考虑混合量化或者后处理补偿。7. 工程落地的一些补充思考7.1 版本管理是隐形的大坑RKNN工具链迭代非常快一年发好几个大版本。不同版本之间的rknn模型格式、Runtime API、量化算法都可能存在不兼容。工程化项目的版本管理策略很重要我建议建立一个版本对照表记录板端固件版本、RKNN Runtime版本、RKNN-Toolkit2版本、模型onnx版本。每次升级工具链先在PC端用同一份模型跑一次转换和模拟器推理对比新旧版本的精度差异和性能差异再决定是否升级。模型文件和rknn文件全部进Git管理但不要把转换环境依赖的大文件比如toolkit的whl包也提交进来用requirements.txt记录依赖版本就行。7.2 日志和调试信息的保留板端调试时RKNN的C API本身提供了比较完善的错误码但打印出来的信息往往不够直观。我习惯在JNI封装里加一层错误码映射把RKNN_ERR_*枚举转成可读字符串。比如RKNN_ERR_PARAM_INVALID对应参数无效检查模型路径、输入尺寸和模型版本这样排查问题快得多。另外rknn_query除了性能信息还可以查询输入输出张量的属性和数据类型。在板端初始化完模型后做一个打印所有输入输出张量的工具函数把shape、type、量化参数全部打出来和PC端转换时记录的对一遍能提前发现很多输入输出不匹配的问题。7.3 稳定性和异常恢复NPU推理在长时间运行后偶发死锁或超时是可能存在的。RKNN Runtime的接口本身是同步阻塞式的一旦因为某种原因卡在rknn_run里没有超时机制的话整个推理线程就挂了。我的经验是给rknn_run加一个看门狗在Java层用Handler.postDelayed设置超时比如2秒超时后主动release掉当前RKNN实例重新init再加载模型。虽然这个操作很重但至少能让系统自愈不需要重启整个App。另外如果要长时间连续运行推理服务建议定期比如每10万帧主动重启一次推理引擎释放潜在的资源泄漏。这个动作在后台服务里做不影响用户体验。最后聊一句RKNN这套工具链的问题不少文档也不是特别完备但它在端侧NPU部署这一块确实是国内用得最广、社区最活跃的路线。RK3568和RK3588这两颗芯片的NPU潜力并不小很多时候跑不起来或跑得慢的根源都在于模型转换阶段和Android集成阶段的细节处理。把本文提到的这些坑逐个趟过去你的项目在板子上跑出稳定可用的效果是完全可以做到的。