在 RK182x 加速卡上运行 CNN 与 Transformer 模型

本文使用 Ubuntu x86_64 PC 完成模型转换和应用交叉编译，再通过 SSH/SCP 将程序部署到运行 Debian 的 RK3588，由 PCIe 连接的 RK182x M.2 加速卡完成推理。它们的关系是：

text

Ubuntu PC：ONNX → RKNN3-Toolkit → .rknn + .weight
                                      │ SCP
                                      ▼
RK3588：C++ Demo ────────────────→ RKNN3 Runtime
        Python / Toolkit Lite ──→ RKNN3 Runtime
                                      │ 通信服务 + PCIe 驱动
                                      ▼
                                RK182x M.2 加速卡

#1. 缺少 RK182x 驱动时如何解决

#1.1 确认问题所在层次

板端执行：

bash

uname -r
lspci -nnk
ls -l /dev/pcie-rkep-*

本例安装驱动前已有如下 PCIe 枚举结果，但该设备下面没有 Kernel driver in use，也没有 /dev/pcie-rkep-*：

text

0000:01:00.0 Processing accelerators [1200]:
Rockchip Electronics Co., Ltd Device [1d87:182a] (rev 01)

同时运行代理出现：

text

List of ntb devices attached
No pcie-rkep devices found

这说明主控已枚举到 PCIe 端点，接下来应补齐、加载 pcie-rkep 驱动。 rknn-smi: command not found 则说明管理工具尚未安装或不在 PATH 中。

⚠️注意：若连 PCIe 端点都没有，先处理供电、M.2 连接及主控 PCIe 配置；本文后续安装流程以端点已被枚举为前提。

#1.2 下载并安装 M.2 软件包

从官方 RK1820/RK1828 预编译软件安装包获取：

text

rknn3-rk182x-m2_1.1.0_arm64.deb

选择 m2 和 arm64，不要换成 sodimm、sodimm-net，也不要给 reComputer 刷入文档中的 RK3588 EVB10 主板镜像。

将rknn3-rk182x-m2_1.1.0_arm64.deb安装包上传到设备端Download文件夹内。

板端执行：

bash

sudo dpkg -i ~/Downloads/rknn3-rk182x-m2_1.1.0_arm64.deb

安装程序在检测到 DKMS 后应显示 Engine: DKMS，针对当前内核编译并安装驱动，同时配置开机加载。

这个 DEB 包一并提供：PCIe 驱动源码和 DKMS 配置、M.2 固件、Runtime 动态库、rknn3_transfer_proxy、rknn-smi、RKNN3 自启服务等。下一节无需再次覆盖安装系统 Runtime。

#1.3 验证驱动并重启

板端执行：

bash

sudo dkms status
sudo modinfo pcie-rkep
lspci -nnk -s 0000:01:00.0
ls -l /dev/pcie-rkep-*

输出为：

text

pcie-rkep/3.3.1, 6.1.115-vendor-seeed-rk3588, aarch64: installed

filename: /lib/modules/6.1.115-vendor-seeed-rk3588/updates/dkms/pcie-rkep.ko
vermagic: 6.1.115-vendor-seeed-rk3588 SMP mod_unload modversions aarch64

0000:01:00.0 Processing accelerators [1200]: Rockchip Electronics Co., Ltd Device [1d87:182a] (rev 01)
        Kernel driver in use: pcie-rkep

/dev/pcie-rkep-0000:01:00.0

普通用户的 PATH 可能不包含 /usr/sbin，因此这里对 dkms、modinfo 使用 sudo。不要仅凭普通用户输入这两个命令时出现“未找到命令”判断软件未安装。

确认驱动安装成功后重启设备：

bash

sudo reboot

#2. 安装及验证 Runtime 和 Toolkit Lite

#2.1 Runtime：由 M.2 DEB 包统一安装

第 1 节的 M.2 包已经完成本教程需要的 Runtime 部署。实际关键文件如下：

文件	用途
`/usr/lib/librknn3_api.so`	Runtime API 入口
`/usr/lib/librknn3_api_rkcp.so`	协处理器模式后端
`/usr/bin/rknn3_transfer_proxy`	RK3588 与加速卡之间的通信代理
`/usr/lib/firmware/rknn3_rk1820.img`	本软件包部署的加速卡固件文件
`/usr/bin/rknn-smi`	状态和版本查询
`rknn3.service`	开机固件加载和 Runtime 服务启动

其中固件路径包含 rk1820 是软件包的实际命名，如果使用RK1828加速卡也使用该M.2配套包。

板端执行：

bash

systemctl status rknn3.service --no-pager -l
sudo rknn3_transfer_proxy devices
sudo rknn-smi info
sudo rknn-smi -v

输出为：

text

Active: active (running)

List of ntb devices attached
0000:01:00.0        b98e6c51    PCIE

Device: 0     Status: Online     Health: OK
Chip: RK1828  Bus-Id: 0000:01:00.0
Memory-Usage(MB): 36 / 5120

rknn-smi version              : 1.3.0
PCIe driver version           : 3.3.1
RC chips connect version      : 3.3.2
EP chips connect version      : 0.0.2
PCIe Device 0 firmware version: 1.1.0
rknn3 API version             : 1.1.0

设备序号、温度和内存占用随运行状态变化；各组件独立编号，版本数字不要求全部相等。此时 C/C++ Runtime 已准备好。

#2.2 准备板端 Lite 安装文件

本文在 PC 获取官方仓库，再只将 Lite 安装文件传到板端。该仓库也会用于下一节安装 PC Toolkit。

PC 执行：

bash

sudo apt update
sudo apt install git wget cmake make gcc g++ openssh-client
mkdir -p ~/RKNN3_Project
cd ~/RKNN3_Project

git clone https://github.com/airockchip/rknn3-toolkit.git
git -C rknn3-toolkit checkout 2136cc54fa79ad289c43e56ed9cf7e63ef56439b

git clone https://github.com/airockchip/rknn3-model-zoo.git
git -C rknn3-model-zoo checkout 174e44c77230735b1458946debb62b3982c1ee58

这里固定为本次验证的仓库提交，避免后续 main 的文件名和 API 变化影响复现。新环境只执行一次克隆；后续章节复用这两个目录。

PC 执行：

bash

ssh rk3588@ip 'mkdir -p ~/RKNN3_Project/lite-packages'
cd ~/RKNN3_Project/rknn3-toolkit/rknn3-toolkit-lite/packages

scp requirements.txt \
  rknn3_toolkit_lite-1.1.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl \
  rk3588@ip:~/RKNN3_Project/lite-packages/

板端 Debian 12 使用 Python 3.11，所以这里选择 cp311 和 aarch64。

#2.3 安装 Lite

板端执行：

bash

sudo apt update
sudo apt install python3.11-venv

python3 -m venv ~/venvs/rknn3-lite
source ~/venvs/rknn3-lite/bin/activate

cd ~/RKNN3_Project/lite-packages
python -m pip install -r requirements.txt
python -m pip install \
  ./rknn3_toolkit_lite-1.1.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

python -m pip check
python -c "from rknn3lite.api import RKNN3Lite; print('RKNN3 Toolkit Lite import OK')"

本次实测输出：

text

No broken requirements found.
RKNN3 Toolkit Lite import OK

再用 Python 接口查询加速卡：

bash

sudo "$HOME/venvs/rknn3-lite/bin/python" - <<'PY'
from rknn3lite.api import RKNN3Lite
rknn = RKNN3Lite()
print(rknn.get_devices_id())
rknn.release()
PY

本次实际返回：

text

[b'0000:01:00.0']

这里特意使用虚拟环境 Python 的绝对路径：直接运行 sudo python3 通常会切换到系统 Python，导致找不到刚安装的 Lite。后续第 4 节运行的是 C++ 程序，不依赖激活 Lite 环境。

#3. 在 Ubuntu PC 配置 Toolkit 并转换 YOLOv6

#3.1 创建 Python 3.10 环境

PC 执行。 从零使用 Miniforge 创建隔离环境；本次验证 PC 原有的 Conda 安装在 ~/miniconda3，实际转换使用其 toolkit3 环境。

bash

mkdir -p ~/Downloads
cd ~/Downloads
wget -c https://github.com/conda-forge/miniforge/releases/download/25.3.0-1/Miniforge3-25.3.0-1-Linux-x86_64.sh
bash Miniforge3-25.3.0-1-Linux-x86_64.sh -b -p "$HOME/miniforge3"
source ~/miniforge3/etc/profile.d/conda.sh
conda create -n toolkit3 python=3.10 -y
conda activate toolkit3

重新打开终端后先执行 source ~/miniforge3/etc/profile.d/conda.sh 和 conda activate toolkit3。已有可用 Conda 的读者使用自己的 Conda 路径，无需再安装一套。

#3.2 安装 RKNN3-Toolkit 1.1.0

PC 执行：

bash

cd ~/RKNN3_Project/rknn3-toolkit/rknn3-toolkit
python -m pip install -r packages/requirements_cp310-1.1.0.txt
python -m pip install \
  packages/rknn3_toolkit-1.1.0-cp310-cp310-manylinux2014_x86_64.whl

python --version
python -m pip show rknn3-toolkit
python -m pip check
python -c "from rknn.api import RKNN; print('RKNN3 Toolkit import OK')"

本次环境版本和依赖检查结果：

text

Python 3.10.21
Name: rknn3-toolkit
Version: 1.1.0
Summary: Rockchip Neural Network Toolkit. (commit: cdbad21c1)
No broken requirements found.

注意此固定提交中的 wheel 直接位于 packages/，不是 PDF 示例中的 packages/x86_64/。也不要将 Toolkit2 安装进这个专用环境：本 SDK 的 PC 导入入口仍然是 from rknn.api import RKNN，容易与旧工具混淆。

#3.3 下载 YOLOv6n ONNX 模型

PC 执行：

bash

cd ~/RKNN3_Project/rknn3-model-zoo/examples/yolov6/model
bash download_model.sh
ls -lh yolov6n_rknn3.onnx

下载脚本默认获取面向 RK182X 优化的 yolov6n_rknn3.onnx。本次下载成功，文件大小为 18,644,871 字节。

该优化模型将 YOLO 解码、候选框筛选、排序与 NMS 等处理放入模型计算流程。本文只使用这一模型，不混用没有 _rknn3 后缀的标准版。

#3.4 执行 INT8 转换

PC 执行：

bash

conda activate toolkit3
cd ~/RKNN3_Project/rknn3-model-zoo
export PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}"

# 官方示例使用的量化校准清单和图片目录
ls datasets/COCO/coco_subset_20.txt
ls datasets/COCO/subset

cd examples/yolov6/python
python convert.py ../model/yolov6n_rknn3.onnx rk1820 i8

参数含义：

参数	含义
`../model/yolov6n_rknn3.onnx`	输入 ONNX
`rk1820`	官方 RK182X 案例使用的转换目标，本次 RK1828 实测可用
`i8`	开启量化；该脚本主体使用 `w8a8`，并对指定子图设置 `w16a16`

脚本已设置输入归一化、uint8/NHWC 输入属性和 core_num=1。首次验证保持原配置，不要另外预改 ONNX 输入布局。

本次转换日志节选：

text

I version: rknn3-toolkit 1.1.0(cdbad21c1@2026-08-22T07:33:23)
...
I rknn building ...
...
I rknn building done.
...
--> Export rknn model
done

确认两个模型文件都已生成：

bash

ls -lh ../model/yolov6n_rknn3.rknn ../model/yolov6n_rknn3.weight

本次 .rknn 约 249 KB，.weight 约 5.1 MB。两个文件必须一起部署。

#4. 编译程序、通过 SCP 部署并运行

#4.1 在 PC 安装 ARM64 交叉编译器

PC 执行：

bash

cd ~/RKNN3_Project
wget -c https://dn.odroid.com/compiler/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.tar
tar -xf gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu.tar

export GCC_COMPILER="$HOME/RKNN3_Project/gcc-linaro-6.3.1-2017.05-x86_64_aarch64-linux-gnu/bin/aarch64-linux-gnu"
"${GCC_COMPILER}-gcc" --version
cmake --version

本次编译器实际版本：

text

aarch64-linux-gnu-gcc (Linaro GCC 6.3-2017.05) 6.3.1 20170404

GCC_COMPILER 是编译器前缀，不带末尾的 -gcc；构建脚本会自行追加。Ubuntu 20.04 的 CMake 满足此案例的 CMake 3.15 最低要求。

#4.2 编译 YOLOv6 C++ Demo

PC 执行：

bash

cd ~/RKNN3_Project/rknn3-model-zoo
./build-linux.sh -t rk3588 -a aarch64 -b Release -d yolov6

本次编译日志节选：

text

[ 68%] Built target rknn_yolov6_demo
...
[100%] Built target cnpy
Install the project...
-- Install configuration: "Release"

部署目录为：

text

install/rk3588_linux_aarch64/rknn_yolov6_demo/
├── rknn_yolov6_demo
├── dataset_eval
├── lib/
│   ├── librknn3_api.so
│   ├── librknn3_api_rkcp.so
│   ├── librga.so
│   └── libpostprocess_yolov6_rk182x.so
└── model/
    ├── yolov6n_rknn3.rknn
    ├── yolov6n_rknn3.weight
    ├── bus.jpg
    └── coco_80_labels_list.txt

构建脚本会把已经转换出的模型一并复制到部署目录，所以顺序必须是“先转换，再编译打包”。

#4.3 用 SCP 复制整个部署目录

PC 执行：

bash

ssh rk3588@ip 'mkdir -p ~/RKNN3_Project'

cd ~/RKNN3_Project/rknn3-model-zoo
scp -r install/rk3588_linux_aarch64/rknn_yolov6_demo \
  rk3588@ip:~/RKNN3_Project/

复制整个目录，不能只复制可执行文件或 .rknn。本文使用新的部署目录，避免覆盖其他项目文件。

#4.4 在板端运行

板端执行：

bash

cd ~/RKNN3_Project/rknn_yolov6_demo

sudo env LD_LIBRARY_PATH="$PWD/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
  ./rknn_yolov6_demo \
  ./model/yolov6n_rknn3.rknn \
  ./model/yolov6n_rknn3.weight \
  ./model/bus.jpg \
  1

最后的 1 是 core_mask=0x01，与此模型的 core_num=1 对应。使用 sudo env ... 是为了同时满足设备节点访问权限，并明确传入 Demo 的动态库路径；只在用户终端里 export LD_LIBRARY_PATH 后再 sudo，该变量可能被清除。

这里使用 Model Zoo 部署目录的 Runtime 动态库，主控固件和通信服务仍由第 1 节安装的 M.2 包提供；两部分已在上表固定版本组合中共同验证。

本次真实推理结果节选：

text

model input num: 1, output num: 1
model is NHWC input fmt
model input height=640, width=640, channel=3
...
Pre-process time: 4.08 ms
Inference time: 18.10 ms
Post-process time: 0.06 ms
Total time: 22.23 ms
--> inference model done
bus @ (97 138 553 438) 0.947
person @ (109 237 223 535) 0.936
person @ (211 240 285 511) 0.928
person @ (478 232 560 522) 0.920
person @ (79 326 118 514) 0.450
write_image path: out.png width=640 height=640 channel=3 ...

这是本次单次执行的测量值，不代表稳定 FPS 或性能基准。成功标准是程序正常退出、输出合理检测结果，并生成 out.png。

#4.5 取回结果图片

PC 执行：

bash

mkdir -p ~/RKNN3_Project/results
scp rk3588@ip:~/RKNN3_Project/rknn_yolov6_demo/out.png \
  ~/RKNN3_Project/results/yolov6-out.png

可以在 Ubuntu 桌面直接打开结果文件。如果你的板端有外接屏幕，可以不拷贝结果，在板端直接查看结果。

以下为本次实测生成的检测图：

RK3588 + RK1828 上的 YOLOv6 检测结果

#5. 首次运行的集中排查

现象	本教程中的处理位置
`rknn-smi: command not found`	安装第 1 节的 M.2 DEB 包；不要只复制代理程序
PCIe 有 `1d87:182a`，但无驱动绑定/设备节点	核对 headers 与运行内核一致，再检查 DKMS 编译结果
`dpkg` 完成，但 DKMS 没有 `installed`	查看 `/var/lib/dkms/pcie-rkep/3.3.1/build/make.log`，不要跳过驱动错误
`No pcie-rkep devices found`	先确认驱动绑定和设备节点，再确认 `rknn3.service`
`ensurepip is not available`	安装 `python3.11-venv` 后重新创建 Lite 虚拟环境
wheel 不受支持	PC 选 `cp310/x86_64`；本文板端选 `cp311/aarch64`
`No module named py_utils`	在 Model Zoo 根目录设置 `PYTHONPATH`，然后进入示例目录
校准集路径不存在	从 `examples/yolov6/python` 运行转换，并检查仓库的 `datasets/COCO`
sudo 后 Python 找不到 Lite	使用虚拟环境 Python 的绝对路径
模型/动态库找不到	完整复制部署目录，在 Demo 目录执行，并通过 `sudo env` 设置库路径

板端集中收集诊断信息：

bash

sudo dkms status
sudo modinfo pcie-rkep
lspci -nnk -s 0000:01:00.0
ls -l /dev/pcie-rkep-*
systemctl status rknn3.service --no-pager -l
sudo journalctl -u rknn3.service -b --no-pager -n 100
sudo dmesg | grep -Ei 'pcie|rkep|rknn|firmware' | tail -n 100

#6. 版本与参考资料

本次验证固定仓库提交：

text

rknn3-toolkit   2136cc54fa79ad289c43e56ed9cf7e63ef56439b
rknn3-model-zoo 174e44c77230735b1458946debb62b3982c1ee58

教程用统一的 ~/RKNN3_Project 作为读者工作目录。

RKNN3 官方仓库：软件组件关系及安装包。
本次版本的 Toolkit Lite：ARM64 wheel、requirements 和 Python 示例。
本次版本的 Runtime：运行库与通信组件。
本次版本的 YOLOv6 示例：下载、转换及 C++ 示例源码。
Seeed Armbian 扩展与软件源：本例主板的厂商软件源项目；头文件必须与实际系统内核配套。