快速入门：怎么在 RK3588 上运行 CNN 模型

本指南使用 YOLO11n，完成 NPU 驱动检查 → Runtime 与 Toolkit Lite2 安装 → PC 模型转换 → C++ 编译部署 → 板端推理。模型运行在 RK3588 内置 NPU 上，通过 SSH/SCP 或板端本地终端操作。

#开始之前

项目	本文配置及实测环境
PC	Ubuntu 20.04.6 LTS，x86_64，Python 3.11
板卡	reComputer RK3588，aarch64
板端系统	Debian 12 / Armbian `26.08.0-trunk`
板端内核	`6.1.115-vendor-seeed-rk3588`
NPU 驱动	实测 `0.9.8`
工具版本	RKNN-Toolkit2 / Toolkit Lite2 `2.3.2`
Runtime	本文安装 `librknnrt.so 2.3.2`
示例	YOLO11n，640 × 640，INT8 量化
转换 / 编译目标	`rk3588` / `rk3588 + aarch64`

执行位置： “PC 执行”指 Ubuntu 开发机；“板端执行”指 SSH 登录后或板卡本地终端。将 BOARD_IP 和示例用户名 rk3588 替换为实际地址与账户。

若板端还没有开启 SSH，先在板卡本地执行：

bash

sudo apt update
sudo apt install openssh-server
sudo systemctl enable --now ssh
hostname -I

然后在 PC 登录，首次连接核对主机指纹，按提示输入账户密码：

bash

ssh rk3588@BOARD_IP

#1. 缺少 NPU 驱动时如何解决

#1.1 区分内核驱动与用户态软件

RK3588 的 NPU 驱动是内核中的 RKNPU，配置项为 CONFIG_ROCKCHIP_RKNPU。Runtime 的 .so 文件、Toolkit Lite2 的 Python wheel 都不能替代内核驱动。

#1.2 检查驱动、设备节点与负载

板端执行：

bash

uname -r
sudo dmesg | grep -i rknpu
sudo cat /sys/kernel/debug/rknpu/version
sudo cat /sys/kernel/debug/rknpu/load
ls -l /sys/class/drm/renderD*/device/driver

本机真实输出节选：

text

RKNPU driver: v0.9.8
NPU load:  Core0:  0%, Core1:  0%, Core2:  0%,

/sys/class/drm/renderD130/device/driver -> .../bus/platform/drivers/RKNPU

本机 NPU 节点为 renderD130，编号可能变化，应以 device/driver 指向 RKNPU 为准。

如果 debugfs 尚未挂载，可以先执行：

bash

mountpoint -q /sys/kernel/debug || sudo mount -t debugfs debugfs /sys/kernel/debug

挂载后重试，并结合启动日志和驱动绑定判断驱动状态。

本机内核配置检查：

bash

grep '^CONFIG_ROCKCHIP_RKNPU=' /boot/config-$(uname -r)

实际输出为：

text

CONFIG_ROCKCHIP_RKNPU=y

=y 代表编入内核，因此 lsmod 中没有 rknpu 并不代表缺少驱动。官方 RKNN SDK V2.3.2 快速入门建议 RKNPU 驱动版本不低于 0.9.2；本次 0.9.8 已完成推理验证。

#1.3 驱动缺失或需要更新时

本文使用 reComputer RK3588 配套 Seeed/Armbian 内核。若驱动检查已通过，可直接进入第 2 节，无需重装内核。

对同款、已配置 Seeed 软件源的系统，先查看内核与设备树软件包：

bash

sudo apt update
apt-cache policy linux-image-vendor-seeed-rk3588 linux-dtb-vendor-seeed-rk3588

确认两个包来自该板配套软件源且候选版本匹配后，安装/更新配套内核与设备树：

bash

sudo apt install --reinstall linux-image-vendor-seeed-rk3588 linux-dtb-vendor-seeed-rk3588
sudo reboot

重启会断开 SSH；重新登录后，按 1.2 节验证驱动。

若软件源没有这两个包，请使用本型号配套的厂商镜像或 BSP。自编内核时需启用 CONFIG_ROCKCHIP_RKNPU=y，并使用本板的 NPU 设备树配置。

#2. 安装及验证 Runtime 和 Toolkit Lite2

#2.1 三个组件的区别

组件	安装位置	主要职责
RKNN-Toolkit2	Ubuntu PC 的独立 Python 环境	ONNX 转换、量化，生成 `.rknn`
RKNN Runtime / `librknnrt.so`	RK3588 板端	提供 C/C++ API，加载模型并驱动 NPU 推理
RKNN-Toolkit-Lite2	RK3588 板端 Python 环境	提供 Python 推理 API，依赖板端 Runtime 和驱动

PC 使用 from rknn.api import RKNN；板端 Python 使用 from rknnlite.api import RKNNLite。Lite2 不提供模型转换功能，C++ 示例直接调用 Runtime。

本文在板端本地推理，无需启动 rknn_server。

#2.2 在 PC 获取固定版本的官方仓库

后续第 3、4 节复用这两个目录，只需在新工作目录克隆一次。

PC 执行：

bash

sudo apt update
sudo apt install git wget cmake make gcc g++ openssh-client
mkdir -p ~/RKNN2_Project
cd ~/RKNN2_Project

git clone https://github.com/airockchip/rknn-toolkit2.git
git -C rknn-toolkit2 checkout 59a913d172e7f5ff03c9076e2ec7b1b1288ffd08

git clone https://github.com/airockchip/rknn_model_zoo.git
git -C rknn_model_zoo checkout bad6c7334531becaf90a561988519b7bec34d0ab

以上是本次实测的提交，Model Zoo 对应 v2.3.2。固定代码与安装包，避免后续仓库更新导致命令路径改变。

#2.3 安装板端 Runtime

PC 执行：

bash

ssh rk3588@BOARD_IP 'mkdir -p ~/RKNN2_Project/packages'

scp ~/RKNN2_Project/rknn-toolkit2/rknpu2/runtime/Linux/librknn_api/aarch64/librknnrt.so \
  rk3588@BOARD_IP:~/RKNN2_Project/packages/

板端执行： 先保留可能存在的旧库，再安装新库。

bash

sudo apt update
sudo apt install binutils

if [ -e /usr/lib/librknnrt.so ]; then
  sudo cp -a /usr/lib/librknnrt.so "/usr/lib/librknnrt.so.bak-$(date +%Y%m%d-%H%M%S)"
fi
sudo install -m 0644 ~/RKNN2_Project/packages/librknnrt.so /usr/lib/librknnrt.so
sudo ldconfig
strings /usr/lib/librknnrt.so | grep 'librknnrt version'

本文软件包中的版本字符串为：

text

librknnrt version: 2.3.2 (429f97ae6b@2025-04-09T09:09:27)

Lite2 需要系统路径 /usr/lib/librknnrt.so；仅设置 Demo 目录的 LD_LIBRARY_PATH 不能替代此步骤。

#2.4 安装板端 Toolkit Lite2

本文板端 Debian 12 使用 Python 3.11，因此选 cp311 和 aarch64 wheel。

PC 执行：

bash

scp ~/RKNN2_Project/rknn-toolkit2/rknn-toolkit-lite2/packages/rknn_toolkit_lite2-2.3.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl \
  rk3588@BOARD_IP:~/RKNN2_Project/packages/

板端执行：

bash

sudo apt install python3.11-venv
python3 -m venv ~/venvs/rknn-lite2
source ~/venvs/rknn-lite2/bin/activate

python -m pip install \
  ~/RKNN2_Project/packages/rknn_toolkit_lite2-2.3.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
python -m pip check
python -c "from rknnlite.api import RKNNLite; print('RKNN Toolkit Lite2 import OK')"

两项检查的实测输出：

text

No broken requirements found.
RKNN Toolkit Lite2 import OK

若提示 ensurepip is not available，安装 python3.11-venv 后重新创建虚拟环境。第 4 节验证实际推理。

#3. 在 Ubuntu PC 配置 Toolkit 并转换 YOLO11n 模型

#3.1 创建 PC Python 3.11 环境

PC 执行： 以下给出新 PC 的 Miniforge 安装命令；已有 Conda 时，用现有 Conda 创建同名环境即可。

bash

mkdir -p ~/Downloads
cd ~/Downloads
wget -c https://github.com/conda-forge/miniforge/releases/download/25.3.0-1/Miniforge3-25.3.0-1-Linux-x86_64.sh
bash Miniforge3-25.3.0-1-Linux-x86_64.sh -b -p "$HOME/miniforge3"
source ~/miniforge3/etc/profile.d/conda.sh
conda create -n rknn2 python=3.11 -y
conda activate rknn2

每次新开 PC 终端，先执行 source ~/miniforge3/etc/profile.d/conda.sh 和 conda activate rknn2，再运行后续 Python 命令。

#3.2 安装 Toolkit2 2.3.2

PC 执行：

bash

cd ~/RKNN2_Project/rknn-toolkit2/rknn-toolkit2
python -m pip install \
  -r packages/x86_64/requirements_cp311-2.3.2.txt \
  packages/x86_64/rknn_toolkit2-2.3.2-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl \
  'onnx==1.16.1' 'protobuf==4.25.4'

python -m pip check
python -m pip show rknn-toolkit2
python -c "from rknn.api import RKNN; print('RKNN Toolkit2 import OK')"

实测使用 Python 3.11.14、Toolkit2 2.3.2、ONNX 1.16.1 和 protobuf 4.25.4，pip check 返回 No broken requirements found.。在独立环境中固定依赖版本，避免与其他项目冲突。

#3.3 下载官方适配的 YOLO11n

PC 执行：

bash

cd ~/RKNN2_Project/rknn_model_zoo/examples/yolo11/model
bash download_model.sh
ls -lh yolo11n.onnx

本次下载得到 yolo11n.onnx，大小为 10,527,859 字节。

使用 Rockchip 适配版 ONNX，其输出布局与示例的 C++ 后处理配套。自训模型请按 YOLO11 导出说明导出。

#3.4 转换为 RK3588 INT8 模型

PC 执行：

bash

conda activate rknn2
cd ~/RKNN2_Project/rknn_model_zoo
export PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}"
ls datasets/COCO/coco_subset_20.txt
ls datasets/COCO/subset

cd examples/yolo11/python
python convert.py ../model/yolo11n.onnx rk3588 i8 ../model/yolo11n_rk3588.rknn
ls -lh ../model/yolo11n_rk3588.rknn

四个参数依次为 ONNX 路径、目标平台、量化类型和输出路径。本篇必须使用 rk3588。

从 examples/yolo11/python 运行，确保脚本能找到校准集 datasets/COCO/coco_subset_20.txt。该数据集用于示例验证，业务模型需使用代表实际场景的数据校准。

本次真实转换输出节选：

text

I rknn-toolkit2 version: 2.3.2
...
--> Building model
...
I rknn building ...
I rknn building done.
done
--> Export rknn model
done

转换成功后会生成 .rknn 文件。输入/输出类型改为 int8 的提示属于量化提醒，后续使用配套 C++ 示例处理输入输出。

#4. 编译程序、通过 SCP 部署并运行

#4.1 准备 ARM64 交叉编译器

PC 执行：

bash

cd ~/RKNN2_Project
wget -c https://dn.odroid.com/compiler/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.tar
tar -xf gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.tar

export GCC_COMPILER="$HOME/RKNN2_Project/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu"
"${GCC_COMPILER}-gcc" --version

实测编译器为 Linaro GCC 6.3.1 20170404。GCC_COMPILER 是前缀，不带末尾的 -gcc；构建脚本会自动追加。

#4.2 编译 RK3588 的 YOLO11 C++ 示例

PC 执行：

bash

cd ~/RKNN2_Project/rknn_model_zoo
bash build-linux.sh -t rk3588 -a aarch64 -b Release -d yolo11

先转换模型，再执行构建，脚本会将 .rknn 一并复制到部署目录。

部署文件结构如下，其他附带示例程序可保留：

text

install/rk3588_linux_aarch64/rknn_yolo11_demo/
├── rknn_yolo11_demo
├── lib/
│   ├── librknnrt.so
│   └── librga.so
└── model/
    ├── yolo11n_rk3588.rknn
    ├── bus.jpg
    └── coco_80_labels_list.txt

#4.3 通过 SCP 部署完整目录

PC 执行：

bash

ssh rk3588@BOARD_IP 'mkdir -p ~/RKNN2_Project'
cd ~/RKNN2_Project/rknn_model_zoo
scp -r install/rk3588_linux_aarch64/rknn_yolo11_demo \
  rk3588@BOARD_IP:~/RKNN2_Project/

复制完整目录，包括 lib/ 和 model/；随包 Runtime 版本为 2.3.2。

#4.4 在板端执行目标检测

板端执行：

bash

cd ~/RKNN2_Project/rknn_yolo11_demo
sudo env LD_LIBRARY_PATH="$PWD/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
  ./rknn_yolo11_demo model/yolo11n_rk3588.rknn model/bus.jpg

本次 RK3588 真实输出节选：

text

model input num: 1, output num: 9
model is NHWC input fmt
model input height=640, width=640, channel=3
...
rknn_run
bus @ (91 135 552 435) 0.948
person @ (109 236 223 536) 0.898
person @ (212 240 285 509) 0.843
person @ (477 230 559 521) 0.827
person @ (79 359 116 515) 0.448
write_image path: out.png width=640 height=640 channel=3 ...

程序正常退出并生成 out.png 即完成检测；坐标和置信度可能随版本及量化结果变化。

PC 执行，取回图片：

bash

mkdir -p ~/RKNN2_Project/results
scp rk3588@BOARD_IP:~/RKNN2_Project/rknn_yolo11_demo/out.png \
  ~/RKNN2_Project/results/yolo11n-rk3588-out.png

在 PC 打开结果图查看检测框，也可在板端图形界面直接打开 out.png。

#4.5 验证 Lite2 能运行同一个模型

使用同一模型和全零输入验证 Lite2 推理链路；此步骤不做图片检测后处理。

板端执行：

bash

cd ~/RKNN2_Project/rknn_yolo11_demo
sudo "$HOME/venvs/rknn-lite2/bin/python" - <<'PYCODE'
import numpy as np
from rknnlite.api import RKNNLite

rknn = RKNNLite()
try:
    ret = rknn.load_rknn('model/yolo11n_rk3588.rknn')
    if ret != 0:
        raise RuntimeError(f'load_rknn failed: {ret}')
    ret = rknn.init_runtime()
    if ret != 0:
        raise RuntimeError(f'init_runtime failed: {ret}')
    outputs = rknn.inference(inputs=[np.zeros((1, 640, 640, 3), dtype=np.uint8)])
    if outputs is None:
        raise RuntimeError('inference failed')
    print('Lite2 inference OK; output count:', len(outputs))
finally:
    rknn.release()
PYCODE

本次实测返回：

text

Lite2 inference OK; output count: 9

使用虚拟环境 Python 的绝对路径，避免 sudo python3 意外调用未安装 Lite2 的系统 Python。

#4.6 常见问题与验收

现象	检查方法
NPU 驱动找不到	回到 1.2 节核对 `RKNPU` 绑定和启动日志；驱动编入内核时不依赖 `lsmod`
Lite2 导入成功但初始化失败	检查 `/usr/lib/librknnrt.so`、NPU 驱动和访问权限
`Can not find dynamic library`	按 2.3 节安装系统 Runtime，不能只复制 Demo 的 `lib/`
`pip check` 提示依赖冲突	回到独立 PC 环境，按 3.2 节安装声明依赖，不沿用其他项目的旧 ONNX/protobuf
找不到量化图片或 `py_utils`	核对工作目录、仓库校准集和 `PYTHONPATH`
模型平台不匹配	重新使用 `rk3588` 转换，运行 `yolo11n_rk3588.rknn`
模型或标签文件不存在	完整复制部署目录，并先进入 `rknn_yolo11_demo` 目录
动态库不存在	检查 `lib/librknnrt.so`，并按 4.4 节传入 `LD_LIBRARY_PATH`

完成后应具备：NPU 驱动可查询、Runtime/Lite2 可用、PC 转换成功、C++ 程序能生成检测图片、Lite2 能返回九个输出张量。

#4.7 参考资料

RKNN-Toolkit2 官方仓库：Toolkit、Runtime、Lite2 及配套文档。
RKNN SDK V2.3.2 快速上手指南：本教程将连接与传输步骤改为 SSH/SCP。
本次验证的 YOLO11 示例：ONNX 下载、转换脚本与 C++ 后处理。
Seeed Armbian 扩展与软件源：reComputer 配套内核和设备树软件包来源。