RK3588芯片NPU的使用：Ubuntu 22.04安装RKNN SDK V2.3.0环境运行YOLOv5目标检测模型（万字详述）
本文的目标
本文将详细介绍在Ubuntu 22.04系统环境下，如何为搭载RK3588芯片的安卓开发板配置RKNN SDK V2.3.0开发环境，并实现通过adb工具在开发板上运行基于NPU加速的YOLOv5目标检测模型。
是不是很兴奋？那咱们开始。
开发环境说明
- 主机系统：Ubuntu 22.04 LTS
- 目标设备：搭载RK3588芯片的安卓开发板
- 核心工具：rknn-toolkit2、rknn_model_zoo、ADB调试工具
rknn-toolkit2简介
瑞芯微的NPU工具集调整后放到新的仓库，名曰rknn-toolkit2，它包括toolkit2和toolkit-lit2，以及rknpu2。完全克隆要3GB的样子。下面说说这三个库都是干什么的。
1.RKNN-Toolkit2：
- 1、模型转换：支持将主流深度学习框架（如TensorFlow、PyTorch、ONNX等）的模型转换为Rockchip专用的RKNN格式，适配其NPU硬件
- 2、量化与优化：提供模型量化（如非对称8位量化）、混合量化功能，以提升推理效率并减少内存占用
- 3、PC端推理仿真：可在PC上模拟NPU运行RKNN模型，进行性能评估和内存分析
- 4、加密与部署：支持模型加密，确保部署安全性，并可通过网络分发模型到开发板
适用场景：主要用于开发阶段的模型转换、调试和性能优化，运行环境为PC（x86/arm64）
2.RKNN-Toolkit-Lite2
- 1、嵌入式部署：专为开发板设计，提供Python接口简化RKNN模型的加载和推理，无需复杂编译
- 2、轻量化运行：相比RKNN-Toolkit2，移除了模型转换和性能评估功能，仅保留推理接口，适合资源受限的嵌入式环境
- 3、多核调度：支持通过core_mask参数配置NPU核心的调度模式（如单核或多核并行）
适用场景：直接在Rockchip开发板（如RK3588）上运行Python脚本进行模型推理，适用于终端应用部署
3.RKNPU2
- 1、硬件加速：Rockchip NPU（神经网络处理单元）的软件栈核心，包含驱动和运行时库，直接调用NPU硬件加速推理
- 2、底层API支持：提供C/C++接口（RKNN Runtime），与RKNN-Toolkit2生成的模型对接，实现高效推理
- 3、跨平台兼容：支持RK356x、RK3588等系列芯片，适配多种AI应用场景（如计算机视觉、自然语言处理）
适用场景：需高性能推理的嵌入式系统，通常与RKNN-Toolkit2或Lite2配合使用
通常的开发流程：
PC端：使用RKNN-Toolkit2转换和优化模型。
板端：通过RKNN-Toolkit-Lite2（Python）或RKNPU2的C API加载模型并调用NPU加速。
rknn-toolkit2安装
1. Clone rknnkit2源码库
# 下载 RKNN-Toolkit2 仓库
git clone https://github.com/airockchip/rknn-toolkit2.git --depth 1
# 注意：
# 1.参数 --depth 1 表示只克隆最近一次 commit
# 2.如果遇到 git clone 失败的情况，也可以直接在 github 中下载压缩包到本地，然后解压至该目录
我是用了大概两个时辰才全部clone完成。要心里有个准备。
目录结构如下：
├── rknn-toolkit2
│ ├── doc
│ ├── rknn-toolkit2
│ │ ├── packages
│ │ ├── docker
│ │ └── ...
│ ├── rknn-toolkit-lite2
│ │ ├── packages
│ │ ├── docker
│ │ └── ...
│ ├── rknpu2
│ │ ├── runtime
│ │ └── ...
│ └── ...
2、安装 RKNN-Toolkit2 环境
rknn-toolkit2目前只支持在Ubuntu系统下使用，推荐的python版本是3.8。条件也算是很苛刻了。
就操作系统而言，我们有以下几个选择：
1、Ubuntu的开发电脑：我就有一台老爷机，今天用的就是它；
2、docker：这个最建议使用，因为镜像中环境已经搭建好，拿来就用，后面我会尝试使用；
3、WSL：windows中可以用它安装，后面有时间我也会尝试一下；
4、虚拟机：请参考第一条。
就Python版本而言，这边建议用miniforge创建新的 Python 3.8 环境。那么就开始吧。
2.1 下载 miniforge 安装包
wget -c https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
通过以下命令安装 miniforge：
chmod 777 Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh
执行命令确认安装是否成功：
$ source /home/linc/miniforge3/bin/activate
$ conda -V
conda 24.11.3
通过以下命令创建名称为 toolkit2 的 Python 3.8 环境：
conda create -n toolkit2 python=3.8
过程中会让你确认下载安装其他依赖，直到出现下面内容：
Proceed ([y]/n)? y
Downloading and Extracting Packages:
Preparing transaction: done
Verifying transaction: done
Executing transaction: done
#
# To activate this environment, use
#
# $ conda activate toolkit2
#
# To deactivate an active environment, use
#
# $ conda deactivate
激活 toolkit2 环境，后续将在此环境中安装 RKNN-Toolkit2：
(base) linc:~/workplace/github/ai$ conda activate toolkit2
(toolkit2) linc:~/workplace/github/ai$
2.2 安装rknn-toolkit2
我选择通过pip源安装：
pip install rknn-toolkit2 -i https://pypi.org/simple
# 如果已安装 RKNN-Toolkit2，可通过以下命令升级 RKNN-Toolkit2
pip install rknn-toolkit2 -i https://pypi.org/simple --upgrade
大概一柱香或者两柱香的时间（torch和cuda相关库很大），安装完成。
验证安装是否完成：
执行以下命令，若没有报错，则代表 RKNN-Toolkit2 环境安装成功。
# 进入 Python 交互模式
python
# 导入 RKNN 类
from rknn.api import RKNN
至此，toolkit2环境算是安装完成。
安装编译工具
1.安装 CMake
在计算机的终端中，执行以下命令：
# 更新包列表
sudo apt update
# 安装 cmake
sudo apt install cmake
2.安装编译器
确认下开发板的系统架构：
$ adb shell getprop ro.product.cpu.abi
arm64-v8a
安装NDK
$ wget -c https://dl.google.com/android/repository/android-ndk-r19c-linux-x86_64.zip
预计一炷香的时间下载完毕，解压到项目路径下，比如：
Projects
├── rknn-toolkit2
├── rknn_model_zoo
└── android-ndk-r19c # 此路径在后面编译 RKNN C Demo 时会用到
3.确认开发板RKNPU2环境
通常来说，我们购置开发板后rknpu2的环境已经配置好。我们只需要确认一下就好。
RKNN-Toolkit2 的连板调试功能要求板端已安装 RKNPU2 环境，并且启动rknn_server 服务。以下是RKNPU2 环境中的两个基本概念：
RKNN Server：一个运行在开发板上的后台代理服务。该服务的主要功能是调用板端 Runtime 对应的接口处理计算机通过USB传输过来的数据，并将处理结果返回给计算机。
RKNPU2 Runtime 库（librknnrt.so）：主要职责是负责在系统中加载 RKNN 模型，并通过调用专用的神经处理单元（NPU）执行 RKNN 模型的推理操作。
如果板端没有安装 RKNN Server 和 Runtime 库，或者 RKNN Server 和 Runtime 库的版本不一致，都需要重新安装 RKNPU2 环境。（注意：1. 若使用动态维度输入的 RKNN 模型，则要求 RKNN Server 和Runtime 库版本 >= 1.5.0。2. 要保证 RKNN Server 、Runtime 库的版本、RKNN-Toolkit2 的版本是一致的，建议都安装最新的版本）。
如果能够启动 rknn_server 服务，则代表板端已经安装 RKNPU2 环境。
# 有线连接开发板与PC
# 或者无线连接也可以
# 进入板端
adb shell
# 启动 rknn_server
su
setenforce 0
/vendor/bin/rknn_server &
如果出现以下输出信息，则代表启动 rknn_server 服务成功，即已经安装 RKNPU2 环境。
start rknn server, version: x.x.x
运行示例程序运行yolov5目标识别
1.RKNN Model Zoo 介绍
RKNN Model Zoo 提供了示例代码，旨在帮助用户快速在 Rockchip 的开发板上运行各种常用模型，工程的目录结构如下：
rknn_model_zoo
├── 3rdparty # 第三方库
├── datasets # 数据集
├── examples # 示例代码
├── utils # 常用方法，如文件操作，画图等
├── build-android.sh # 用于目标为 Android 系统开发板的编译脚本
├── build-linux.sh # 用于目标为Linux 系统开发板的编译脚本
└── ...
examples 目录包括了一些常用模型的示例，例如 MobileNet 和 YOLO 等。每个模型示例提供了Python 和 C/C++ 两个版本的示例代码。以 YOLOv5 模型为例，其目录结构如下：
rknn_model_zoo
├── examples
│ └── yolov5
│├── cpp # C/C++ 版本的示例代码
│├── model # 模型、测试图片等文件
│├── python # 模型转换脚本和Python版本的示例代码
│└── README.md
└── ...
2.RKNN C Demo 运行yolov5目标识别
不同的芯片都有相应的方法，需要按照目录下 README.md 中的步骤运行。
2.1 准备模型
进入 rknn_model_zoo/examples/yolov5/model 目录，运行 download_model.sh 脚本，该脚本将下载一个可用的YOLOv5 ONNX 模型，并存放在当前 model 目录下，参考命令如下：
# 进入 rknn_model_zoo/examples/yolov5/model 目录
cd rknn_model_zoo/examples/yolov5/model
# 运行 download_model.sh 脚本，下载 yolov5 onnx 模型
# 例如，下载好的 onnx 模型存放路径为 model/yolov5s_relu.onnx
./download_model.sh
2.2 模型转换
进入 rknn_model_zoo/examples/yolov5/python 目录，运行 convert.py 脚本，该脚本将原始的 ONNX 模型转成RKNN 模型，参考命令如下：
# 进入 rknn_model_zoo/examples/yolov5/python 目录
cd rknn_model_zoo/examples/yolov5/python
# 运行 convert.py 脚本，将原始的 ONNX 模型转成 RKNN 模型
# 用法: python convert.py model_path [rk3566|rk3588|rk3562] [i8/fp] [output_path]
python convert.py ../model/yolov5s_relu.onnx rk3588 i8 ../model/yolov5s_relu.rknn
运行结果如下：
I rknn-toolkit2 version: 2.3.0
--> Config model
done
--> Loading model
I Loading : 100%|██████████████████████████████████████████████| 121/121 [00:00<00:00, 11908.93it/s]
done
--> Building model
I OpFusing 0: 100%|██████████████████████████████████████████████| 100/100 [00:00<00:00, 124.13it/s]
I OpFusing 1 : 100%|██████████████████████████████████████████████| 100/100 [00:01<00:00, 63.79it/s]
I OpFusing 2 : 100%|██████████████████████████████████████████████| 100/100 [00:01<00:00, 63.69it/s]
I GraphPreparing : 100%|████████████████████████████████████████| 149/149 [00:00<00:00, 5790.34it/s]
I Quantizating : 100%|████████████████████████████████████████████| 149/149 [00:12<00:00, 11.74it/s]
I rknn building ...
I rknn building done.
done
--> Export rknn model
done
2.3 编译
RK3588 安卓平台，使用 rknn_model_zoo 目录下的 build-android.sh 脚本进行编译。在运行 build-android.sh 脚本之前，需要指定编译器的路ANDROID_NDK_PATH 为本地的 NDK 编译器路径。在 build-android.sh 脚本中，需要加入以下命令：
# 添加到 build-android.sh 脚本的开头位置即可
ANDROID_NDK_PATH=YOUR_PATH/android-ndk-r19c
在 rknn_model_zoo 目录下，运行 build-android.sh 脚本，参考命令如下：
# 运行 build-android.sh 脚本
# 用法:./build-android.sh -t -a -d [-b ] [-m]
# -t : target (rk356x/rk3588) # 平台类型
# -a : arch (arm64-v8a/armeabi-v7a) # 板端系统架构
# -d : demo name # 对应 examples 目录下子文件夹的名称，如yolov5、mobilenet
# -b : build_type (Debug/Release)
# -m : enable address sanitizer, build_type need set to Debug
./build-android.sh -t rk3588 -a arm64-v8a -d yolov5
结果如下：
$ ./build-android.sh -t rk3588 -a arm64-v8a -d yolov5
bash: ./build-android.sh: Permission denied
# 需要给脚本执行权限
$ chmod +x build-android.sh
$ ./build-android.sh -t rk3588 -a arm64-v8a -d yolov5
./build-android.sh -t rk3588 -a arm64-v8a -d yolov5
===================================
BUILD_DEMO_NAME=yolov5
BUILD_DEMO_PATH=examples/yolov5/cpp
TARGET_SOC=rk3588
TARGET_ARCH=arm64-v8a
BUILD_TYPE=Release
ENABLE_ASAN=OFF
DISABLE_RGA=OFF
DISABLE_LIBJPEG=OFF
100%] Built target audioutils
Install the project...
-- Install configuration: "Release"
-- Installing: /home/rknn_model_zoo/install/rk3588_android_arm64-v8a/rknn_yolov5_demo/./rknn_yolov5_demo
-- Installing: /home/rknn_model_zoo/install/rk3588_android_arm64-v8a/rknn_yolov5_demo/./model/bus.jpg
-- Installing: /home/rknn_model_zoo/install/rk3588_android_arm64-v8a/rknn_yolov5_demo/./model/coco_80_labels_list.txt
-- Installing: /home/rknn_model_zoo/install/rk3588_android_arm64-v8a/rknn_yolov5_demo/model/yolov5s_relu.rknn
-- Installing: /home/rknn_model_zoo/install/rk3588_android_arm64-v8a/rknn_yolov5_demo/lib/librknnrt.so
-- Installing: /home/rknn_model_zoo/install/rk3588_android_arm64-v8a/rknn_yolov5_demo/lib/librga.so
2.4 推送文件到开发板
编译完成后，会在 rknn_model_zoo 目录下产生 install 文件夹， 其中有编译好的可执行文件，以及测试图片等相关文件。参考目录结构如下：
install/
└── rk3588_android_arm64-v8a
└── rknn_yolov5_demo
├── lib
│ ├── librga.so
│ └── librknnrt.so
├── model
│ ├── bus.jpg
│ ├── coco_80_labels_list.txt
│ └── yolov5s_relu.rknn
└── rknn_yolov5_demo
在rknn_model_zoo目录下，执行以下操作：
$ adb connect 192.168.1.4:43225
connected to 192.168.1.4:43225
# 切换到 root 用户权限
adb root
# 推送整个 rknn_yolov5_demo 文件夹到板端
# 注：rknn_yolov5_demo 文件夹下有一个同名的可执行文件 rknn_yolov5_demo
# 注：使用不同的模型和平台时，建议直接在 install 下找对应的路径
adb push install/rk3588_android_arm64-v8a/rknn_yolov5_demo /data/
结果：
$ adb push install/rk3588_android_arm64-v8a/rknn_yolov5_demo /data/
install/rk3588_android_arm64-v8a/rknn_yolov5_demo/: 6 files pushed, 0 skipped. 6.1 MB/s (19310163 bytes in 3.011s)
2.5 开发板上运行demo
执行如下命令：
adb shell
# 进入开发板中rknn_yolov5_demo目录
cd /data/rknn_yolov5_demo/
# 设置依赖库环境
export LD_LIBRARY_PATH=./lib
# 运行可执行文件
# 用法: ./rknn_yolov5_demo
./rknn_yolov5_demo model/yolov5s_relu.rknn model/bus.jpg
执行结果如下，速度非常快：
rk3588_s:/data/rknn_yolov5_demo # ./rknn_yolov5_demo model/yolov5s_relu.rknn model/bus.jpg
load lable ./model/coco_80_labels_list.txt
model input num: 1, output num: 3
input tensors:
index=0, name=images, n_dims=4, dims=[1, 640, 640, 3], n_elems=1228800, size=1228800, fmt=NHWC, type=INT8, qnt_type=AFFINE, zp=-128, scale=0.003922
output tensors:
index=0, name=output0, n_dims=4, dims=[1, 255, 80, 80], n_elems=1632000, size=1632000, fmt=NCHW, type=INT8, qnt_type=AFFINE, zp=-128, scale=0.003922
index=1, name=286, n_dims=4, dims=[1, 255, 40, 40], n_elems=408000, size=408000, fmt=NCHW, type=INT8, qnt_type=AFFINE, zp=-128, scale=0.003922
index=2, name=288, n_dims=4, dims=[1, 255, 20, 20], n_elems=102000, size=102000, fmt=NCHW, type=INT8, qnt_type=AFFINE, zp=-128, scale=0.003922
model is NHWC input fmt
model input height=640, width=640, channel=3
origin size=640x640 crop size=640x640
input image: 640 x 640, subsampling: 4:2:0, colorspace: YCbCr, orientation: 1
scale=1.000000 dst_box=(0 0 639 639) allow_slight_change=1 _left_offset=0 _top_offset=0 padding_w=0 padding_h=0
rga_api version 1.10.1_[0]
rknn_run
person @ (209 243 286 510) 0.880
person @ (479 238 560 526) 0.871
person @ (109 238 231 534) 0.840
bus @ (91 129 555 464) 0.692
person @ (79 353 121 517) 0.301
write_image path: out.png width=640 height=640 channel=3 data=0xb40000787775e000
2.6 查看结果
输出图片保存路径为 rknn_yolov5_demo/out.png ，通过 adb 工具从板端拉取到本地查看，在本地计算机的终端中，执行以下命令：
# 拉取到本地当前目录
adb pull /data/rknn_yolov5_demo/out.png .
小结
本文详细介绍了在 Ubuntu 22.04 系统下搭建 RKNN SDK V2.3.0 开发环境的完整流程，并实现了在 RK3588 开发板（Android 系统） 上通过 NPU 加速 运行 YOLOv5 目标检测模型（没错，本人搞了一天）。
核心要点回顾
- 环境准备：确保主机（Ubuntu 22.04）与 RK3588 开发板正确连接，并配置好 ADB 调试工具。
- RKNN SDK 安装：安装瑞芯微官方提供的 RKNN 工具链，为 NPU 推理提供软件支持。
- 模型转换与部署：将 YOLOv5 模型转换为 RKNN 格式，并部署到开发板运行。
- 性能对比：相比纯 CPU 推理，NPU 加速显著提升了目标检测的推理速度，适用于实时性要求较高的 AI 应用场景。
适用场景
- 边缘计算：在嵌入式设备（如 RK3588 开发板）上高效运行 AI 模型。
- 计算机视觉：目标检测、图像分类等 AI 推理任务。
- 低功耗高性能需求：利用 NPU 加速，降低 CPU 负载，提升能效比。
通过本教程，大家可以快速掌握 RK3588 NPU 的开发流程，为后续的 AI 应用开发奠定基础。
