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服务（如果是⾮协处理器模式，处理PC的连板推理请求）

rknn3_transfer_proxy

板端

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

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，协处理器模式，主控SOC是RK3588（Lubancat-5），Lubancat-5通过PCIe高速接口连接RK1820/RK1828协处理器。

7.1. 环境准备

7.1.1. PCIe驱动安装

如果Lubancat-5烧录的是旧系统（20260828日期以前发布的镜像），需要编译内核模块，然后安装驱动。 而最新的镜像已经内建驱动，则不需要手动安装驱动模块（最新镜像已经更新pcie-rkep）。

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

获取到pcie-rkep.ko内核模块后，传输到板卡（通过ssh或者adb等方式），然后复制到系统/lib/modules/目录下，或者执行手动加载测试。

1
2
3
4
5
6
# 查看内核版本
cat@lubancat:~$ uname -r
6.1.99

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

7.1.2. 硬件连接

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

broken

Lubancat-5设备上电，烧录的是Debian12系统，登录终端查看设备：

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

7.1.3. 固件安装

可以从配套网盘获取RK1820/RK1828 M2模组预编译软件安装包（rknn3_rk182x_m2_vx.x.x_installer_arm64.tgz等）, 然后传输到板卡解压后安装：

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

sudo ./install.sh

安装成功后，重启Lubancat-5设备，rknn3.service将检测设备，下载固件，启动rknn3_transfer_proxy等，正常启动后服务状态：

 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.2. 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中的应⽤。

7.2.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

7.2.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

7.2.3. 卸载app portal

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