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

本指南沿着一条流程完成 NPU 驱动检查 → Runtime 与 Toolkit Lite2 安装 → PC 模型转换 → C++ 编译部署 → 板端推理。案例使用 RKNN Model Zoo 提供的 YOLO11n，运行在 RK3576 芯片内置 NPU 上，全程通过 SSH/SCP 或板端本地终端操作。

#开始之前

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

执行位置约定： “PC 执行”指 Ubuntu 开发机；“板端执行”指 SSH 登录后或板卡本地终端。文中的 BOARD_IP 是占位符，输入自己板卡的局域网 IP，不要照抄该字符串。

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

bash

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

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

bash

ssh rk3576@BOARD_IP

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

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

RK3576 的 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%,

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

renderD129 是本次枚举出的 NPU 节点，不是固定编号；通过 device/driver 指向 RKNPU 来识别。其他 render 节点可能属于显示控制器或 GPU，不能只看 /dev/dri 存在就认为 NPU 正常。

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

bash

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

再重试版本查询。单独缺少 debugfs 查询文件，也不能证明驱动缺失，需要结合启动日志和驱动绑定一起判断。

本机内核配置检查：

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 RK3576 配套 Seeed/Armbian 内核。若驱动检查已通过，可直接进入第 2 节，无需重装内核。

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

bash

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

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

bash

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

这是驱动维护操作，会更改启动内核并断开 SSH。重新登录后按 1.2 节检查，不以安装命令退出成功代替驱动验证。

若软件源中没有这两个包，应先取得 本型号 的厂商系统镜像或 BSP。不要安装另一款开发板的内核、随意复制 rknpu.ko，也不要套用 RK182x 的 DKMS 安装包。自编 BSP 时，需在本板配套内核启用 CONFIG_ROCKCHIP_RKNPU=y，保留正确的 NPU 设备树配置，再按该 BSP 的流程编译和部署；内核与设备树步骤取决于主板，不能由 Toolkit 的 pip install 补齐。

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

#2.1 三个组件的区别

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

PC 导入路径为 from rknn.api import RKNN，板端 Lite2 导入路径为 from rknnlite.api import RKNNLite。Lite2 负责推理，不负责把 ONNX 转成 RKNN；本文的 C++ 示例不依赖 Lite2。

本文通过 SCP 传文件，再在板端本地运行，不使用 PC 的 USB 连板推理功能，无需启动 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 rk3576@BOARD_IP 'mkdir -p ~/RKNN2_Project/packages'

scp ~/RKNN2_Project/rknn-toolkit2/rknpu2/runtime/Linux/librknn_api/aarch64/librknnrt.so \
  rk3576@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 需要这一步。 本次验证的 Lite2 会查找 /usr/lib/librknnrt.so，仅设置 Demo 目录的 LD_LIBRARY_PATH 不能替代其系统库检查。RK3588 上曾因该文件缺失出现 Can not find dynamic library on RK3588!，补齐后恢复正常。

#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 \
  rk3576@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

不要把 PC 的 x86_64 wheel 传给板端；出现 ensurepip is not available 时，先确认 python3.11-venv 已安装，再重建虚拟环境。导入成功只代表 Python 包可用，第 4 节还会验证实际 NPU 推理。

#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；依赖修正后 pip check 返回 No broken requirements found.。

显式固定 ONNX 和 protobuf 是为了避免旧项目依赖污染：使用隔离环境中的 ONNX 1.16.1、protobuf 4.25.4 完成转换，不会改动原 Conda 环境。

#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++ 后处理配套，不要直接换成任意 Ultralytics 原始导出模型；如需转换自训模型，先按官方 YOLO11 导出说明适配。

#3.4 转换为 RK3576 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 rk3576 i8 ../model/yolo11n_rk3576.rknn
ls -lh ../model/yolo11n_rk3576.rknn

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

转换脚本使用仓库内的 datasets/COCO/coco_subset_20.txt 作为量化校准集，因此需要从 examples/yolo11/python 运行以保持相对路径正确。该小规模数据集用于首次验证，业务模型还需用代表真实场景的数据校准并评估精度。

本次真实转换输出节选：

text

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

实际日志首行格式可能带工具内部构建信息；以成功生成目标文件为准。INT8 模型出现输入/输出默认类型改为 int8 的提示是量化脚本的正常提醒。使用本例配套 C++ 程序处理模型输入输出，不要另外随意将图像转成有符号数。

RKNN2 的本案例只需部署一个 .rknn 模型文件。

#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 编译 RK3576 的 YOLO11 C++ 示例

PC 执行：

bash

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

这里使用 bash build-linux.sh，避免仓库脚本没有可执行位时出现 Permission denied。需要先完成模型转换，再编译打包，脚本才会将生成的 .rknn 一起安装到部署目录。

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

text

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

若在同一仓库同时转换了两个平台，安装目录可能包含两份 .rknn；运行时仍需显式选择带 rk3576 后缀的文件。

#4.3 通过 SCP 部署完整目录

PC 执行：

bash

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

完整复制 lib/ 和 model/，不要只复制可执行文件。模型 Runtime 随示例打包到 lib/，本次实测版本为 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_rk3576.rknn model/bus.jpg

本次 RK3576 真实输出节选：

text

model input num: 1, output num: 9
model is NHWC input fmt
model input height=640, width=640, channel=3
...
rknn_run
bus @ (95 136 553 438) 0.944
person @ (108 236 222 535) 0.898
person @ (212 240 284 509) 0.835
person @ (476 229 559 522) 0.831
person @ (79 358 117 515) 0.452
write_image path: out.png width=640 height=640 channel=3 ...

成功标准是进程正常退出，输出公交车和行人的检测结果，并在当前目录生成 out.png。检测坐标与分数可能随工具版本和量化结果略有变化；本次未测量稳定 FPS，不把这次功能验证当作性能基准。

PC 执行，取回图片：

bash

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

在 PC 桌面打开该图片即可查看检测框；若板端连接有显示器，也可以在板端的图形界面直接打开相应的图片。

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

C++ 检测完成后，可以用相同模型检查 Python 推理链路。

板端执行：

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_rk3576.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`
模型平台不匹配	重新使用 `rk3576` 转换，运行 `yolo11n_rk3576.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 配套内核和设备树软件包来源。