📚 课程目录第3章 RKNN软件栈

3. RKNN软件栈

在RK3588边缘AI交付中，模型能否顺利跑在NPU上，往往不取决于模型本身，而取决于整条RKNN软件栈是否“版本对齐”。很多“模型转换成功但板端加载失败”“推理结果异常”“NPU利用率始终为0”的问题，根源都在工具链、运行时、驱动与固件之间的错配。理解这条栈的分层职责与版本约束，是环境搭建的第一步。

一、软件栈分层与职责

RKNN软件栈自上而下可分为五层，每层解决不同问题：

模型转换层（RKNN-Toolkit2）：运行在PC端（x86 Linux/Windows），负责把ONNX、PyTorch、TensorFlow、Caffe等模型量化、转换、编译为.rknn文件，并提供精度分析与模拟推理。
板端运行时（RKNPU2 Runtime）：运行在RK3588上，提供librknnrt.so，负责加载.rknn、管理输入输出内存、提交推理任务到NPU。
用户态驱动（RKNPU2 Driver / rknpu2）：即内核模块rknpu.ko，负责与NPU硬件通信、内存映射、任务调度。
内核与设备树：提供NPU节点、时钟、电源域、IOMMU等资源。
NPU固件（Firmware）：运行在NPU内部MCU上的二进制，负责具体算子执行与硬件调度。

这五层中，RKNN-Toolkit2 与 RKNPU2 Runtime 的版本必须匹配，Runtime 与驱动、固件之间也有最低版本要求。任意一层过旧，都会导致加载失败或推理异常。

二、版本对应关系与查询方法

RKNN-Toolkit2 与 RKNPU2 Runtime 的版本号通常保持同步发布，例如 Toolkit2 1.6.0 对应 Runtime 1.6.0。但驱动与固件版本号独立，需要满足Runtime的最低要求。下表给出常见版本的对应关系：

RKNN-Toolkit2	RKNPU2 Runtime	最低驱动版本	最低固件版本	说明
1.4.0	1.4.0	0.8.0	0.8.0	基础支持RK3588
1.5.0	1.5.0	0.9.0	0.9.0	支持多核调度优化
1.6.0	1.6.0	0.9.6	0.9.6	推荐稳定版本
2.0.0	2.0.0	0.9.8	0.9.8	新算子支持，需较新内核

查询板端实际版本的方法：

# 查看 Runtime 版本
strings /usr/lib/librknnrt.so | grep -i "librknnrt version"

# 查看驱动版本
cat /sys/kernel/debug/rknpu/version
# 或
dmesg | grep -i rknpu

# 查看固件版本
cat /sys/kernel/debug/rknpu/firmware_version

# 查看 NPU 利用率与频率
cat /sys/kernel/debug/rknpu/load
cat /sys/class/devfreq/fdab0000.npu/cur_freq

三、环境搭建流程

推荐在 Ubuntu 20.04/22.04 x86_64 上搭建PC端环境，板端使用官方Buildroot或Debian固件。完整流程如下：

PC端安装RKNN-Toolkit2：创建Python虚拟环境（建议Python 3.8/3.10），安装对应版本的wheel包。
验证PC端转换：用示例模型跑通onnx → rknn转换与模拟推理。
板端确认Runtime：检查librknnrt.so版本是否与Toolkit2匹配，不匹配则替换。
板端确认驱动与固件：通过debugfs查看版本，低于最低要求则升级内核或固件。
联调测试：用rknn_model_zoo中的示例在板端跑通推理，确认NPU利用率大于0。

# PC端：创建环境并安装
conda create -n rknn python=3.10
conda activate rknn
pip install rknn_toolkit2-1.6.0-cp310-cp310-linux_x86_64.whl

# 验证安装
python -c "from rknn.api import RKNN; print('RKNN Toolkit2 OK')"

# 板端：替换 Runtime（如版本不匹配）
scp librknnrt.so root@192.168.1.100:/usr/lib/
ssh root@192.168.1.100 "ldconfig && strings /usr/lib/librknnrt.so | grep version"

提示：RKNN-Toolkit2 的 wheel 包文件名中包含 Python 版本与平台信息，务必选择与当前 Python 版本一致的包，否则会出现 ImportError 或 undefined symbol。

四、典型误区与复盘

误区一：只升级Toolkit2，不升级Runtime。PC端转换出的.rknn可能使用了新版本才支持的算子或元数据格式，板端旧Runtime无法解析，报错RKNN_ERR_MODEL_INVALID。解决方法是保持两端版本一致。

误区二：忽略驱动与固件版本。Runtime版本正确，但驱动过旧，会出现RKNN_ERR_DEVICE_UNAVAILABLE或推理结果全零。此时需检查/sys/kernel/debug/rknpu/version，必要时升级内核或固件。

误区三：在板端直接pip安装rknn-toolkit2。Toolkit2是PC端工具，板端只需Runtime。在板端安装Toolkit2不仅无法使用NPU，还会因依赖冲突破坏系统Python环境。

误区四：用错架构的Runtime。RK3588是aarch64，若误用armhf或x86的librknnrt.so，会出现cannot open shared object file或wrong ELF class。务必确认文件架构：

file /usr/lib/librknnrt.so
# 应输出：ELF 64-bit LSB shared object, ARM aarch64

排障顺序建议：先确认.rknn文件是否由匹配版本的Toolkit2生成，再确认板端Runtime版本，然后检查驱动与固件，最后检查NPU设备节点与权限。按“模型→Runtime→驱动→固件→硬件”的顺序排查，可避免在错误层级反复折腾。

完成环境搭建后，建议用官方rknn_model_zoo中的yolov5或mobilenet示例做一次端到端验证：PC端转换、板端推理、查看NPU负载。只有这条链路完全跑通，后续的模型部署与性能调优才有可靠基础。