RK3566 搭建 RKNN-Toolkit2 环境笔记

在基于瑞芯微 RK3566 / RK3568 等芯片（如立创·泰山派、Radxa、鲁班猫）进行边缘 AI 应用开发时，官方的 NPU 工具链主要基于 RKNN-Toolkit2。初学者在刚接触该生态时，极易对官方仓库中多个形态各异的包产生混淆。

在动手部署前，必须首先厘清三者的核心分工与运行位置：

组件名称	运行环境	主要职责与定位
rknn-toolkit2	PC 端（x86_64 Linux）	模型转换（ONNX/PyTorch/TF 转 .rknn）、量化、PC 端仿真、通过 USB/ADB 远程调试板端 NPU。严禁/无法在 RK3566 开发板上安装！
rknpu2	RK3566 板端（aarch64）	板端底层 NPU 运行时库，提供 C API（rknn_api.h）、动态库 librknnrt.so 及调试服务 rknn_server，用于 C/C++ 推理。
rknn-toolkit-lite2	RK3566 板端（aarch64）	板端专用的 Python 推理库，仅支持加载运行已转换好的 .rknn 格式模型，不具备模型转换与量化功能。

官方统一仓库地址：https://github.com/airockchip/rknn-toolkit2

本文将完整记录“PC 端转换环境搭建 $\to$ RK3566 板端驱动检查 $\to$ C++ 运行时部署 $\to$ 板端 Python lite2 推理环境配置”的端到端落地流程。

---

整体工作流概览

$$\begin{aligned}
\text{【PC 端 x86_64】}&: \text{ONNX / PyTorch 模型} \xrightarrow[\text{指定 target=”rk3566”}]{\text{rknn-toolkit2 转换与量化}} \text{.rknn 模型文件} \
&\quad\qquad\qquad\qquad\qquad\qquad\qquad\qquad\qquad\qquad\qquad\downarrow \text{拷贝至板端} \
\text{【板端 RK3566】}&: \begin{cases}
\text{C/C++ 工程} \longrightarrow \text{引入 rknn_api.h，链接 librknnrt.so} \
\text{Python 工程} \longrightarrow \text{通过 rknn-toolkit-lite2 加载并执行推理}
\end{cases}
\end{aligned}$$

---

一、PC 端（x86_64 Ubuntu）安装 rknn-toolkit2

⚠️ 红线提示：rknn-toolkit2 的完整包仅支持 x86_64 架构的 Linux/Windows 系统，千万不要尝试在板子（aarch64）上安装它。

1.1 拉取官方仓库

建议使用 --depth 1 浅克隆以节省网络流量与磁盘空间：

git clone https://github.com/airockchip/rknn-toolkit2.git --depth 1
cd rknn-toolkit2

1.2 创建隔离的 Python 环境

推荐使用 Python 3.8（官方支持与兼容最成熟）：

# 使用 conda 或 venv 均可
conda create -n rknn2 python=3.8
conda activate rknn2

1.3 安装依赖与 Wheel 安装包

进入 x86_64 包目录安装依赖与 whl 本体：

cd rknn-toolkit2/packages/x86_64

# 1. 安装基础依赖（按实际 python 对应版本选择）
pip3 install -r requirements_cp38-*.txt

# 2. 安装 rknn-toolkit2 本体
pip3 install ./rknn_toolkit2-*-cp38-*-x86_64.whl

1.4 PC 端验证

在 Python 终端中导入验证：

from rknn.api import RKNN
rknn = RKNN()
print("rknn-toolkit2 PC 端安装成功！")

在导出模型时，必须显式指定目标芯片平台为 rk3566：

# 示例关键参数：
rknn.config(target_platform="rk3566")

---

二、RK3566 板端准备工作

在 RK3566 开发板（如泰山派、Radxa、鲁班猫等）上执行。

2.1 检查并开启板端 NPU 驱动

首先检查系统内核是否已经加载了 rknpu 驱动：

lsmod | grep rknpu
dmesg | grep -i npu

• 若看到类似 [rknpu]: driver version: ... 等输出，说明内核驱动已就绪。
• 若驱动未启用（例如部分 Radxa 系统）：

  sudo rsetup
  # 进入 Overlays -> Manage overlays -> 开启 Enable NPU，保存并重启
  sudo reboot

• 若使用官方 APT 源自带 NPU 运行时包（如部分 Radxa OS）：

  sudo apt update
  sudo apt install -y rknpu2-rk356x

2.2 安装板端基础依赖

sudo apt update
sudo apt install -y python3 python3-pip python3-dev git gcc g++

---

三、部署 rknpu2（板端 C/C++ 运行时）

无论是运行 C/C++ 程序还是后续运行 Python 推理库，底层都依赖 librknnrt.so。

在仓库中的源码目录结构如下：

rknn-toolkit2/rknpu2/runtime/Linux/librknn_api/
├── include/
│   ├── rknn_api.h       # C/C++ 核心头文件
│   └── rknn_matmul_api.h
└── aarch64/
    └── librknnrt.so     # aarch64 平台运行时动态库

方式 A：通过 PC 端 adb 直接推送到板端（适合调试）

在 PC 端终端执行：

# 推送动态库至板端系统库目录
adb push rknpu2/runtime/Linux/librknn_api/aarch64/librknnrt.so /usr/lib/

# （可选）推送 rknn_server 用于 PC 远程调试
adb push rknpu2/runtime/Linux/rknn_server/aarch64/usr/bin/rknn_server /usr/bin/

# 刷新板端动态链接缓存
adb shell ldconfig

方式 B：在板端直接下载/部署（推荐独立开发使用）

直接在板端拉取仓库并部署：

git clone https://github.com/airockchip/rknn-toolkit2.git --depth 1
cd rknn-toolkit2/rknpu2

# 1. 部署动态库
sudo cp runtime/Linux/librknn_api/aarch64/librknnrt.so /usr/lib/
sudo ldconfig

# 2. 部署头文件（供后续 C/C++ 自定义工程调用）
sudo mkdir -p /usr/include/rknpu2
sudo cp runtime/Linux/librknn_api/include/* /usr/include/rknpu2/

⚠️ 架构选库说明：
RK3566 / RK3568 属于标准 ARM aarch64 架构，使用的动态库名称为 **librknnrt.so**。切勿拷贝 RV 系列（如 RV1109/RV1126 使用的 librknnmrt.so）。

---

四、板端安装 rknn-toolkit-lite2（Python 推理库）

⚠️ 提示：rknn-toolkit-lite2 专用于板端运行推理，不具备模型转换功能。

4.1 安装对应 Python 版本的 Wheel 包

建议结合前文构建的独立 Python 虚拟环境（如 RK3566 Ubuntu26.04 安装 Python3.12）或系统默认 Python：

# 查看板端 Python 版本
python3 --version

# 进入板端 lite2 包目录
cd rknn-toolkit2/rknn-toolkit-lite2/packages

# 选择对应 python 版本的 aarch64 wheel 安装（以当前 python 版本匹配对应的 cp 文件）
pip3 install ./rknn_toolkit_lite2-*-manylinux_2_17_aarch64.whl

也可以直接通过 pip 在线源安装（需确保源中有匹配平台构型的 wheel）：

pip3 install rknn-toolkit-lite2

4.2 板端最小推理验证

编写简单的验证脚本，加载 PC 端转换好拷贝过来的 .rknn 模型测试：

from rknnlite.api import RKNNLite

# 1. 初始化
rknn_lite = RKNNLite()

# 2. 加载模型
ret = rknn_lite.load_rknn_model("./test.rknn")
if ret != 0:
    print("加载 RKNN 模型失败！")
    exit(ret)

# 3. 初始化板端运行环境
ret = rknn_lite.init_runtime(target="rk3566")
if ret != 0:
    print("初始化 NPU 运行时失败，请检查驱动与 librknnrt.so！")
    exit(ret)

print("✅ RKNNLite 在 RK3566 上初始化成功！")

# 4. 执行推理（传入预处理后的 numpy ndarray）
# outputs = rknn_lite.inference(inputs=[input_data])

# 5. 释放资源
rknn_lite.release()

---

五、与硬件加速流水线的衔接（MPP + RGA + RKNN）

至此，RK3566 平台上的视觉处理三大件已全部就绪：

1. 环境准备：RK3566 Ubuntu26.04 安装 Python3.12 提供了隔离的多版本 Python 运行环境；
2. 硬件编解码与预处理：Rockchip 平台 librga 安装部署与权限问题排坑指南 提供了 MPP 高速视频解码与 RGA 零 CPU 开销的格式转换与缩放；
3. 边缘 AI 推理：本篇搭建的 rknpu2 / rknn-toolkit-lite2 负责接收 RGA 预处理完成的张量，直接送进 NPU 硬件完成高速神经网络推理。

---

六、常见踩坑与排障清单

1. **试图在 RK3566 板端执行 pip install rknn-toolkit2**：
   • 报错无法找到符合架构的包。记住原则：转换在 PC（x86），板端只装 lite2 和 rknpu2。
2. **板端运行报错 librknnrt.so: cannot open shared object file**：
   • 确认动态库已拷贝至 /usr/lib/ 或 /usr/lib/aarch64-linux-gnu/，且必须执行 sudo ldconfig 刷新系统链接器缓存。
3. PC 转换的模型在板端初始化失败：
   • 检查 PC 端转换脚本中 rknn.config() 是否指定了 target_platform="rk3566"。若未指定或选错平台，生成的指令集与权重结构板端 NPU 无法识别。
4. rknnlite 导入时报错版本不兼容：
   • wheel 包的文件名必须严格对应 Python 解释器的具体版本（如 cp38 对应 Python 3.8，cp312 对应 Python 3.12）。
5. C/C++ 工程编译报错找不到符号：
   • 链接参数中需增加 -lrknnrt，并确保头文件目录包含 rknn_api.h。若在 PC 端进行交叉编译，请确认使用的是 aarch64-linux-gnu-gcc 交叉工具链。