AI / NPU

Neardi Pi 3 搭载 RK3576，NPU 算力为 6 TOPS。这里以 rknn_model_zoo 里的 MobileNet 分类 Demo 和 YOLOv8 检测 Demo 为例，主要整理板端代码获取、编译和模型运行流程。

RKNN 使用流程

NPU 不能直接运行常见训练框架导出的模型。完整流程里，需要先在 PC 上把 ONNX 模型转换成 RKNN 模型，然后在 Neardi Pi 3 上通过 RKNN Runtime 调用 NPU 推理。

简单理解就是：PC 负责“转模型”，Neardi Pi 3 负责“跑模型”。不过如果只是先在 Neardi Pi 3 上验证 NPU，使用 Neardi 镜像仓库即可，常用 RKNN 模型已经准备好了，不需要用户先做转换。

rknn_model_zoo 已经把常用 Demo、运行库、后处理代码和测试图片都整理好了，适合先用来验证 NPU 环境是否正常。PC 端 ONNX 转 RKNN 的步骤单独放在 RKNN 模型转换。

准备编译环境

在 Neardi Pi 3 板端安装基础工具：

sudo apt update  
sudo apt install git cmake build-essential

如果后续编译提示找不到 aarch64-linux-gnu-gcc，再补充安装交叉编译工具：

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

获取 rknn_model_zoo

• Rockchip 官方仓库
• Neardi 镜像仓库

git clone https://github.com/airockchip/rknn_model_zoo  
cd rknn_model_zoo

如果板端访问 GitHub 或模型下载比较慢，可以使用 Neardi 同步仓库。该仓库中的环境和常用 RKNN 模型已经整理过，更适合在板端快速验证，用户可以直接编译运行 Demo，不用先走 PC 端转换流程。

git clone http://git.neardi.com/airockchip/rknn_model_zoo  
cd rknn_model_zoo

官方示例 Demo

Rockchip 官方 rknn_model_zoo/examples 目前已经覆盖视觉、OCR、音频、语音和多模态等常见方向。不同仓库版本中的目录可能会有细微变化，常见目录如下：

clip       lite_transformer  mms_tts    mobilesam  ppseg    resnet      wav2vec2  yamnet  yolov10  yolov5_seg  yolov7  yolov8_obb   yolov8_seg  yolox  
deeplabv3  LPRNet            mobilenet  PPOCR      ppyoloe  RetinaFace  whisper   yolo11  yolov5   yolov6      yolov8  yolov8_pose  yolo_world  zipformer

大致可以这样理解：

示例	用途说明
mobilenet, resnet	图片分类。输入输出都比较简单，适合先做 NPU 冒烟测试。
yolov5, yolov6, yolov7, yolov8, yolov10, yolo11, yolox, ppyoloe	目标检测。输出目标框和类别，比如人、车、COCO 常见物体。
yolov5_seg, yolov8_seg	实例分割。除了目标框，还会输出每个目标的 mask。
yolov8_pose	人体姿态估计。检测人以及肩、肘、膝等关键点。
yolov8_obb	旋转框检测。适合航拍、工业检测等目标角度不固定的场景。
yolo_world, clip	视觉语言或开放词汇相关 Demo，适合做图片特征和文本概念匹配。
deeplabv3, ppseg	语义分割。按像素分类，比如道路、人、背景等。
mobilesam	轻量级 SAM 风格图像分割 Demo。
RetinaFace	人脸检测。
LPRNet	车牌识别。
PPOCR	OCR 文字检测和识别，用于读取图片中的文字。
yamnet	音频事件分类。
wav2vec2, whisper, zipformer	语音识别相关 Demo。
mms_tts	文本转语音 Demo。
lite_transformer	轻量级 Transformer Demo，主要用于序列或 NLP 类模型验证。

如果只是想快速确认板端 NPU 能跑起来，建议先从 mobilenet 或 yolov8 开始。确认 RKNN Runtime、RGA 和 Demo 编译流程都正常后，再根据实际模型类型选择更接近的示例。

修改 build-linux.sh

在 Neardi Pi 3 上编译 RK3576 demo 时，建议在 build-linux.sh 中指定编译器前缀：

 if [ -z ${TARGET_SOC} ] || [ -z ${BUILD_DEMO_NAME} ]; then  
   echo "$usage"  
   exit -1  
 fi  
   
+GCC_COMPILER=aarch64-linux-gnu  
+  
 if [[ -z ${GCC_COMPILER} ]];then  
     if [[ ${TARGET_SOC} = "rv1106"  || ${TARGET_SOC} = "rv1103" ]];then  
         echo "Please set GCC_COMPILER for $TARGET_SOC"

同时确认脚本有执行权限：

chmod +x build-linux.sh

编译 MobileNet Demo

MobileNet 是一个轻量级图片分类 Demo，适合先用来确认 NPU 推理流程是否正常，再继续验证目标检测 Demo。

执行：

./build-linux.sh -t rk3576 -a aarch64 -d mobilenet -b Release

编译完成后，安装目录一般是：

neardi@RK3576:~/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_mobilenet_demo

运行 MobileNet Demo

使用准备好的 panda 图片运行：

neardi@RK3576:~$ cd ~/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_mobilenet_demo  
neardi@RK3576:~/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_mobilenet_demo$ ./rknn_mobilenet_demo ./model/mobilenet_v2.rknn ./model/panda.png

输入图片：

正常运行时会打印模型信息，并输出 Top 5 分类结果：

num_lines=1001  
model input num: 1, output num: 1  
model is NHWC input fmt  
model input height=224, width=224, channel=3  
src width is not 4/16-aligned, convert image use cpu  
finish  
rknn_run  
[388] score=0.999382 class=n02510455 giant panda, panda, panda bear, coon bear, Ailuropoda melanoleuca  
[387] score=0.000056 class=n02509815 lesser panda, red panda, panda, bear cat, cat bear, Ailurus fulgens  
[151] score=0.000048 class=n02085620 Chihuahua  
[850] score=0.000036 class=n04399382 teddy, teddy bear  
[295] score=0.000032 class=n02133161 American black bear, black bear, Ursus americanus, Euarctos americanus

编译 YOLOv8 Demo

执行：

./build-linux.sh -t rk3576 -a aarch64 -d yolov8 -b Release

正常情况下可以看到类似信息：

BUILD_DEMO_NAME=yolov8  
TARGET_SOC=rk3576  
TARGET_ARCH=aarch64  
BUILD_TYPE=Release  
CC=aarch64-linux-gnu-gcc  
CXX=aarch64-linux-gnu-g++

编译完成后，安装目录一般是：

neardi@RK3576:~/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_yolov8_demo

目录内容如下：

neardi@RK3576:~$ cd ~/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_yolov8_demo  
neardi@RK3576:~/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_yolov8_demo$ ls

lib  model  rknn_yolov8_demo  rknn_yolov8_demo_zero_copy

编译过程中如果出现 warning，但最终显示下面内容，一般不影响 Demo 使用：

[100%] Built target rknn_yolov8_demo  
[100%] Built target rknn_yolov8_demo_zero_copy  
Install the project...

运行 YOLOv8 Demo

进入安装目录后运行：

neardi@RK3576:~$ cd ~/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_yolov8_demo  
neardi@RK3576:~/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_yolov8_demo$ ./rknn_yolov8_demo ./model/yolov8.rknn ./model/bus.jpg

正常运行时会打印模型输入输出信息，并输出检测结果，例如：

model input num: 1, output num: 9  
model is NHWC input fmt  
model input height=640, width=640, channel=3  
rga_api version 1.10.1_[0]  
rknn_run  
person @ (211 241 282 507) 0.864  
person @ (109 235 225 536) 0.856  
bus @ (99 136 552 455) 0.856  
person @ (476 223 560 521) 0.848  
write_image path: out.png width=640 height=640 channel=3

运行完成后，当前目录会生成 out.png，可以打开查看检测框效果。

模型转换文档

如果使用 Neardi 镜像仓库，常用 RKNN 模型已经转换好了；只有在使用自己的 ONNX 模型，或者想手动更新模型时，才需要走 PC 端转换流程。PC 端环境安装、RKNN Toolkit2 安装、ONNX 转 RKNN、常见报错已经单独整理：

RKNN 模型转换

常见问题

找不到 aarch64-linux-gnu-gcc

先安装编译器：

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

然后确认 build-linux.sh 中已经加入：

GCC_COMPILER=aarch64-linux-gnu

cmake: command not found

如果编译时停在 ./build-linux.sh: line 202: cmake: command not found，说明板端还没有安装 cmake。安装后重新编译即可：

sudo apt install cmake  
./build-linux.sh -t rk3576 -a aarch64 -d yolo11 -b Release

其他 Demo，比如 yolov8，处理方法也是一样的。

The RKNN model can not be found

如果编译已经完成，但最后提示：

The RKNN model can not be found in "/home/neardi/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_yolo11_demo/model", please check!

一般是对应的 .rknn 模型还没有转换，或者没有放到 demo 的 model 目录。先在 PC 端把 ONNX 转成 RKNN，再把生成的 .rknn 拷贝到对应目录。PC 端步骤可以看 RKNN 模型转换。

例如 yolo11：

scp yolo11.rknn neardi@192.168.1.153:~/rknn_model_zoo/examples/yolo11/model/

然后重新编译：

neardi@RK3576:~$ cd ~/rknn_model_zoo  
neardi@RK3576:~/rknn_model_zoo$ ./build-linux.sh -t rk3576 -a aarch64 -d yolo11 -b Release

如果只是快速验证，也可以直接把 .rknn 拷贝到报错中提示的 install 目录下。

下载模型失败

官方仓库中的部分 Demo 会在线下载模型。如果板端网络访问外网不稳定，建议使用 Neardi 同步仓库：

git clone http://git.neardi.com/airockchip/rknn_model_zoo

运行时报 librknnrt.so 或 librga.so 找不到

优先进入安装目录运行 Demo：

neardi@RK3576:~$ cd ~/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_yolov8_demo  
neardi@RK3576:~/rknn_model_zoo/install/rk3576_linux_aarch64/rknn_yolov8_demo$ ./rknn_yolov8_demo ./model/yolov8.rknn ./model/bus.jpg

该目录下的 lib/ 已经包含 librknnrt.so 和 librga.so。