本文档介绍如何在 RK3576 Linux 平台上使用预编译的 RKNN demo 程序。

目录结构

dfrobot-ai-demo/
├── rknn_yolov5_demo/                  # YOLOv5 目标检测
├── rknn_yolov5_seg_demo/              # YOLOv5 目标检测+实例分割
├── rknn_yolov8_demo/                  # YOLOv8 目标检测
├── rknn_yolov8_seg_demo/              # YOLOv8 目标检测+实例分割
├── rknn_yolov8_pose_demo/             # YOLOv8 人体姿态估计
├── rknn_yolo11_demo/                  # YOLO11 目标检测
├── rknn_clip_demo/                    # CLIP 图像-文本匹配
├── rknn_whisper_demo/                 # Whisper 语音识别
├── rknn_zipformer_demo/               # Zipformer 语音识别
├── rknn_mms_tts_demo/                 # MMS-TTS 文本转语音
├── rknn_RetinaFace_demo/              # RetinaFace 人脸检测
└── rknn_PPOCR-System_demo/            # PPOCR 文字识别系统
└── rknn_llm_multimodal_model_demo/    # Qwen2-VL-2B 多模态模型

通用使用说明

1. 环境准备

• 硬件平台: RK3576 Linux aarch64系统
• Demo 路径：/dfrobot-ai-demo
• 依赖库: 所有 demo 所需的动态库已包含在各自的 lib/ 目录中
• 模型文件: 需要将对应的 RKNN 模型文件放置在 model/ 目录中

2. 运行方式

进入对应的 demo 目录，直接运行可执行文件：

cd rknn_xxx_demo
./rknn_xxx_demo [参数]

3. 查看帮助

./rknn_xxx_demo

Demo 详细介绍

1. YOLOv5 目标检测 (rknn_yolov5_demo)

功能: 实时目标检测，支持 COCO 数据集的 80 类物体检测

主要特性:

• 支持摄像头实时检测（利用rk3576 ISP功能，使用同一摄像头枚举的两个格式不同的video设备）
• 多线程推理，使用双 NPU 核心加速
• DRM 显示输出

使用方法:

cd rknn_yolov5_demo
# 使用默认摄像头设备
./rknn_yolov5_demo model/yolov5.rknn

# 指定摄像头设备
./rknn_yolov5_demo model/yolov5.rknn /dev/video11 /dev/video12 connector_id

参数说明:

• model_path: RKNN 模型文件路径
• nv12_device: NV12 格式摄像头设备（可选，默认: /dev/video11）
• rgb_device: RGB 格式摄像头设备（可选，默认: /dev/video12）
• connector_id: DRM 连接器 ID（可选，默认: 0，自动选择）

退出: 按 Ctrl+C 查看统计信息（推理帧数、运行时间、平均 FPS）

2. YOLOv5 实例分割 (rknn_yolov5_seg_demo)

功能: 目标检测 + 实例分割，可同时检测物体并生成分割掩码

主要特性:

• 实时目标检测和分割
• 彩色掩码叠加显示
• 多线程推理优化
• 固定显示分辨率720P

使用方法:

cd rknn_yolov5_seg_demo
# 使用默认摄像头设备
./rknn_yolov5_seg_demo model/yolov5_seg.rknn

# 指定摄像头设备和显示设备
./rknn_yolov5_seg_demo model/yolov5_seg.rknn [nv12_device] [rgb_device] [connector_id]

参数说明: 同 YOLOv5 目标检测

3. YOLOv8 目标检测 (rknn_yolov8_demo)

功能: YOLOv8 实时目标检测，性能优于 YOLOv5

主要特性:

• 更高的检测精度和速度
• 双 NPU 核心并行推理
• 实时显示检测结果

使用方法:

cd rknn_yolov8_demo
# 使用默认摄像头设备
./rknn_yolov8_demo model/yolov8n.rknn

# 指定摄像头设备和显示设备
./rknn_yolov8_demo model/yolov8n.rknn [nv12_device] [rgb_device] [connector_id]

参数说明: 同 YOLOv5 目标检测

4. YOLOv8 实例分割 (rknn_yolov8_seg_demo)

功能: YOLOv8 目标检测 + 实例分割

主要特性:

• 高精度目标检测和分割
• 优化的分割掩码渲染
• 多线程后处理加速
• 固定显示分辨率为720P

使用方法:

cd rknn_yolov8_seg_demo
# 使用默认摄像头设备
./rknn_yolov8_seg_demo model/yolov8_seg.rknn

# 指定摄像头设备和显示设备
./rknn_yolov8_seg_demo model/yolov8_seg.rknn [nv12_device] [rgb_device] [connector_id]

参数说明: 同 YOLOv5 目标检测

5. YOLOv8 人体姿态估计 (rknn_yolov8_pose_demo)

功能: 实时人体姿态估计，检测人体关键点和骨架

主要特性:

• 检测 17 个人体关键点
• 绘制骨架连接线
• 实时姿态可视化

使用方法:

cd rknn_yolov8_pose_demo
# 使用默认摄像头设备
./rknn_yolov8_pose_demo model/yolov8_pose.rknn

# 指定摄像头设备和显示设备
./rknn_yolov8_pose_demo model/yolov8_pose.rknn [nv12_device] [rgb_device] [connector_id]

参数说明: 同 YOLOv5 目标检测

关键点说明:

• 检测 17 个关键点：鼻子、眼睛、耳朵、肩膀、手肘、手腕、臀部、膝盖、脚踝等
• 自动绘制骨架连接线

6. YOLO11 目标检测 (rknn_yolo11_demo)

功能: YOLO11 目标检测

主要特性:

• 更高的检测精度
• 优化的推理性能

使用方法:

cd rknn_yolo11_demo
# 使用默认摄像头设备
./rknn_yolo11_demo model/yolo11.rknn

# 指定摄像头设备和显示设备
./rknn_yolo11_demo model/yolo11n.rknn [nv12_device] [rgb_device] [connector_id]

参数说明: 同 YOLOv5 目标检测

7. CLIP 图像-文本匹配 (rknn_clip_demo)

功能: 使用 CLIP 模型进行图像和文本的相似度匹配

主要特性:

• 交互式图像搜索
• 文本查询图像库

参数说明:

$ ./rknn_clip_demo_search
Usage: ./rknn_clip_demo_search <image_model_path> <text_model_path> <image_dir>
Example: ./rknn_clip_demo_search ./model/clip_images.rknn ./model/clip_text.rknn ./images

Interactive mode: Enter text query to search for matching images, or 'quit' to exit.

• image_model_path: 图像编码模型路径
• text_model_path: 文本编码模型路径
• image_dir: 图像目录路径

使用示例:

$ cd rknn_clip_demo
# 交互式使用
# 输入文本查询，例如: "a cat"
# 输入 "quit" 或 "exit" 退出
$ ./rknn_clip_demo_search model/clip_images.rknn model/clip_text.rknn images/
=== Ready for Interactive Search ===
Enter text query to search for matching images (or 'quit' to exit):
> a cat

Searching for: "a cat"
Processing 3 images...
rga_api version 1.10.1_[0]

=== Search Results ===
Processed 3 images
Best match:
  Path:  images//cat.jpg
  Score: 0.262

> quit
Exiting...

8. Whisper 语音识别 (rknn_whisper_demo)

功能: 使用 Whisper 模型进行语音识别，支持中英文

主要特性:

• 支持麦克风实时录音
• 中英文语音识别
• 高精度转录

参数说明:

$ cd rknn_whisper_demo
$ ./rknn_whisper_demo_mic
Usage: ./rknn_whisper_demo_mic <encoder_path> <decoder_path> <task> [duration_sec] [alsa_device]
  encoder_path:   Path to encoder RKNN model
  decoder_path:   Path to decoder RKNN model
  task:           Recognition task: "en" (English) or "zh" (Chinese)
  duration_sec:   Audio capture duration in seconds (default: 20, max: 20)
  alsa_device:    ALSA device name (default: "plughw:0,0")
                  Recommended: "plughw:0,0" (auto format conversion)
                  Alternatives: "default", "hw:0,0" (direct hardware)

Note: If only 4 arguments are provided and the 4th argument looks like an ALSA device
      (starts with 'plughw:', 'hw:', or 'default'), it will be treated as alsa_device.

• encoder_path: 编码模型路径
• decoder_path: 解码模型路径
• task: en: 英文识别，zh: 中文识别
• duration_sec：录音时长（秒），默认 20 秒
• alsa_device:ALSA 设备，默认 "plughw:0,0"

使用示例:

# 英文识别，录音 5 秒
./rknn_whisper_demo_mic model/whisper_encoder_base_20s.rknn model/whisper_decoder_base_20s.rknn en 5

# 中文识别，使用指定麦克风设备
./rknn_whisper_demo_mic model/whisper_encoder_base_20s.rknn model/whisper_decoder_base_20s.rknn zh 10 plughw:0,0

输出: 识别结果会显示在终端

9. Zipformer 语音识别 (rknn_zipformer_demo)

功能: 使用 Zipformer 模型进行语音识别

主要特性:

• 高效的语音识别模型
• 支持麦克风输入
• 实时识别

参数说明:

$ ./rknn_zipformer_demo_mic
Usage: ./rknn_zipformer_demo_mic <encoder_path> <decoder_path> <joiner_path> [duration_sec] [alsa_device]
  encoder_path:   Path to encoder RKNN model
  decoder_path:   Path to decoder RKNN model
  joiner_path:    Path to joiner RKNN model
  duration_sec:   Audio capture duration in seconds (default: 5.0)
  alsa_device:    ALSA device name (default: "plughw:0,0")
                  Recommended: "plughw:0,0" (auto format conversion)
                  Alternatives: "default", "hw:0,0" (direct hardware)

• encoder_path: 编码模型路径
• decoder_path：解码模型路径
• joiner_path：joiner模型路径
• duration_sec： 录音时长
• alsa_device：ALSA 设备，默认 "plughw:0,0"

使用示例:

# 默认 5 秒录音
./rknn_zipformer_demo_mic model/encoder-epoch-99-avg-1.rknn model/decoder-epoch-99-avg-1.rknn model/joiner-epoch-99-avg-1.rknn

# 指定录音时长和设备
./rknn_zipformer_demo_mic model/encoder-epoch-99-avg-1.rknn model/decoder-epoch-99-avg-1.rknn model/joiner-epoch-99-avg-1.rknn 10 plughw:0,0

10. MMS-TTS 文本转语音 (rknn_mms_tts_demo)

功能: 将文本转换为语音并播放

主要特性:

• 交互式文本输入
• 板载扬声器播放

参数说明：

$ ./rknn_mms_tts_demo_interactive
Usage: ./rknn_mms_tts_demo_interactive <encoder_path> <decoder_path> [alsa_device]
Example: ./rknn_mms_tts_demo_interactive model/mms_tts_eng_encoder_200.rknn model/mms_tts_eng_decoder_200.rknn plughw:0,0

Interactive mode: Enter text to convert to speech, or 'quit' to exit.

• encoder_path: 编码模型路径
• decoder_path：解码模型路径
• alsa_device：ALSA 设备，默认 "plughw:0,0"

使用示例:

$ ./rknn_mms_tts_demo_interactive model/mms_tts_eng_encoder_200.rknn model/mms_tts_eng_decoder_200.rknn plughw:0,0
> The weather is really nice today!

Inference time: 0.502 sec, Audio length: 1.072 sec, RTF: 0.469
Playing audio...
Target sample rate: 44100 Hz, actual: 44100 Hz (requested: 16000 Hz)
Using 2 channels (stereo)
Resampling from 16000 Hz to 44100 Hz
Converting from 1 channels to 2 channels
Audio device opened successfully: plughw:0,0
Sample rate: 44100 Hz, Channels: 2, Format: S16_LE
Period size: 512 frames, Buffer size: 2048 frames
Audio data: 47275 frames, 1.07 seconds
Audio data range: [-0.0020, 0.0015] (first 1000 samples)
Warning: Audio data appears to be very quiet or silent!
Playback already running after writing 512 frames
Total frames written: 47275 / 47275
Draining PCM buffer...
PCM state before drain: 3 (0=SND_PCM_STATE_OPEN, 1=RUNNING, 2=XRUN, 3=DRAINING, 4=PAUSED, 5=SUSPENDED, 6=DISCONNECTED, 7=SETUP, 8=PREPARED)
PCM is running, waiting for playback to complete...
Final PCM state: 1
Audio playback complete.

> quit
Exiting...

注意事项: 文本长度限制为 200 个字符

11.RetinaFace 人脸检测 (rknn_RetinaFace_demo)

功能: 高精度人脸检测，可检测多个人脸并标注关键点

主要特性:

• 实时人脸检测
• 人脸关键点检测（5 个点）
• 多线程优化

使用方法:

cd rknn_RetinaFace_demo
# 使用默认摄像头设备
./rknn_retinaface_demo model/RetinaFace.rknn

# 指定摄像头设备和显示设备
./rknn_retinaface_demo model/RetinaFace.rknn [nv12_device] [rgb_device] [connector_id]

参数说明: 同 YOLOv5 目标检测

12. PPOCR 文字识别系统 (rknn_PPOCR-System_demo)

功能: OCR 文字识别，可检测和识别图像中的文字

主要特性:

• 文字检测 + 文字识别
• 支持中英文识别
• 实时 OCR 处理

使用方法:

cd rknn_PPOCR-System_demo
# 使用默认摄像头设备
./rknn_ppocr_system_demo model/ppocrv4_det.rknn model/ppocrv4_rec.rknn
# 指定摄像头设备和显示设备
./rknn_ppocr_system_demo model/ppocrv4_det.rknn model/ppocrv4_rec.rknn [nv12_device] [rgb_device] [connector_id]

参数说明:

• det_model_path: 文字检测模型路径
• rec_model_path: 文字识别模型路径
• 其他参数同 YOLOv5 目标检测

多模态大语言模型（rknn_llm_multimodal_model_demo）

功能：本示例使用的是rknn-llm/examples/multimodal_model_demo，用来演示在k3576端部署多模态模型

主要特征：内置的开源模型：Qwen2-VL-2B

使用示例：

cd rknn_llm_multimodal_model_demo
export LD_LIBRARY_PATH=./lib
# run imgenc
#./imgenc model/rknn/qwen2-vl-vision_rk3576.rknn demo.jpg 3
# run demo(Multimodal Example)
./demo demo.jpg model/rknn/qwen2-vl-vision_rk3576.rknn model/rkllm/qwen2-vl-2B-llm_rk3576.rkllm 2048 4096 3  "<|vision_start|>" "<|vision_end|>" "<|image_pad|>"

#多模态示例
user: <image>What is in the image?
robot: The image depicts an astronaut ，on the moon, enjoying a beer. The background shows the Earth and stars, creating a surreal and futuristic scene.

#纯文本示例
user: 把这句话翻译成英文: 今天天气真好啊！我们一起去郊游吧！
robot: The weather is really nice today! Let's go for a picnic together!

常见问题

1. 摄像头设备找不到
   问题: 提示 camera_source_init fail
   解决方法:

# 列出可用的摄像头设备
v4l2-ctl --list-devices
# 检查设备格式
v4l2-ctl --list-formats-ext --device=/dev/video11

2. 显示设备问题
   问题: 提示 drm_display_init fail
   解决方法:

# 运行 demo 时会自动列出可用的显示器
# 使用 connector_id=0 会自动选择第一个可用显示器
# 或指定具体的 connector_id

3. 麦克风设备问题
   问题: 语音识别 demo 无法录音
   解决方法:

# 列出可用的音频设备
aplay -l
arecord -l
# 尝试不同的 ALSA 设备
# plughw:0,0 (推荐，自动格式转换)
# hw:0,0 (直接硬件访问)
# default (系统默认)

4. 模型文件缺失
   问题: 提示模型文件不存在
   解决方法:

• 确保模型文件已放置在 model/ 目录中
• 检查模型文件路径是否正确
• 确认模型文件格式为 .rknn

5. 动态库加载失败
   问题: 提示 error while loading shared libraries
   解决方法:

# 确保 lib 目录存在且包含所需的 .so 文件
# 设置 LD_LIBRARY_PATH（通常已自动设置）
export LD_LIBRARY_PATH=$PWD/lib:$LD_LIBRARY_PATH

性能优化说明

多线程架构

大部分视觉检测 demo 采用多线程架构：

• 摄像头线程: 负责采集 NV12 和 RGB 图像
• 推理线程: 双 NPU 核心并行推理（Core 0 + Core 1）
• 后处理线程: 双线程并行后处理和绘制
• 显示线程: DRM 显示输出

性能统计

运行 demo 时按 Ctrl+C 可查看性能统计：

• 总推理帧数
• 运行时间
• 平均推理 FPS

更新日志

• 支持双 NPU 核心并行推理
• 优化多线程后处理性能
• 添加交互式语音和图像搜索功能
• 优化显示缓冲区管理，减少闪烁

版本: 1.0
平台: RK3576 Linux aarch64
更新日期: 2025/11/11