从 PyTorch 到 RK3588：一次完整的 NPU 部署实战与踩坑记录

RK3588 NPU 部署完全指南

从 PyTorch 模型到板端 100Hz 实时推理的完整流程，涵盖模型转换、板端部署、性能验证和生产环境配置。

Part 1: PC 端 - Ubuntu 22.04 环境搭建与模型转换

在 PC 上安装 RKNN Toolkit2，完成 PyTorch → ONNX → RKNN 模型转换

Ubuntu 22.04 装 RKNN Toolkit2 踩坑记录

记一下重点。Ubuntu 22.04 上装这个有三个坑：

必须 Python 3.8（系统自带 3.10 不行）
必须虚拟环境（直接装系统 Python 会炸）
包名是 rknn_toolkit2 带下划线，PyPI 上那个是假的

这三条哪个不对后面都会报错。

1. 装系统依赖

先把该装的基础包装上：

sudo apt update
sudo apt install -y \
    build-essential cmake git wget unzip \
    libglib2.0-0 libsm6 libxrender1 libxext6

装 Python 3.8（22.04 不自带）：

sudo apt install -y python3.8 python3.8-dev python3.8-venv

# 确认一下版本
python3.8 --version

2. 搞虚拟环境

建个虚拟环境，别污染系统 Python：

mkdir -p ~/envs
cd ~/envs
python3.8 -m venv rknn_env

# 激活（命令行前面会出现 (rknn_env) ）
source ~/envs/rknn_env/bin/activate

# 检查一下
which python       # 应该是 ~/envs/rknn_env/bin/python
python --version   # 应该是 Python 3.8.x

路径不对或版本不是 3.8 就别往下走了。

升级 pip：

pip install --upgrade pip setuptools wheel

3. 下载源码

cd ~
git clone https://github.com/rockchip-linux/rknn-toolkit2.git
cd rknn-toolkit2
git checkout master

4. 装包

确认虚拟环境还在（echo $VIRTUAL_ENV 能看到路径就行）：

# 装依赖（注意是 cp38 那个）
pip install -r packages/requirements_cp38.txt

# 装主程序
pip install packages/rknn_toolkit2-*.whl

别直接 pip install rknn-toolkit2，PyPI 那个不全。

5. 装模型转换所需的库

只装转换需要的：

# PyTorch（加载模型和导出 ONNX 用，CPU 版本就够了）
pip install torch --index-url https://download.pytorch.org/whl/cpu

# ONNX（转换中间格式）
pip install onnx

6. 测试一下

python - << EOF
from rknn.api import RKNN
print("装好了")
EOF

能 print 出来就说明成功了。每次新开终端记得激活：source ~/envs/rknn_env/bin/activate

7. 下载模型转换示例代码

装好 RKNN Toolkit2 后，下载我的模型转换示例：

下载 rknn_test.zip

包里都有啥：

export_maddpg_actors_to_onnx.py - PyTorch → ONNX 转换脚本
onnx_to_rknn_maddpg.py - ONNX → RKNN 转换脚本（核心）
pc_make_torch_out.py - 生成 PyTorch 参考输出（用于验证）
board_validate.py - 板端验证脚本
agent_*_actor - 训练好的 PyTorch 模型权重
actor_agent*.onnx - 转换好的 ONNX 模型
actor_agent*.rknn - 转换好的 RKNN 模型
networks.py / maddpg.py / agent.py - 网络结构定义

怎么用：

# 1. 激活虚拟环境
source ~/envs/rknn_env/bin/activate

# 2. PyTorch 模型 → ONNX
python export_maddpg_actors_to_onnx.py

# 3. ONNX → RKNN（不量化，保证精度）
python onnx_to_rknn_maddpg.py

# 4. 生成参考输出（用于板端对比验证）
python pc_make_torch_out.py

重点：转换时设置 do_quantization=False，保证和 PyTorch 输出一致。

Part 2: 板端 - RK3588 部署与验证

在 RK3588 开发板上部署 C 程序，实现 100Hz 实时推理和系统服务

0. 你要达到的最终状态

在 RK3588 上能运行：./verify_rknn（推理验证工具）和 ./actor_daemon（常驻部署程序）。
实现以下功能：
- 推理验证（数值一致性/性能/稳定性/极值输入）。
- 开机自启动 + 崩溃自动重启（systemd）。

1. 新板子基础配置

1.1 登录板子并确认架构

uname -m

应输出 aarch64（RK3588 是 ARM64）。

1.2 更新系统 + 安装编译工具

sudo apt update
sudo apt upgrade -y
sudo apt install -y build-essential cmake git pkg-config

2. 安装 RKNN Runtime（librknnrt）

重点：apt 装不到，必须来自 rknpu2 SDK（或厂商 SDK）。

2.1 找到你的 rknpu2 SDK 目录

选项 1：懒得在官网下？用我打包好的：

下载 rknpu2-master.zip

解压后用这个路径（aarch64 版本）：

# 解压到板子上
unzip rknpu2-master.zip
cd rknpu2-master

# 查看文件
ls runtime/RK3588/Linux/librknn_api/aarch64/

选项 2：板子上已有的 SDK（路径因人而异）：

先找到你板子上的 librknnrt.so 在哪：

# 查找 librknnrt.so 的位置
sudo find / -name "librknnrt.so" 2>/dev/null

# 或者用 locate（更快，但可能需要先 updatedb）
sudo updatedb
locate librknnrt.so

找到后记下路径，常见路径示例：

# Khadas 板子常见路径
ls /home/khadas/khadas/rknpu2/runtime/RK3588/Linux/

# 或者其他厂商路径
ls /opt/rknpu2/runtime/RK3588/Linux/

应该能看到：

librknnrt.so / librknnrt.so.1
librknn_api/include/rknn_api.h

2.2 安装到系统目录（推荐，最稳）

如果用我的压缩包（aarch64）：

sudo cp rknpu2-master/runtime/RK3588/Linux/librknn_api/aarch64/librknnrt.so* /usr/lib/
sudo ldconfig

如果用板子自带的（路径根据你实际情况改）：

# 示例：Khadas 路径
sudo cp /home/khadas/khadas/rknpu2/runtime/RK3588/Linux/librknnrt.so* /usr/lib/
sudo ldconfig

验证：

ldconfig -p | grep rknn

应该能看到 librknnrt.so。

3. 建项目目录

mkdir -p ~/rknn_deploy_demo
cd ~/rknn_deploy_demo

把你的 .rknn / obs.bin / torch_out.bin 放这里。

4. 下载完整示例代码

环境配好了，现在下载我打包好的完整代码：

下载 rknn_c.zip

4.1 包里都有啥

核心 C 程序：

npu_daemon.c - 100Hz 推理守护进程，后台常驻运行
rknn_validate.c - 验证工具，测试数值一致性和性能
main.c - 简单的推理示例（可忽略）

编译和部署脚本：

compile_daemon.sh - 编译守护进程
compile_validate.sh - 编译验证工具
deploy_npu_system.sh - 一键部署脚本（推荐）
install_daemon.sh - 安装 systemd 服务
test_daemon.sh - 测试守护进程

systemd 配置：

rk3588-npu-daemon.service - systemd 服务配置文件，设置自启动和崩溃重启

测试数据：

actor_agent*.rknn - 四个智能体的 RKNN 模型
obs_actor_*.bin - PyTorch 测试输入（26 维 float32）
torch_out_actor_*.bin - PyTorch 参考输出（2 维 float32）

文档：

SYSTEM_OVERVIEW.md - 完整的系统架构说明
使用文档.txt - 快速上手指令

4.2 怎么用

快速部署（推荐）：

# 解压后进入目录
cd rknn_c

# 一键部署（编译+安装+启动）
chmod +x *.sh
sudo ./deploy_npu_system.sh

# 查看运行状态
sudo systemctl status rk3588-npu-daemon

分步测试：

# 1. 编译验证工具
./compile_validate.sh

# 2. 验证模型（确保数值和 PyTorch 一致）
./validate_rknn actor_agent0.rknn obs_actor_0.bin torch_out_actor_0.bin

# 3. 测试守护进程（不安装服务）
./test_daemon.sh