企业官网建设流程全解析

• 示例工程
• 人工智能
• 嵌入式
• 边缘计算
• 计算机视觉
• 模型优化

本文以 RKNN Model Zoo 仓库的官方 FAQ（FAQ.md / FAQ_CN.md）为主线，系统梳理 Rockchip NPU 平台（RKNPU1 / RKNPU2）在依赖升级、推理性能、模型量化、编译部署以及 YOLO 系列后处理过程中最常见的问题与排查思路。读完本文，你将掌握 RKNPU 依赖库的升级方法、推理性能差异的定位手段、量化掉精度的应对策略，以及"置信度超过 1""检测框填满整图""anchor 不匹配""MAP 精度偏低"等典型 YOLO 异常的根因与修复方向。

1. 环境、依赖与性能问题（Common Issue）

1.1 如何升级 RKNPU 的相关依赖库

RKNPU 的软件栈通常由三部分组成：驱动（Driver）、运行时（Runtime）与 RKNN-Toolkit 工具链。升级时三者需要匹配，RKNPU1 与 RKNPU2 两个体系的升级方式不同，官方 FAQ 给出的对应关系如下：

需要特别提醒：由于开发板规格存在差异，固件通常互不兼容，请向开发板的购买渠道获取适配的新固件及烧录方法，不要在不同型号板卡间混用固件。

仓库中与本主题直接相关的资源包括：3rdparty/rknpu1（内含 rknn_api.h 头文件与各平台的librknn_api.so）与 3rdparty/rknpu2（内含 rknn_api.h、rknn_matmul_api.h、rknn_custom_op.h 等），编译 C demo 时就是链接这些 runtime 库。

1.2 不同平台推理结果不同

受 NPU 代次差异影响，同一模型在不同平台上的推理结果存在略微差异属于正常现象。RKNN Model Zoo 的示例 README 也反复声明："Different platforms, different versions of tools and drivers may have slightly different results." 只有当差异非常显著时，才需要提交 issue 反馈。

1.3 demo 推理结果不对

推理结果异常时，第一排查项是驱动、runtime.so、RKNN-Toolkit 的版本是否满足要求。仓库主 README.md 的 "Environment dependencies" 章节列出了各版本对 SDK 的最低要求，例如：

也就是说，仓库内所有 demo 均基于最新 RKNPU SDK 验证，若使用更低版本验证，推理性能和推理结果都可能出错。升级前请先按 1.1 节的方式将三件套对齐。

1.4 demo 跑对了，但换成自己的模型跑错了

这是最典型的一类问题：官方 demo 正常，但替换成自己导出的模型后结果异常。官方 FAQ 给出的排查方向是：检查导出模型时是否遵循了对应 demo 文档的要求。

以 yolov5 为例，官方要求基于定制版本的 yolov5 仓库导出 ONNX 模型，并按照 examples/yolov5/README.md 的操作执行。该文档明确说明：仓库提供的模型是经过结构优化的模型，与官方原始模型不同。以 yolov5n 为例：

• 输出信息由[1, 19200, 85]调整为[1, 255, 80, 80]；
• 将模型中的一段子图（该子图对量化不友好）删除，放入后处理阶段实现。

如果用户直接使用未优化结构的模型，后处理代码与模型结构不匹配，就会出现 FAQ 第 3 节描述的各类异常（置信度异常、框数量异常等）。因此，换用自己模型时，务必先确认"模型导出方式 + demo 后处理代码"这一组合与官方一致。

1.5 模型推理性能达不到参考性能

README 中的性能表是各 demo 的参考基准，实测达不到时，官方 FAQ 列出了以下几个主要影响因素：

1. Python API 的推理性能通常弱于 C API，性能敏感的开发者应基于 C API 测试；
2. 性能数据口径不同：RKNN Model Zoo 公布的推理性能不包含前后处理，只统计rknn.run的耗时，与完整 demo 的端到端耗时存在差异——前后处理耗时与使用场景、系统资源占用强相关，需要基于实际环境测试；
3. 板卡未定频或未达到最高频率：部分固件会限制 CPU/NPU/DDR 的最高频率，导致推理性能下降。仓库提供了定频脚本 scaling_frequency.sh，使用方法为./scaling_frequency.sh -c <chip_name>，支持rv1126、rk1808、rk3566、rk3568、rk3588、rk3576、rv1106、rv1103等芯片。脚本按平台分别设定 CPU/NPU/DDR 目标频率，例如：

脚本执行后会写回当前频率并在freq_set_status文件中记录设置结果，可用于验证板卡是否已锁定在目标频率（README 的性能数据即基于各平台最大 NPU 频率采集）。

4. 其他应用占用 CPU/NPU 及带宽资源，也会显著拉低推理性能；
5. 大小核 CPU 芯片需要绑定大核：对于目前具有大小核 CPU 的 RK3588、RK3576，测试时应参考 RKNN-Toolkit2 用户手册第 5.3.3 小节，将测试绑定到大核上执行。

1.6 如何解决模型量化掉精度问题

模型开启 int8 量化后精度损失，首先应确认量化功能的使用方式是否正确——参考对应平台的 RKNN-Toolkit 用户手册（RKNPU1 平台参考 RKNN-Toolkit1 文档，RKNPU2 平台参考 RKNN-Toolkit2 文档）核对校准数据集、量化配置等细节。

如果量化方式无误，而是模型结构特性或权重分布导致 int8 量化本身掉精度，官方建议考虑两条路线：

• 混合量化（hybrid quantization）：对精度敏感的关键层保留更高精度；
• QAT 量化（Quantization-Aware Training）：在训练阶段引入量化感知，让网络权重自适应量化误差。

仓库各 demo 的转换脚本即为可对照的量化入口，例如 examples/yolov5/python/convert.py 中通过rknn.config(...)配置均值方差等预处理参数，再调用rknn.build(do_quantization=do_quant, dataset=DATASET_PATH)开启量化，其中DATASET_PATH指向datasets/COCO/coco_subset_20.txt这类包含 20 张校准图片的列表文件。

1.7 是否有板端 Python demo

有。在板端安装 RKNN-Toolkit-lite，然后使用对应 demo 的 Python 推理脚本，将导入语句从from rknn.api import RKNN修改为from rknnlite.api import RKNNLite as RKNN，即可在板端完成 Python 推理：

• RKNPU1 平台：使用 RKNN-Toolkit-lite；
• RKNPU2 平台：使用 RKNN-Toolkit-lite2。

官方同时提示：部分示例目前暂缺 Python demo；对性能有要求的用户更推荐使用 C 接口部署。

1.8 为什么其他模型没有 demo，是因为不支持吗

不是。大多数模型都是支持的，之所以只挑选了部分模型制作 demo，是受限于开发周期，同时为了照顾大多数开发者的需求，选择了实用性较高的模型作为示例。如果开发者有更好的模型推荐，可以通过 issue 或其他渠道反馈给 RKNPU 部门。

1.9 是否有大模型 demo

目前没有。对 transformer 类模型的支持仍在逐步优化中，官方也希望能尽早提供大模型 demo 供开发者参考使用。不过仓库已包含若干 transformer 结构的轻量示例，例如 examples/lite_transformer（机器翻译）、examples/clip（图文匹配）、examples/zipformer（流式语音识别）等，可作为理解 RKNPU 上 transformer 部署现状的参考。

1.10 为什么 RV1103、RV1106 能跑的 demo 较少

受限于 RV1103 / RV1106 的内存大小，许多较大模型的内存占用超出板端内存上限，因此暂不提供对应 demo。这也是为什么 README.md 将这些平台标记为"Limited support"的原因。选型时若目标平台是 RV1103/RV1106，需要优先评估模型体积与内存占用。

1.11 在 opencv 和 jpeg 库共用时会出现 Segmentation fault 报错

这是典型的库冲突问题：opencv 内部自带的 jpeg 库与 rknn_model_zoo 的3rdparty中的 jpeg_turbo 库（见 3rdparty/jpeg_turbo）符号冲突，导致段错误。解决方案有两种：

1. 重新编译一个不带 jpeg 库的 opencv，从根源上消除符号冲突；
2. 如果只是用 opencv 读取或保存 jpg 图片，可以在执行./build-linux.sh或./build-android.sh时指定-j参数来禁用 jpeg_turbo 库。

1.12 在编译阶段报错或者运行时提示找不到某些依赖库

这类问题通常是因为当前使用的交叉编译器与 rknn_model_zoo 默认使用的交叉编译器不一致。请按照 docs/Compilation_Environment_Setup_Guide.md 的说明，使用对应的编译器重新编译，注意先删除旧的 build 目录再重新构建。

该指南同时给出了工具链要求：Android 平台需通过环境变量ANDROID_NDK_PATH指定 NDK 路径（README 建议使用 r18 或 r19 版本）；Linux 平台需通过GCC_COMPILER指定交叉编译工具链，其中 aarch64 推荐gcc-linaro-6.3.1、armhf 推荐gcc-arm-8.3，RV1103/RV1106 系列需使用armhf-uclibcgnueabihf工具链。使用其他版本可能遇到 C demo 编译失败的问题。

2. RGA 相关问题

RGA（Rockchip RGA）是 Rockchip 的 2D 图形加速硬件单元，demo 中常用于图像缩放、格式转换等预处理。FAQ 明确说明：RGA 相关问题请参考 librga 官方文档（Rockchip_FAQ_RGA）。仓库侧的相关资源位于 3rdparty/librga，包含各平台（Android/Linux、aarch64/armhf/armhf_uclibc）的静态/动态库以及 im2d、RgaApi 等头文件，编译 demo 时会自动链接。

3. YOLO 系列问题

YOLO 是仓库中示例最多的检测模型（yolov5、yolov6、yolov7、yolov8、yolov10、yolo11、yolox、ppyoloe、yolo_world 等）。FAQ 专门总结了 5 类高频异常，其共同根因几乎都指向一句话：模型结构与后处理代码不匹配。

3.1 类别置信度超过 1

YOLO 的后处理代码必须与模型导出结构匹配，否则就会出现异常输出。当前 YOLO demo 使用的后处理要求：模型的类别置信度输出由 sigmoid 算子产生。sigmoid 将(-∞, ∞)的原始分数映射到(0, 1)区间，若模型尾部缺失 sigmoid 算子，类别置信度就可能大于 1，如下图所示（bus 置信度甚至达到数百个百分比）：

从源码可以印证这一约束：后处理在筛选框时依赖置信度阈值过滤，例如 examples/yolov5/python/yolov5.py 中OBJ_THRESH = 0.25、NMS_THRESH = 0.45，C 端 examples/yolov5/cpp/postprocess.h 同样定义BOX_THRESH 0.25、NMS_THRESH 0.45——一旦置信度超出[0,1]区间，这些阈值判断就会完全失效。遇到此类问题，请按 demo 文档要求的导出方式重新导出模型（见 1.4 节）。

3.2 推理结果出现框非常多，填满了整个图

如上图所示，检测框密集到覆盖整个画面，通常有两种可能：

1. 与 3.1 节同因：模型尾部缺失 sigmoid 算子，导致类别置信度异常、大量低质量框通过过滤；
2. demo 阈值配置不当：box threshold（置信度阈值）设置得太小、nms threshold（NMS 阈值）设置得太大，导致大量重叠框被保留。

源码中可以看到阈值的默认值与"错误示范"：在 examples/yolov5/python/yolov5.py 中默认OBJ_THRESH = 0.25、NMS_THRESH = 0.45，而被注释掉的示例OBJ_THRESH = 0.001、NMS_THRESH = 0.65正是"阈值过松"导致框爆炸的典型配置。排查时可先恢复到 demo 默认阈值验证，再结合模型结构确认是否缺失 sigmoid。

3.3 框的位置、置信度是对的，但框和物体不贴合（yolov5、yolov7）

这种情况通常是anchor 不匹配导致的。yolov5/yolov7 这类基于 anchor 的检测器，其先验框尺寸写死在模型结构里；如果导出模型时打印的 anchor 信息与 demo 中默认的 anchor 配置不一致，就会出现"框位置和置信度正确、但大小与目标不贴合"的现象。

仓库中对应的默认 anchor 配置示例见 examples/yolov5/model/anchors_yolov5.txt，内容为 18 个数值（即 3 个尺度 × 3 个 anchor 对），例如小尺度(10, 13, 16, 30, 33, 23)、中尺度(30, 61, 62, 45, 59, 119)、大尺度(116, 90, 156, 198, 373, 326)。导出模型时请留意终端打印的 anchor 信息，与 demo 默认配置比对是否一致。

3.4 MAP 精度相比官方的结果低一些

官方 FAQ 给出了两个主要原因，外加一个测试注意事项：

1. 动态 shape vs 固定 shape：官方测 MAP 时使用动态 shape 模型，而 RKNN Model Zoo 为了简单易用采用了固定 shape 模型，MAP 测试结果天然会低一些；
2. 量化精度损失：RKNN 模型开启量化后会有一定精度损失（应对方法见 1.6 节）；
3. 图片读取方式影响 C 端测试结果：若在板端用 C 接口测 MAP，读取图片的方式会影响测试结果，例如基于cv2和基于stbi得到的 MAP 结果并不相同——仓库的 utils 中同时提供了 utils/image_utils.c（基于 stb_image 实现）和 3rdparty 的 opencv，测试时需固定读取方式以保证结果可比。

3.5 如果不修改 YOLO 模型结构，NPU 可以跑吗

可以，但不推荐。

• 若不修改模型结构，Python demo 与 C demo 对应的后处理代码都需要自行调整，以适配原始模型的输出格式（例如 yolov5 原始输出[1, 19200, 85]与优化后[1, 255, 80, 80]的后处理逻辑完全不同）；
• 官方对模型结构的调整是基于精度与性能双重考量的：保持原模型结构可能面临量化精度不佳（模型尾部子图对量化不友好）以及推理性能更差的问题。

因此，除非有特殊原因，建议优先使用 demo 配套的优化模型结构，把重心放在应用层的后处理优化上。

结语

本文围绕 RKNN Model Zoo 官方 FAQ 的 16 类高频问题，从环境依赖、性能调优、量化精度、编译部署到 YOLO 后处理异常，逐项给出了根因分析与排查路径，并结合仓库源码（scaling_frequency.sh、examples/yolov5、utils/image_utils.c 等）补充了底层依据。排查思路可以归纳为一条主线：先对齐版本（驱动/runtime/Toolkit），再对齐模型（导出结构与后处理、anchor、sigmoid、阈值），最后对齐环境（定频、大核绑定、资源占用）。按此顺序逐层排查，绝大多数 FAQ 中描述的问题都能定位到具体根因。

• 示例工程
• 人工智能
• 嵌入式
• 边缘计算
• 计算机视觉
• 模型优化