企业官网建设流程全解析

1. 为什么我劝你先搞清楚RK3568和RK3588的NPU差异再动手

老实说，RKNN这套东西本身不难，真正卡住人的往往是第一步：你手上的芯片到底是哪个。RK3568和RK3588虽然都是Rockchip的NPU方案，都走RKNN工具链，但它们的NPU架构细节和实际算力表现差得不是一点半点。如果一上来就照搬别人的配置，大概率会在板子上跑出让你怀疑人生的结果。

RK3568的NPU算力标称0.8 TOPS（INT8），RK3588则是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加四核A55，RK3568是四核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 python=3.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里target='rk3568'之类的选项），不需要连板子，那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_platform='rk3588' ) # 2. 加载模型（以onnx为例） ret = rknn.load_onnx(model='model.onnx') if ret != 0: print('Load model failed!') exit(-1) # 3. 构建模型（这一步会做算子映射和优化） ret = rknn.build(do_quantization=True, dataset='dataset.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(target='rk3588') 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的日志完整读一遍。它会明确告诉你是哪个节点、什么算子。这时候通常的处理路径是：

1. 先查官方文档的算子支持列表，看这个算子是否被支持。如果支持，大概率是你的模型里用了某个很新或很特殊的onnx opset版本，尝试用onnxsim简化模型后再转。
2. 如果官方就不支持，尝试修改模型结构，把不支持的运算替换成等价的支持算子组合。比如某些模型里用Gather加Concat实现动态shape操作，可以重写为固定shape的Slice加Reshape。
3. 实在绕不过去，就退一步：把不支持的这部分算子拆出来放到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输出是动态shape，RKNN对动态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_quantization=True。对于大多数检测和分类模型，效果都能接受。但有两种情况建议用混合量化：

• 模型的某些层对数值非常敏感（比如检测框回归的最后一层），全量化后精度掉得厉害；
• 模型里同时有卷积层和全连接层，FC层对量化误差更敏感。

混合量化的配置方式是在rknn.config里指定custom_quantize_layers，把敏感层的名字加进列表中。但说实话，除非你对模型的数值分布有很深的了解，否则我不建议盲目上混合量化。我见过不少项目，混合量化设置不当，反而比全量化精度更低，而且排查起来极其痛苦（因为问题不再是你"量化了"还是"没量化"，而是"哪一层被影响了"）。

量化校准数据集的代表性，比量化算法本身更影响最终精度。一旦发现量化后精度崩了，我首先怀疑的是你的dataset.txt选图垃圾，而不是去调量化参数。

4. Android平台接入RKNN Runtime：JNI、权限和内存分配的连锁坑

4.1 库文件放置和JNI封装

RKNN在Android上的接入方式本质上就是通过JNI调用librknnrt.so。Rockchip官方提供了一份Android Demo，里面包含了编译好的JNI库和Java层的API封装。但是，实际项目里几乎不可能直接拿来用——你需要的不是Demo的界面和逻辑，而是理解它的调用链。

核心依赖是两个so文件：librknnrt.so（Runtime主库）和librknn_api.so（C 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包（targetSdkVersion=28）跑得好好的，Release包（targetSdkVersion=34）一到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转RGB：8毫秒
• Letterbox缩放：5毫秒
• 归一化和数据拷贝：4毫秒
• Numpy风格的解码（在Java层做的）：9毫秒
• 其余杂项：5毫秒

算下来光CPU就吃了31毫秒，和NPU推理加起来接近60毫秒，帧率自然上不去。

优化思路是流水线重叠：把预处理放到推理线程A，NPU推理放到线程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。举例来说，检测头里的DFL（Distribution 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集成阶段的细节处理。把本文提到的这些坑逐个趟过去，你的项目在板子上跑出稳定可用的效果，是完全可以做到的。