香橙派5开发板NPU调用完整教程：从零开始高效运行AI程序（YOLO实时检测 + LLM大模型）

香橙派5（Orange Pi 5）搭载Rockchip RK3588S SoC，内置6 TOPS（3核×2 TOPS）NPU，支持INT4/INT8/INT16混合精度运算，是性价比极高的边缘AI开发板。它能让YOLO系列目标检测达到实时30-60+ FPS，让小型LLM（如1.5B-7B模型）本地流畅运行，完全脱离云端。

本文基于2025-2026最新资料（Rockchip官方rknn-toolkit2 v2.3.2+、rknn_model_zoo、Pelochus便捷脚本、Joshua Riek ubuntu-rockchip系统），一步步教你完整流程：系统安装 → NPU驱动 → 模型转换 → Python/C++部署 → 实际案例 → 优化排错。全程可操作，适合初学者和进阶开发者。

1. 硬件准备与系统安装

硬件推荐：

• 香橙派5（建议8GB/16GB RAM版本，4GB容易OOM）
• 5V/4A+ Type-C电源（必须稳定，否则启动不稳）
• 高速TF卡（≥Class 10）或M.2 NVMe SSD（强烈推荐SSD）
• 散热：被动散热片+风扇（NPU满载温度会升至60-80℃）
• 可选：USB摄像头、HDMI显示器、网线

最佳系统推荐（NPU驱动最完善）：

1. 访问 https://joshua-riek.github.io/ubuntu-rockchip-download/boards/orangepi-5.html
2. 下载最新 Ubuntu 24.04 Desktop/Server（推荐24.04，内核带最新NPU驱动0.9.8+）
   • 示例：ubuntu-24.04-preinstalled-desktop-arm64-orangepi-5.img.xz
3. 用balenaEtcher或Rufus烧录到TF卡/SSD。
4. 插入板子，通电启动。首次登录默认用户ubuntu，密码ubuntu（立即修改）。
5. 连接网络，更新系统：

   sudo apt update && sudo apt upgrade -y
   sudo apt install python3-pip python3-venv git cmake build-essential libopencv-dev -y
   

验证NPU驱动：

dmesg | grep -i rknpu
ls /dev/rknpu*

看到rknpu设备节点即成功。

备选系统：

• Armbian（最新 nightly 版）
• 官方Orange Pi Ubuntu/Debian（需手动更新rknpu驱动）

2. 在开发板上一键安装NPU运行环境

最简单方式使用社区神器 Pelochus/ezrknpu（专为RK3588/RK3588S优化）：

sudo curl https://raw.githubusercontent.com/Pelochus/ezrknpu/main/install.sh | sudo bash

它会自动安装：

• rknpu2 驱动与运行时库（librknnrt.so）
• rknn-toolkit-lite2（Python API）
• rknn-llm（大模型专用）
• 依赖包与示例

安装完成后重启：

sudo reboot

测试NPU：

# Python简单测试（resnet18）
cd ~/rknn-toolkit-lite2/examples/resnet18   # 脚本会自动下载
python3 test.py

看到输出“Test passed!” 说明NPU可用。

3. 在x86 PC上安装RKNN-Toolkit2

模型转换只能在x86 Ubuntu PC上进行（RK3588不支持板上转换）。

推荐PC系统：Ubuntu 22.04/24.04 x86_64。

# 安装依赖
sudo apt install python3 python3-pip python3-venv libxslt1-dev zlib1g-dev libglib2.0-dev libsm6 libgl1-mesa-glx libprotobuf-dev gcc -y

# 下载工具包
git clone -b v2.3.2 https://github.com/airockchip/rknn-toolkit2.git
cd rknn-toolkit2

# 创建虚拟环境（Python 3.10/3.11）
python3 -m venv rknn_env
source rknn_env/bin/activate
pip install -r doc/requirements_cp310-2.3.2.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 模型转换流程（ONNX → RKNN）

以YOLOv5s为例（最常用）：

1. 在Ultralytics导出ONNX（PC上）：

   pip install ultralytics
   yolo export model=yolov5s.pt format=onnx opset=13 simplify=True
   

2. 使用RKNN-Toolkit2转换：

   # 文件：convert_yolov5.py
   from rknn.api import RKNN
   rknn = RKNN(verbose=True)
   
   # 加载ONNX
   ret = rknn.load_onnx(model='yolov5s.onnx')
   
   # 构建（量化+目标平台）
   ret = rknn.build(do_quantization=True, 
                    dataset='./dataset.txt',  # 100张校准图片
                    target_platform='rk3588')
   
   # 导出
   ret = rknn.export_rknn('./yolov5s.rknn')
   rknn.release()
   print("转换完成！")
   

3. 把生成的 yolov5s.rknn 通过SCP/USB复制到香橙派5上。

其他模型：直接去 https://github.com/airockchip/rknn_model_zoo 下载已转换好的 .rknn 文件（支持YOLOv5/8/11、MobileNet、Whisper等几十个模型）。

5. 在香橙派5上运行AI推理

Python API示例（resnet或YOLO）：

# test_inference.py
from rknnlite.api import RKNNLite
import cv2
import numpy as np

rknn_lite = RKNNLite()

# 加载模型
ret = rknn_lite.load_rknn('./yolov5s.rknn')
ret = rknn_lite.init_runtime(core_mask=255)  # 使用全部NPU core

# 预处理图像（示例）
img = cv2.imread('bus.jpg')
img = cv2.resize(img, (640, 640))
img = np.expand_dims(img, 0).astype(np.float32) / 255.0   # 根据模型调整

# 推理
outputs = rknn_lite.inference(inputs=[img])

# 后处理（YOLO需要NMS等）
# ... 你的后处理代码 ...

rknn_lite.release()
print("推理完成！")

实时视频检测（摄像头）：

• 用OpenCV读取摄像头帧
• 每帧送NPU推理
• 绘制框 + 显示（预期YOLOv5s可达40-60 FPS）

C++版本更快（推荐生产）：

• 克隆 rknpu2
• ./build-linux.sh -t rk3588 -a aarch64 -d yolov5
• 复制可执行文件到板子，直接运行 ./rknn_yolov5_demo yolov5s.rknn test.jpg

6. 进阶：用NPU运行大语言模型（RKLLM）

# 一键安装RKLLM（已在ezrknpu包含）
# 下载预转换模型（推荐Pelochus HF仓库）
GIT_LFS_SKIP_SMUDGE=1 git clone https://huggingface.co/Pelochus/Phi-3-mini-4k-instruct-rkllm
cd Phi-3-mini-4k-instruct-rkllm && git lfs pull

# 运行
rkllm Phi-3-mini-4k-instruct_W8A8_RK3588.rkllm 1024 1024

支持Qwen2、DeepSeek-R1-Distill、ChatGLM3等，1.5B模型可达15-30 tokens/s（预填充更快）。

WebUI：用Gradio/Flask搭建本地聊天界面（Pelochus有现成脚本）。

7. 性能优化与常见问题排查

优化：

• echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
• 用 rknpu load 监控NPU占用：cat /sys/kernel/debug/rknpu/load
• 风扇控温：sudo apt install fan-control
• 多线程：C++ demo支持多线程推理

8. 参考资源

• 官方工具：https://github.com/airockchip/rknn-toolkit2
• 模型仓库：https://github.com/airockchip/rknn_model_zoo （现成YOLO/Whisper等）
• 便捷脚本：https://github.com/Pelochus/ezrknpu
• 系统镜像：https://joshua-riek.github.io/ubuntu-rockchip
• 社区教程（中文）：CSDN搜索“香橙派5 NPU yolov5”、知乎专栏、Bilibili视频
• Radxa文档（通用RK3588）：https://docs.radxa.com