环境搭建详解

本章详细介绍如何跑通 RKNN 3.x 模型转换。

如果只想快速了解全貌，请看 ch02 环境搭建 30 秒概览。

1. 系统要求

组件最低要求推荐配置
操作系统Ubuntu 20.04Ubuntu 22.04 LTS
CPU4 核 x86_648 核以上
内存8 GB16 GB 或更多
磁盘50 GB100 GB SSD

模型量化不需要 NVIDIA GPU，纯 CPU 即可。

2. 主机端交叉编译工具链

sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

验证：

aarch64-linux-gnu-gcc --version

输出：

aarch64-linux-gnu-gcc (Debian 12.2.0-14+deb12u1) 12.2.0
Copyright (C) 2022 Free Software Foundation, Inc.

关键环境变量

  • CROSS_COMPILE：aarch64-linux-gnu-
  • ARCH：arm64
  • CC：${CROSS_COMPILE}gcc

3. NPU 开发环境

装 RKNN 3.x Toolkit

python3 -m venv ~/rk1828-npu-env
source ~/rk1828-npu-env/bin/activate
cd /userdata/RK1820_RK1828_AI_SDK/rknn/rknn3-toolkit/rknn3-toolkit/packages
pip install rknn3_toolkit-*.whl

RKNN 3.x Toolkit wheel 仅支持 x86_64（manylinux_2_17_x86_64），不能在 RK3588（aarch64）板端直接安装。必须：

  1. 在 Ubuntu 上安装
  2. 用 Ubuntu 转换模型
  3. 把 .rknn 文件传到 RK3588 板端

板端只能装 rknn3-toolkit-lite（推理，不转换），wheel 在 rknn/rknn3-toolkit/rknn3-toolkit-lite/packages/ 下，含 cp39 / cp310 / cp311 / cp312 四个 Python 版本。

验证包：

ls /userdata/RK1820_RK1828_AI_SDK/rknn/rknn3-toolkit/rknn3-toolkit/packages/

输出：

md5sum.txt
requirements_cp310-1.0.0.txt
requirements_cp312-1.0.0.txt
rknn3_toolkit-1.0.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
rknn3_toolkit-1.0.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

验证安装（虚拟环境里）：

python3 -c "from rknn.api import RKNN; print('RKNN 3.x OK')"

输出：

RKNN 3.x OK

在系统 Python 环境中直接运行会报 ModuleNotFoundError: No module named 'rknn'，必须先激活 venv。

RKNN 3.x 支持的输入模型

训练框架导出格式支持情况
PyTorch.pt / .onnx推荐
ONNX.onnx最稳定
TensorFlow.pb / .tflite
PaddlePaddle.pdmodel
Caffe.caffemodel部分算子受限

验证 PCIe NPU 驱动

设备节点：

ls /dev/pcie-rkep-*

输出：

/dev/pcie-rkep-0004:41:00.0

驱动加载：

lsmod | grep pcie_rkep

返回空属正常，驱动已内置到内核，不是模块形式。

PCIe 设备：

/usr/bin/pcie_upgrade_tool ld 2>&1 | sed 's/\x1b\[[0-9;]*m//g'

输出：

Program directory: /usr/bin/
List of connected rkep devices
Addr=0004:41:00.0 [1d87:182a]

服务状态：

systemctl is-active rknn3.service

输出：

active

4. 开发板 NPU 固件加载

固件位置：

ls -lh /lib/firmware/rknn3_rk1820.img

输出：

-rwxr-xr-x 1 root root 2.2M  8月19日 17:59 /lib/firmware/rknn3_rk1820.img

通过 PCIe 下发：

bdf=$(/usr/bin/pcie_upgrade_tool ld 2>&1 | sed 's/\x1b\[[0-9;]*m//g' | grep -o 'Addr=[0-9:a-f]*' | head -1 | cut -d= -f2)
sudo /usr/bin/pcie_upgrade_tool -s "$bdf" uf /lib/firmware/rknn3_rk1820.img

输出：

Program directory: /usr/bin/
Downloading firmware...
Device boot state: 0x00004b52
Device is not in maskrom mode or loader mode

设备已在正常运行状态，固件更新需在 maskrom/loader 模式下进行。正常情况下固件由 rknn3.service 自动加载，无需手动执行。

重启服务：

sudo systemctl restart rknn3.service

输出：

● rknn3.service - rknn3 runtime service
     Loaded: loaded (/lib/systemd/system/rknn3.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-08-17 17:01:04 UTC; 31s ago
   Process: 5042 ExecStart=/bin/rknn3_startup start (code=exited, status=0/SUCCESS)
  Main PID: 5065 (rknn3_transfer_)
       CPU: 5.840s
   CGroup: /system.slice/rknn3.service
           ├─5065 /bin/rknn3_transfer_proxy
           └─5074 rknn3_transfer_proxy -s 0004:41:00.0

服务重启慢：systemctl stop / restart rknn3.service 经常卡在 deactivating 状态 1+ 分钟，需要等进程清理完成。这是已知问题。

5. 验证环境

推理 demo：

which rknn3_cnn_demo      # /usr/bin/rknn3_cnn_demo
which rknn3_llm_demo      # /usr/bin/rknn3_llm_demo
which rknn3_vlm_demo      # /usr/bin/rknn3_vlm_demo

模型吞吐测试：

which rknn3_model_test    # /usr/bin/rknn3_model_test

全部找到即表示环境就绪。

6. 常见问题

现象原因处理
ModuleNotFoundError: No module named 'rknn'没激活 venvsource ~/rk1828-npu-env/bin/activate
Toolkit wheel 装不上装到板端了（aarch64 不支持）移到 PC（x86_64）安装
pcie_upgrade_tool 命令找不到SDK 没装重装 rknn3-runtime deb
Addr= 列为空PCIe 没枚举 / 卡没插好重插 + lspci 看 182a 设备
systemctl restart rknn3.service 卡 deactivating 1+ 分钟已知问题等，不要 Ctrl+C
rknn3_*_demo 找不到SDK 包没装全跑 SDK 安装脚本补全

7. 下一步