RKNN 安装

信息

本文档旨在演示如何安装 RKNN SDK，更多资料请查看 RKNN Toolkit2 源码库 的 doc 目录。

RKNN 简介

Rockchip RK3566/RK3568 系列， RK3588 系列， RK3562 系列， RV1103/RV1106 系列芯片搭载神经网络处理器 NPU， 利用 RKNN 可以帮助用户快速部署 AI 模型到 Rockchip 芯片上使用 NPU 硬件加速模型推理。 为了使用 RKNPU，用户首先需要在 x86 计算机上使用 RKNN-Toolkit2 工具，将训练好的模型转换为 RKNN 格式的模型，然后在主板上使用 RKNN C API 或 Python API 进行推断。

包含工具：

• RKNN-Toolkit2 是一个软件开发工具包，供用户在 PC 和 Rockchip NPU 平台上执行模型转换、推断和性能评估。
• RKNN-Toolkit-Lite2 为 Rockchip NPU 平台提供了 Python 编程接口，帮助用户部署 RKNN 模型并加速实施 AI 应用。
• RKNN Runtime 为 Rockchip NPU 平台提供了 C/C++ 编程接口，帮助用户部署 RKNN 模型并加速实施 AI 应用。
• RKNPU 内核驱动负责与 NPU 硬件交互。

整体框架如下：

下载 SDK

克隆 RKNN-Toolkit2 仓库。

提示

建议新建一个目录用来统一存放相关的SDK。

X86 Linux PC

mkdir RKSDK && cd RKSDK
git clone -b v2.3.2 https://github.com/airockchip/rknn-toolkit2.git

版本信息

信息

RKNN-Toolkit2 通过 Python 环境进行模型转换，量化等操作，同时板端也通过 Python 环境和 NPU 驱动的 Python API 交互。 不同架构和操作系统版本依赖的 Python 版本和环境不同，可以参考下方的信息进行选择。 建议使用 Python 环境管理工具进行管理。推荐使用 Miniforge。

版本对应关系如下：

• 使用RKNN-Toolkit2时需要满足以下运行环境要求：

操作系统版本	Ubuntu18.04 (x64)	Ubuntu20.04 (x64)	Ubuntu22.04 (x64)	Ubuntu24.04 (x64)
Python版本	3.6 / 3.7	3.8 / 3.9	3.10 / 3.11	3.12

• ARM64版本运行环境要求：

操作系统版本	Debian10 (arm64)	Debian11 (arm64)	Debian12 (arm64)
Python版本	3.6 / 3.7	3.8 / 3.9	3.10 / 3.11 / 3.12

信息

需要根据上方的版本信息，按照下方的步骤在主机配置虚拟环境，如需使用板端 Python API ，则板端同样需要配置对应的虚拟环境。

安装 Miniforge

X86 Linux PC

wget https://github.com/conda-forge/miniforge/releases/download/25.11.0-0/Miniforge3-25.11.0-0-Linux-x86_64.sh
chmod +x Miniforge3-25.11.0-0-Linux-x86_64.sh
bash Miniforge3-25.11.0-0-Linux-x86_64.sh

创建虚拟环境

X86 Linux PC

conda create -n rknn python=3.8

激活虚拟环境

X86 Linux PC

conda activate rknn

安装 rknn-toolkit2

X86 Linux PC

cd rknn-toolkit2/rknn-toolkit2/packages/x86_64
pip install rknn_toolkit2-2.3.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

如果是 arm64 架构（即板端）：

Device

cd rknn-toolkit2/rknn-toolkit2/packages/arm64
pip install rknn_toolkit2-2.3.2-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

验证安装

执行以下命令，若没有报错，则代表 RKNN-Toolkit2 环境安装成功。

X86 Linux PC

$ python3
>>> from rknn.api import RKNN

安装 rknn-toolkit-lite2

提示

rknn-toolkit-lite2 区别于 rknn_toolkit2 是 rknn-toolkit-lite2 去除模型转换的功能仅集成 NPU 推理的 Python API， 体积更小巧。适合于仅在板端做推理的用户，用户可根据需求选择板端对应 python 版本的 rknn-toolkit-lite2。

Device

cd rknn-toolkit2/rknn-toolkit-lite2/packages
pip3 install rknn_toolkit2-2.3.2-cp3X-cp3X-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

执行以下命令，若没有报错，则代表 rknn_toolkit-lite2 环境安装成功。

Device

$ python3
>>> from rknnlite.api import RKNNLite as RKNN

编译工具

编译板端运行代码时需要用到交叉编译工具链。

点击下载：交叉编译工具链。

下载完成之后解压即可。

编译前需要导出编译器路径到环境变量，让脚本能找到下载的交叉编译器。

X86 Linux PC

export GCC_COMPILER=/path/to/your/gcc/bin/aarch64-linux-gnu

板端驱动配置

提示

RK356X 产品用户使用 NPU 前需要在终端使用 rsetup 开启 NPU: sudo rsetup -> Overlays -> Manage overlays -> Enable NPU，最后重启系统。

如 overlays 选项中无 Enable NPU 选项，请通过: sudo rsetup -> System -> System Update 升级系统, 重启后执行上述步骤开启 NPU。

故障排除

如果 Enable NPU 选项在系统更新后仍然不出现，请尝试以下步骤：

1. 确认系统更新成功：

   • 检查 System Update 是否完成且没有报错
   • 确认系统已完全重启（不是休眠或待机）

2. 检查 NPU 驱动状态：

   # 检查 NPU 驱动是否已加载
   lsmod | grep rknpu
   # 或使用 dmesg 查看启动日志
   sudo dmesg | grep -i npu

3. 验证镜像版本：

   • 确保使用最新版本的 Radxa 官方镜像
   • 部分早期镜像可能不包含完整的 NPU 支持

4. 手动安装 NPU 驱动：

   # 对于 RK356X 系列
   sudo apt update
   sudo apt install rknpu2-rk356x
   sudo reboot

5. 检查硬件兼容性：

   • 确认您的设备型号支持 NPU 功能
   • 某些入门级或特定配置的设备可能没有 NPU 硬件

如果以上步骤仍无法解决问题，请在 Radxa 论坛或 GitHub 仓库提交问题，并附上：

• 设备型号和镜像版本
• sudo dmesg | grep -i npu 的输出
• lsmod | grep rknpu 的输出
• sudo rsetup 界面的截图（如果可能）

信息

Radxa 官方镜像已默认安装 RKNPU2 及其所需依赖，如无法运行可尝试注释命令。

Device

# sudo apt update
# sudo apt install rknpu2-rk3588 #SOC为RK3588系列
# sudo apt install rknpu2-rk356x #SOC为RK356X系列

检查 rknpu2 的驱动版本, 以下输出表示 rknpu2 驱动版本为 0.9.6，建议RKNPU驱动版本>=0.9.2。

信息

rk356X 产品系统， rknpu2 驱动版本为 0.8.8

Device

sudo dmesg | grep "Initialized rknpu"
[ 15.522298] [drm] Initialized rknpu 0.9.6 20240322 for fdab0000.npu on minor 1