RK3588 端侧 AI 部署（二）：主机与板端环境搭建#

这一篇的目标不是“把包装上”，而是得到一个可验证、可复现的开发环境，并用官方 MobileNet Demo 打通：

1
x86 Linux 转换模型
2
  → 交叉编译 AArch64 Demo
3
  → 上传 RK3588
4
  → Runtime/驱动执行 NPU 推理
5
  → 输出正确 Top-5 结果

上一篇：平台、NPU 与 RKNN 工具链

一、建议的环境结构#

主机端#

x86_64 Ubuntu 20.04/22.04，实体机、VMware 或受支持的 WSL 环境均可；
Miniconda/venv 隔离 Python 依赖；
RKNN-Toolkit2；
Git、CMake、编译器和 AArch64 交叉工具链；
可选 VS Code Remote SSH。

RK3588 板端#

板卡厂商提供的 Linux/Android BSP；
RKNPU 内核驱动；
与 Toolkit/模型兼容的 librknnrt.so；
连板调试需要 rknn_server；
Python 原型需要 RKNN-Toolkit-Lite2；
稳定电源、散热器和网络/USB 连接。

主机 Toolkit2 与板端 Lite2 不能混装理解：前者负责转换，后者只负责运行 .rknn。

二、安装前先锁定版本#

打开 RKNN-Toolkit2 主仓库和官方文档目录，确认：

目标芯片是 rk3588；
Release/仓库版本；
wheel 支持的 Python 小版本（文件名中的 cp38、cp310 等）；
主机系统与架构为 Linux x86_64；
板端 Runtime、rknn_server 和驱动兼容要求。

官方仓库目前列出 Python 3.6～3.12 支持，但具体 release 是否提供对应 wheel，仍要以 packages/x86_64 目录中的实际文件为准。

建议建立项目目录：

1
mkdir -p ~/workspace/rk3588-ai/{sdk,models,projects,logs}
2
cd ~/workspace/rk3588-ai

每次实验保存：转换脚本、完整日志、requirements、模型哈希和版本表。

三、安装 RKNN-Toolkit2#

1. 创建独立环境#

下面用 Python 3.10 举例。若你下载的是 cp38 wheel，就创建 Python 3.8 环境，二者必须匹配。

1
conda create -n rknn232 python=3.10 -y
2
conda activate rknn232
3
python --version
4
which python

2. 获取官方仓库#

1
cd ~/workspace/rk3588-ai/sdk
2
git clone https://github.com/airockchip/rknn-toolkit2.git
3
cd rknn-toolkit2
4
git status

为了可复现，正式项目建议切到明确 tag/commit，而不是永远跟随 master：

1
git tag --list
2
git rev-parse HEAD

3. 安装匹配的依赖和 wheel#

先查看有哪些包：

1
find rknn-toolkit2/packages/x86_64 -maxdepth 2 -type f | sort

然后选择与 Python ABI 对应的 requirements 和 wheel：

1
pip install -r rknn-toolkit2/packages/x86_64/requirements_cp310-*.txt
2
pip install rknn-toolkit2/packages/x86_64/rknn_toolkit2-*-cp310-*-linux_x86_64.whl

通配符如果匹配多个文件，应改成明确文件名。不要为了消除报错而随意升级 ONNX、NumPy 等核心依赖；优先使用同一 release 附带的 requirements。

4. 最小导入验证#

1
python - <<'PY'
2
from rknn.api import RKNN
3

4
rknn = RKNN(verbose=True)
5
print("RKNN-Toolkit2 import OK")
6
rknn.release()
7
PY
8

9
pip show rknn-toolkit2
10
pip freeze > ~/workspace/rk3588-ai/logs/rknn232-requirements.txt

出现 ImportError、动态库错误或段错误时，优先检查 Python ABI、x86_64/ARM64 架构和 requirements，而不是反复重装系统 Python。

四、保证主机和开发板互通#

在主机端：

1
ip addr
2
ping <BOARD_IP>
3
ssh <USER>@<BOARD_IP>

在板端：

1
ip addr
2
uname -m

传输文件可以使用：

1
scp ./model.rknn <USER>@<BOARD_IP>:/userdata/models/

若使用 ADB：

1
adb devices
2
adb shell uname -m
3
adb push ./model.rknn /userdata/models/

连板推理依赖 ADB/rknn_server，而纯板端 C++ 程序不要求主机一直连接。

五、检查板端 NPU 环境#

不同 BSP 暴露的节点不同，下面的命令不要求全部成功：

1
dmesg | grep -i rknpu
2
cat /sys/kernel/debug/rknpu/version 2>/dev/null
3
cat /proc/rknpu/version 2>/dev/null
4
modinfo rknpu 2>/dev/null | grep -i version
5

6
ps -ef | grep '[r]knn_server'
7
which rknn_server 2>/dev/null

Runtime 库常见位置可以这样找：

1
find /usr /lib /userdata -name 'librknnrt.so*' 2>/dev/null

记录以下版本：

1
Toolkit2：
2
模型编译版本：
3
librknnrt：
4
rknn_server：
5
RKNPU driver：
6
BSP/Kernel：

更新驱动或系统库有破坏系统的风险。优先使用板卡厂商提供的镜像/BSP；覆盖 librknnrt.so 或 rknn_server 前必须备份原文件，并确认来自同一 SDK release。

六、CPU、NPU 和 DDR 频率#

动态调频适合日常运行，但会让性能测试波动。测试前先查看节点：

1
cat /sys/devices/system/cpu/cpufreq/policy*/scaling_governor
2
cat /sys/devices/system/cpu/cpufreq/policy*/scaling_cur_freq
3
find /sys/class/devfreq -maxdepth 2 -type f -name cur_freq -print
4
cat /sys/kernel/debug/rknpu/load 2>/dev/null

官方 Model Zoo 根目录提供 scaling_frequency.sh。执行前先阅读脚本，确认 sysfs 路径和频率适用于当前 BSP：

1
less ./scaling_frequency.sh
2
sudo bash ./scaling_frequency.sh -c rk3588

脚本参数可能随版本变化，先执行 bash ./scaling_frequency.sh -h 或阅读源码。测试结束后恢复默认 governor；持续最高频运行还要监控散热和降频。

七、用官方 MobileNet 跑通最小闭环#

官方 RKNN Model Zoo 同时提供 Python 转换和 Linux C++ Demo，很适合做环境验收。

1. 下载仓库和模型#

1
cd ~/workspace/rk3588-ai/sdk
2
git clone https://github.com/airockchip/rknn_model_zoo.git
3
cd rknn_model_zoo/examples/mobilenet/model
4
chmod +x download_model.sh
5
./download_model.sh

2. 转换并用 Python 验证#

1
conda activate rknn232
2
cd ../python
3
python mobilenet.py \
4
  --model ../model/mobilenetv2-12.onnx \
5
  --target rk3588

官方脚本默认可生成 mobilenetv2-12.rknn。参数若发生变化，以 MobileNet 示例 README 为准。

3. 交叉编译 Linux Demo#

先准备 AArch64 工具链，并让 GCC_COMPILER 指向工具链可执行文件前缀：

1
cd ~/workspace/rk3588-ai/sdk/rknn_model_zoo
2
export GCC_COMPILER=<AARCH64_TOOLCHAIN_PREFIX>
3
./build-linux.sh -t rk3588 -a aarch64 -d mobilenet

例如工具链实际程序为 /opt/toolchain/bin/aarch64-linux-gnu-gcc，前缀通常写成 /opt/toolchain/bin/aarch64-linux-gnu。具体要求参考官方交叉编译环境指南。

4. 上传并运行#

1
adb push install/rk3588_linux_aarch64/rknn_mobilenet_demo/ /userdata/
2
adb shell
3
cd /userdata/rknn_mobilenet_demo
4
export LD_LIBRARY_PATH=./lib
5
./rknn_mobilenet_demo model/mobilenetv2-12.rknn model/bell.jpg

不用 ADB 时可用 scp -r 上传整个目录。不要只复制可执行文件，否则模型、标签、图片或动态库可能缺失。

官方示例的成功标准是终端打印 Top-5 分类，并且最高类别与测试图片相符。到这里才说明下面几层基本连通：

1
Toolkit2 → RKNN 模型 → AArch64 程序 → librknnrt → 驱动 → NPU

八、常见错误定位#

现象	优先检查
wheel 无法安装	Python `cpXX`、Linux x86_64、wheel 文件名
`from rknn.api import RKNN` 失败	是否激活正确 Conda 环境、requirements 是否匹配
连不上板端	IP/USB、ADB、`rknn_server`、权限
模型版本不兼容	Toolkit、Runtime、server、驱动是否来自兼容 release
`Exec format error`	把 x86 程序传到 ARM，或架构参数选错
找不到 `librknnrt.so`	上传 `lib` 目录并设置 `LD_LIBRARY_PATH`
能运行但结果错误	RGB/BGR、输入 shape、均值/标准差、模型输出契约
FPS 波动大	governor、温度、后台负载、预热和统计方法

九、本篇实践验收#

主机可以导入 RKNN；
主机与 RK3588 可通过 SSH 或 ADB 通信；
能查到板端 RKNPU 驱动和 Runtime 信息；
能转换 MobileNet、交叉编译 Demo 并在板端得到合理 Top-5；
已保存环境版本和 pip freeze。

下一篇：RK3588 端侧 AI 部署（三）：ONNX 转 RKNN 与推理验证

纸翼