7. RKNN3

RKNN3 是瑞芯微⾯向 RK1820/RK1828协处理器 与 RK3572 SoC 的AI模型部署开发套件， 提供从模型转换、量化评估到板端部署的完整⼯具链，⽀持 CNN/LLM/MLLM 等多种模型类型在NPU上的⾼效推理。

RKNN3 SDK中有多个组件，组件使用需要保证版本⼀致，否则可能 出现模型转换正常但板端⽆法运行、推理结果异常等问题。

组件

运行位置

功能描述

RKNN3-Toolkit

PC

模型转换、量化、评估等

RKNN3 Runtime

板端

模型执⾏、内存管理、多核调度

RKNN3-Toolkit Lite

板端

是板端Python推理接⼝，对RKNN3 Runtime（C API）做Python封装

rkllm3-server

板端

OpenAI兼容API服务, 大模型服务化部署

rknn3-server

板端

处理来⾃PC的连板推理请求，管理RK3572NPU资源（⾮协处理器模式）

rknn3_transfer_proxy

板端

主控SoC与RK182X协处理器之间的通信代理，协处理器模式下

RKNN3经典开发流程（CNN/VIT模型）和RKNN2类似，可以简单参考下前面章节。

broken

  • 模型转换 , 在PC端使⽤RKNN3-Toolkit完成原始模型的配置，构建，量化，转换等等。

  • 模型评估 , 在PC端通过USB或⽹络（adb connect）连接开发板，使⽤RKNN3-Toolkit的Python API进行连板推理评估，精度分析，性能分析等等。

  • 板端部署 , 在板端中使⽤RKNN3 Runtime的C API推理。

LLM模型的开发流程与CNN模型相比，主要体现先对HuggingFace模型处理导出onnx模型，以及板端部署接口。

RKNN3 SDK⽀持两种模式：

协处理器模式（RK182X） ：主控SoC（如RK3588/RK3576）通过 PCIe/USB/Ethernet与RK1820/RK1828协处理器互联， 应⽤运行在主控SoC上，通过RKNN3 API控制协处理器执⾏AI推理。

⾮协处理器模式（RK3572） ：RK3572 SoC 集成⾼性能 NPU，应⽤直接运行在RK3572上，通过RKNN3 API控制本地NPU执⾏AI推理。

RKNN3 SDK更多的说明和使用详情请参考 RKNN3 SDK 文档 。

重要

目前教程测试RKNN3， 协处理器模式 ，主控SOC是RK3588（Lubancat-5），Lubancat-5通过PCIe高速接口连接RK1820/RK1828协处理器。

7.1. 板端环境准备

7.1.1. 硬件连接

测试使用RK1820/RK1828 M.2模组，在断电情况下，将其连接到Lubancat-5设备上，RK182X单独12V供电。

broken

7.1.2. PCIe驱动安装

如果Lubancat-5烧录的是旧系统，需要编译内核模块，可以选择直接使用现有的pcie-rkep.ko模块，或者手动板端编译内核模块。 最新的镜像（20260902日期以后发布的镜像）已经内建了更新的pcie-rkep，无需手动安装构建。

1、使用现有KO模块

pcie-rkep.ko模块请从 网盘资料 (提取码：hslu)获取， 在 鲁班猫_瑞芯微系...>1-野火开源图书...>配套代码>嵌入式AI应用开实战指南>AI教程相关源文件>rknn3 目录下,请根据具体内核版本选择。

2、板端编译内核模块

从 网盘资料 (提取码：hslu)获取pcie-rkep.zip文件（路径和前面ko模块路径一致），然后传输到板卡。

1
2
3
4
5
6
7
8
9
# 解压pcie-rkep.zip
unzip pcie-rkep.zip

# 进入pcie-rkep目录
cd pcie-rkep

# 修改Makefile中KERNELDIR:=/usr/src/linux-headers-6.1.118路径（这里以Ubuntu24.04系统为例）

# 执行make命令编译内核模块，将在pcie-rkep目录下生成 pcie-rkep.ko内核模块

获取到pcie-rkep.ko内核模块后，传输到板卡（通过ssh或者adb等方式），然后复制到系统/lib/modules/下任意文件中。

1
2
# 复制pcie-rkep.ko到/lib/modules/，如果一些系统没有/lib/modules/就创建
sudo mkdir -p /lib/modules/

7.1.3. 固件安装

可以从配套网盘或者 RK1820/RK1828 固件 下载固件，选择RK1820/RK1828 M2模组预编译软件安装包（rknn3_rk182x_m2_${VERSION}_installer_arm64.tgz）,然后传输到板卡（通过scp或者adb命令）解压后安装：

1
2
3
4
mkdir tmp && cd tmp
tar -xzf ../rknn3_rk182x_m2_v1.1.0_installer_arm64.tgz

sudo ./install.sh

执行install.sh脚本安装成功后，重启Lubancat-5设备，上电启动后系统的rknn3.service将检测设备， 下载固件，启动rknn3_transfer_proxy等。

pcie-rkep驱动正常加载后：

1
2
3
4
5
6
cat@lubancat:~# lspci
00:00.0 PCI bridge: Fuzhou Rockchip Electronics Co., Ltd Device 3588 (rev 01)
01:00.0 Processing accelerators: Fuzhou Rockchip Electronics Co., Ltd Device 182a (rev 01)

cat@lubancat:~# ls -al /dev/pcie-rkep-*
crw------- 1 root root 10, 120 Aug 28 09:37 /dev/pcie-rkep-0000:01:00.0

rknn3.service服务状态：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
cat@lubancat:~$ sudo systemctl status rknn3
● rknn3.service - rknn3 runtime service
    Loaded: loaded (/lib/systemd/system/rknn3.service; enabled; preset: enable>
    Active: active (running) since Tue 2026-04-28 04:25:13 CST; 3 months 30 da>
    Process: 534 ExecStart=/bin/rknn3_startup start (code=exited, status=0/SUCC>
Main PID: 628 (rknn3_transfer_)
    Tasks: 6 (limit: 9174)
    Memory: 7.0M
        CPU: 569ms
    CGroup: /system.slice/rknn3.service
            ├─628 /bin/rknn3_transfer_proxy
            └─688 rknn3_transfer_proxy_b98e6c51 -s 0000:01:00.0

Aug 27 09:37:47 lubancat rknn3_startup[784]: [31B blob data]
Aug 27 09:37:47 lubancat rknn3_startup[784]: [31B blob data]
Aug 27 09:37:47 lubancat rknn3_startup[784]: [31B blob data]
Aug 27 09:37:47 lubancat rknn3_startup[784]: [32B blob data]
Aug 27 09:37:47 lubancat rknn3_startup[784]: Start to write node4_os at 0xa000..
Aug 27 09:37:47 lubancat rknn3_startup[784]: Write node4_os... (100%)
Aug 27 09:37:47 lubancat rknn3_startup[784]: Reseting device...
Aug 27 09:37:47 lubancat rknn3_startup[784]: Reseting device...OK
Aug 27 09:37:47 lubancat rknn3_startup[784]: Downloading firmware OK

使用rknn-smi查看RK1820/RK1828 状态：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
cat@lubancat:~$ sudo rknn-smi info
[   42.652638] pcie-rkep 0000:01:00.0: update magic=524b4550, ver=2
+------------------------+---------------+---------------+----------------------+
| rknn-smi      Version: 1.3.0                                                  |
+========================+===============+===============+======================+
| Device        Status   | Health        | Power(mW)     | Npu(%)               |
| Chip          Name     | Bus-Id        | Temp(C)       | Memory-Usage(MB)     |
+========================+===============+===============+======================+
| 0             Online   | OK            | NA            | 0                    |
| 0             RK1828   | 0000:01:00.0  | 34            | 32   / 5120          |
+========================+===============+===============+======================+


cat@lubancat:~$ sudo rknn-smi info -l
Device Count                  : 1
    Device ID                     : 0
    Communication mode            : PCIe
    Product Name                  : RM1828MC0-F
    Serial Number                 : R2DMA261600284
    Chip Count                    : 1
    Chip ID                       : 0
    Chip Name                     : RK1828

查看软件版本：

1
2
3
4
5
6
7
cat@lubancat:~$ sudo rknn-smi -v
rknn-smi version              : 1.3.0
PCIe driver version           : 3.3.0
RC chips connect version      : 3.3.2
EP chips connect version      : 0.0.2
PCIe Device 0 firmware version: 1.1.0
rknn3 API version             : 1.1.0

7.1.4. 简单模型测试

从网盘获取一个简单模型（教程测试qwen3-0.6B），然后直接使用rknn3_session_test测试:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
cat@lubancat:~$ rknn3_session_test Qwen3-0.6B.rknn Qwen3-0.6B.weight Qwen3-0.6B.tokenizer.gguf \
            Qwen3-0.6B.embed.bin 256 256 0xff
*******************************NEW TEST**********************************
W RKNNAPI(25657): Weight sync chunk size resolved to 2097152 bytes
model input num: 9, output num: 1
output_callback output tensor[0]: output
llama_model_loader: loaded meta data with 25 key-value pairs and 0 tensors from Qwen3-0.6B.tokenizer.gguf
(version GGUF V3 (latest))
# 省略.....................

Performance Statistics:
-----------------------------------------------------------------------------------------
Stage      | Total Time (ms)  | Tokens   | Time per Token (ms)  | Tokens per Second
-----------------------------------------------------------------------------------------
Prefill    | 29.62            | 20       | 1.48                 | 675.27
Generate   | 1614.29          | 255      | 6.33                 | 157.96
-----------------------------------------------------------------------------------------

*******************************END TEST**********************************

7.1.5. App Portal使用

Lubancat-5的镜像使用debian/Ubuntu,可以使用瑞芯微官方提供的App Portal工具管理RK1820/RK1828板端的应⽤软件。

app-portal有CLI和网页两个版本，网页版本基于命令行版本。

app-portal命令行包含 CLI、共享管理核⼼和当次catalog，不依赖 FastAPI 或 Uvicorn。

app-portal-web 是基于命令行版本并包含Web模块、静态资源和systemd服务，额外依赖 FastAPI、Uvicorn等。 安装⽹⻚包后服务⽴即运⾏并默认开机⾃启，但不会⾃动安装catalog中的应⽤。

1、 安装app portal

请从 网盘资料 (提取码：hslu)获取app-portal相关deb包， 在目录 鲁班猫_瑞芯微系...>1-野火开源图书...>配套代码>嵌入式AI应用开实战指南>AI教程相关源文件>app-portal 下。

获取 app-portal_${VERSION}_arm64.deb 或者 app-portal-web_${VERSION}_arm64.deb后，将其传输到板卡。

教程使用Lubancat-5 Debian12系统，测试app-portal命令行版本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
sudo apt-get update
sudo apt-get install python3-yaml

# 安装
sudo apt-get install --reinstall --yes ./app-portal_0.4.1_arm64.deb
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
Note, selecting 'app-portal' instead of './app-portal_0.4.1_arm64.deb'
Suggested packages:
app-portal-web
The following NEW packages will be installed:
app-portal
0 upgraded, 1 newly installed, 0 to remove and 6 not upgraded.
Need to get 0 B/90.5 kB of archives.
After this operation, 562 kB of additional disk space will be used.
Get:1 /home/cat/app-portal_0.4.1_arm64.deb app-portal arm64 0.4.1 [90.5 kB]
Selecting previously unselected package app-portal.
(Reading database ... 47546 files and directories currently installed.)
Preparing to unpack .../cat/app-portal_0.4.1_arm64.deb ...
Unpacking app-portal (0.4.1) ...
Setting up app-portal (0.4.1) ...

# 或者sudo dpkg -i app-portal_0.4.1_arm64.deb

# 更新app-portal
sudo app-portal update --cli

2、 app portal命令使用

使用app-portal查看相关命令：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
app-portal -h
usage: app-portal [-h] [--catalog CATALOG] [--json] {list,check,status,install,
update,start,stop,restart,uninstall,tree-hash,runtime-version,runtime-update} ...

YAML-driven board application delivery and lifecycle manager.

positional arguments:
{list,check,status,install,update,start,stop,restart,uninstall,tree-hash,runtime-version,runtime-update}
    list                list applications and install packages
    check               validate catalog syntax and contract
    status              show deployed application state
    install             download, install, and deploy an application
    update              update App Portal itself
    start               start a deployed application
    stop                stop a deployed application
    restart             restart a deployed application
    uninstall           stop and uninstall an application
    tree-hash           calculate a directory resource tree_sha256
    runtime-version     scan the local RKNN3 API version
    runtime-update      list or install RKNN3 Runtime releases

options:
-h, --help            show this help message and exit
--catalog CATALOG, -c CATALOG
                        catalog YAML path (default: /etc/app-portal/catalog.yaml)
--json                emit machine-readable JSON

查看相关安装包：

1
2
3
4
5
6
7
8
9
cat@lubancat:~$ sudo app-portal list
multistream-detect      install=apt-deb packages=package:apt-deb
clawchips       install=pip-whl packages=rknn3-toolkit:pip-whl,rk-claw-server:pip-whl,nanobot:pip-whl
ai-media-base   install=apt-deb packages=ai-media-base:apt-deb,rknn-toolkit-lite2:pip-whl
llama-rknn3-server      install=apt-deb packages=package:apt-deb
ai-hub  install=apt-deb packages=package:apt-deb
multistream-event       install=apt-deb packages=package:apt-deb
multistream-vlm install=apt-deb packages=package:apt-deb
meeting install=apt-deb packages=package:apt-deb

查看或者更新RKNN3 Runtime版本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# CLI 可以列出最新版本制品
cat@lubancat:~$ sudo app-portal runtime-update list
installed: 1.1.0
selected: 1.1.0
m2      deb     rknn3-rk182x-m2_1.1.0_arm64.deb
m2      tgz     rknn3_rk182x_m2_v1.1.0_installer_arm64.tgz
sodimm  deb     rknn3-rk182x-sodimm_1.1.0_arm64.deb
sodimm  tgz     rknn3_rk182x_sodimm_v1.1.0_installer_arm64.tgz
sodimm-net      deb     rknn3-rk182x-sodimm-net_1.1.0_arm64.deb
sodimm-net      tgz     rknn3_rk182x_sodimm-net_v1.1.0_installer_arm64.tgz


# 列出全部发布版本
cat@lubancat:~$ sudo app-portal runtime-update list-all
installed: 1.1.0
1.1.0   RELEASE_V1.1.0
1.0.4   RELEASE_V1.0.4
1.0.0   RELEASE_V1.0.0


# 更新版本
sudo app-portal runtime-update --type m2
sudo app-portal runtime-update --version 1.1.0 --type m2

3、 卸载app portal

1
2
sudo apt-get purge app-portal-web app-portal
sudo apt-get autoremove

7.2. RKNN3 Toolkit（PC端）

RKNN3-Toolkit是模型转换核⼼⼯具，将ONNX模型转换为.rknn和.weight 格式，完成图优 化、多核拆分、量化、精度分析与可视化分析等功能。对于LLM/MLLM模型，需先通过Model Zoo相关脚本将模型转换为ONNX，再使⽤Toolkit转换为RKNN。

使用Conda创建环境，然后安装RKNN3-Toolkit，或者直接使用pip安装。

1
2
3
4
5
# 创建conda环境，python3.10版本
conda create -n toolkit3_1.1.0 python=3.10

# 激活环境
conda activate toolkit3_1.1.0

获取rknn3-toolkit的wheel包从 rknn3-toolkit ， 教程测试python3.10版本，下载rknn3_toolkit-{Version}-cp310-cp310-manylinux2014_x86_64.whl，然后安装：

1
2
3
4
5
# 安装依赖包
pip install -r requirements_cpxxx-x.x.x.txt

# 根据Python版本和处理器架构选择对应的wheel安装包
pip install rknn3_toolkit-1.1.0-cp310-cp310-manylinux2014_x86_64.whl

检查Toolkit安装结果:

1
2
(toolkit3_1.1.0) llh@llh:/xxx$ python -c "from rknn.api import RKNN; print('RKNN3 Toolkit import OK')"
RKNN3 Toolkit import OK