瑞芯微RK3588 NPU开发环境搭建笔记

date

Mar 11, 2026

slug

2026-03-11-the-development-environment-of-RK3588-NPU

status

Published

瑞芯微NPU应用开发框架

瑞芯微的NPU应用开发的整体开发流程上，基本上与君正AI应用开发的后处理流程（Post Processing）大致一致，首先是在PC上基于Pytorch或者tensorflow等进行模型的开发和训练，完成后把这个模型（如onnx格式或者pt格式）使用一个 RKNN-Toolkit2 的工具转换为RKNN格式，这个RKNN格式才是能够在瑞芯微芯片上跑起来的端侧模型格式，后续在生产环境中使用C/C++语言调用这个模型进行前向推理。

RKNN的软件框架如下图所示：

RKNN-Toolkit2、RKNN-Toolkit-Lite2、RKNPU2 C++ API之间的关系：

RKNN-Toolkit2用于把PC或者服务器上训练好的模型转换为可以在瑞芯微NPU上运行的RKNN格式，运行在PC端。

RKNN-Toolkit-Lite2是一个可以在瑞芯微NPU上基于RKNN格式的模型进行前向推理的工具，运行在瑞芯微处理器上。

RKNN-Toolkit-Lite2本质上是一个在瑞芯微处理器上运行的Python包，所以其执行的前向推理是在瑞芯微硬件上跑的python环境中运行。如果对性能有更高要求，应该使用RKNPU2的C++ API来运行AI而不是RKNN-Toolkit-Lite2。

所以：RKNN-Toolkit2用于进行模型转换；RKNN-Toolkit-Lite2用于对转换后的模型在板端进行快速验证和测试；RKNPU2 C++ API才用于最终的项目实际落地。

我自己的看法，在板端的推理上，C/C++代码的效率要远远高于Python。所以其实没有太大必要在板端用RKNN-Toolkit-Lite2的python脚本去做推理验证，直接用RKNN-Toolkit2进行模型转换，然后在板端用C/C++进行推理才是一步到位的最成熟的做法。当然，使用RKNN-Toolkit-Lite2的python脚本在板端去做推理验证，优势则在于有大量Python包的支持，而且与PC端环境一致，写推理代码更容易。

RKNN-Toolkit2 能够支持的芯片平台列表：

RK3588 Series

RK3576 Series

RK3566/RK3568 Series

RK3562 Series

RV1103/RV1106

RV1103B/RV1106B

RV1126B

RK2118

如上所述，瑞芯微NPU应用开发主要依赖于RKNN生态。在瑞芯微芯片的NPU上进行应用开发主要依赖于以下两个在Github上维护的代码仓库：

RKNN-Toolkit2： airockchip/rknn-toolkit2 ，模型转换工具。

RK Model Zoo： airockchip/rknn_model_zoo ，模型上板运行的支持示例。

RKNN-Toolkit2开发环境的搭建

截至2026年初，最新的RKNN-Toolkit2的版本是2.3.2。

进行瑞芯微RKNN NPU生态的应用开发与测试，首先要进行RKNN-Toolkit2开发环境的搭建。从Github上下载RKNN-Toolkit2和RKNN Model Zoo仓库：

模型转换的Python环境

新建一个专门的rknn环境(Python版本指定为3.12)并安装RKNN-Toolkit2及其所有的依赖包（rknn-toolkit2-master/rknn-toolkit2/packages/x86_64）：

注意，按照以上流程安装的Python3.12环境，在后续在Model Zoo中把Yolov5的onnx文件转换为rkkn时会报错：AttributeError: module 'onnx' has no attribute 'mapping'，这是因为Python 环境中安装的 onnx 库版本过高，与当前的 rknn-toolkit2 (v2.3.2) 产生了不兼容。应该在requirements_cp312-2.3.2.txt修改onnx依赖版本为：onnx==1.16.1, 而不是安装onnx的最新版本。

交叉编译环境

板端C/C++代码的交叉编译工具（rk3588为aarch64架构，所以安装64位系统的编译工具）：https://releases.linaro.org/components/toolchain/binaries/6.3-2017.05/aarch64-linux-gnu/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.tar.xz ，后续在编译模型上板推理的C/C++ demo时要用。

板端NPU驱动环境

此外，如以上RKNN的软件框架图所示，在RK3588板端上所执行的AI推理，同时还需要依赖于板端NPU的相关支持环境，包括板端kernel的NPU驱动、瑞芯微RKNN网络的运行时库以及其他的支持库。

首先一点，需要在板端的Kernel中启动NPU驱动支持，并且确保kernel的NPU驱动版本与RKNN-Toolkit2及其运行时库的版本相匹配。可以在Kernel的启动信息或者通过dmesg得到NPU驱动的版本信息：

除了以上NPU驱动支持以外，板端应用程序在NPU上执行推理还需要运行时库librknnrt.so的支持。librknnrt.so在rknn-toolkit2-master/rknpu2/runtime/Linux/librknn_api/aarch64位置，在进行板端推理的C/C++ demo编译时应该链接到这个动态链接库，并且把这个库提前放到板端系统的LD_LIBRARTY_PATH路径中。

此外，对于模型上板推理的C/C++ demo运行，除了以上的NPU驱动以及NPU运行时支持动态链接库librknnrt.ko，可能还需要其他的多媒体与硬件加速库：

RGA (Rockchip Graphics Architecture)：用于硬件加速的图像缩放、裁剪、格式转换（如从摄像头拿到的 YUV 转为 NPU 需要的 RGB）。需要 librga.so 库文件及其头文件。

MPP (Media Process Platform)：用于进行硬件编解码（H.264/H.265），需要 librockchip_mpp.so。

至此，在瑞芯微平台上进行NPU开发的Python、C/C++交叉编译环境以及板端运行环境就已经准备好了。接下来通过Model Zoo中的Yolov5 demo对环境和NPU开发的流程进行总结。

基于Model Zoo中的YOLOv5进行上板测试

在前面已经下载的model zoo的仓库rknn_model_zoo-main的examples中，包含有多个已经在瑞芯微平台上适配好的模型案例，经过简单修改编译后即可上板运行测试。整个流程可以分为两个步骤：模型转换和板端C/C++ demo编译。

模型转换

在examples/yolov5/model目录下，执行download_model.sh，这个脚本的功能就是从指定的网络地址上下载一个onnx的yolov5s模型，所以这一步如果自己有已经训练好的yolov5s模型，完全可以使用自己训练的模型来替代。

接下来在examples/yolov5/python目录下，执行convert.sh脚本来进行模型转换（onnx->rknn）的动作。convert.sh脚本中指定了数据集描述文件路径DATASET_PATH和模型转换输出文件路径DEFAULT_RKNN_PATH，有必要的话可以对这两个值进行修改。然后执行python convert.py ../model/yolov5s_relu.onnx rk3588进行模型转换，转换后的模型会放到DEFAULT_RKNN_PATH所指定的路径中（以rknn为后缀）。

至此上板运行的模型文件就转换好了。

C/C++推理demo

在rknn_model_zoo-main目录下有两个build脚本文件：build-linux.sh和build-android.sh，分别用于针对板端的Linux和Android环境编译C/C++推理demo。此处以RK3588的Debian Linux环境为例，所以首先修改build-linux.sh，在最前面增加交叉编译工具链的路径：

然后调用build-linux.sh脚本进行yolov5板端推理demo程序的编译：./build-linux.sh -t rk3588 -a aarch64 -d yolov5 -b Release。build-linux.sh实际上会跳转到examples/yolov5/cpp/目录下，找到其中的CMakeLists.txt，调用cmake来执行完整的编译动作。

build-linux.sh的参数说明如下：

build-linux.sh执行完成后会在rknn_model_zoo-main目录下生成一个install目录，其中包含了demo在板端运行所需要的所有文件：demo可执行程序，运行时依赖库librknnrt.so，板端rknn模型文件，测试图片文件。所以只需要把这个install目录打包后上传到板端执行其中的demo程序即可：