RK3588 开发板 Ubuntu/Android12 系统镜像与 RKNN 模型转换部署完整教程

一、系统镜像烧写

1.1 镜像资源获取

RK3588 官方及第三方厂商提供多种系统镜像，主要包括：

Ubuntu 20.04/22.04：桌面版/服务器版，适合 Linux 开发

Android 12：适合移动端应用开发

Debian 11：多数开发板出厂默认系统

镜像可从对应开发板厂商官网下载，如 Firefly、Radxa、Toybrick 等厂商均提供官方固件。

1.2 Windows 环境烧写（RKDevTool）

准备工作：

安装 RK Driver Assistant 驱动

下载 AndroidTool/RKDevTool 烧写工具

Type-C 数据线连接开发板 OTG 口与电脑

进入烧写模式：

Loader 模式：

1. 开发板断电，Type-C 连接电脑

2. 按住 Recovery/V+ 按键不放

3. 上电，按一下 Reset 按键

4. 工具显示"发现一个 LOADER 设备"后松开按键

MaskRom 模式（救砖用）：

1. 开发板断电，Type-C 连接电脑

2. 按住 Maskrom 按键不放

3. 上电，按一下 Reset 按键

4. 工具显示"发现一个 MASKROM 设备"后松开按键

烧写步骤：

1. 打开 RKDevTool，切换到"升级固件"标签页

2. 点击"固件"按钮选择 .img 镜像文件

3. 点击"升级"开始烧写

4. 等待烧写完成，设备自动重启

1.3 Linux 环境烧写（upgrade_tool）

# 安装依赖

sudo apt-get install libusb-1.0-0-dev

# 下载 upgrade_tool 工具并赋予执行权限

chmod +x upgrade_tool

# 检查设备连接

sudo ./upgrade_tool

# 擦除flash（可选，推荐先擦除）

sudo ./upgrade_tool ef

# 烧写完整镜像

sudo ./upgrade_tool uf firmware.img

分分区烧写：

sudo ./upgrade_tool di -b boot.img      # 烧写boot分区

sudo ./upgrade_tool di -r recovery.img  # 烧写recovery分区

sudo ./upgrade_tool di -u uboot.img     # 烧写uboot分区

1.4 TF 卡烧写方式

对于支持 SD 卡启动的开发板，可使用 balenaEtcher 或 dd 命令：

# Linux dd 命令烧写

sudo dd if=ubuntu.img of=/dev/sdX bs=4M status=progress

sync

二、RKNN 开发环境搭建

2.1 RKNN 工具链概述

RKNN 开发涉及两个核心工具包：

2.2 PC 端 RKNN-Toolkit2 安装

推荐环境： Ubuntu 20.04/22.04 + Python 3.8/3.10

步骤一：创建虚拟环境

# 安装系统依赖

sudo apt-get install python3 python3-dev python3-pip

sudo apt-get install libxslt1-dev zlib1g zlib1g-dev libglib2.0-0 \

    libsm6 libgl1-mesa-glx libprotobuf-dev gcc

# 创建虚拟环境（推荐）

python3 -m venv rknn_env

source rknn_env/bin/activate

步骤二：安装 RKNN-Toolkit2

从瑞芯微官方 GitHub 下载对应版本的 RKNN-Toolkit2 包：

# 进入下载的 packages 目录

cd rknn-toolkit2/packages

# 安装依赖

pip install -r requirements_cp38-2.5.0.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装主包

pip install rknn_toolkit2-2.5.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

步骤三：验证安装

from rknn.api import RKNN

print("RKNN Toolkit2 安装成功！")

2.3 板端 RKNN-Toolkit-Lite2 安装

Ubuntu/Debian 系统：

# 安装基础依赖

sudo apt-get update

sudo apt-get install -y python3 python3-pip python3-opencv python3-numpy gcc

# 安装 RKNN Lite2

pip3 install rknn_toolkit_lite2-2.5.0-cp310-cp310-linux_aarch64.whl

验证 NPU 驱动：

# 检查 NPU 设备节点

ls /dev/dri/renderD*

# 检查驱动版本

dmesg | grep rknpu

三、模型转换完整流程

3.1 支持的模型框架

RKNN-Toolkit2 支持以下框架模型转换：

ONNX（推荐，兼容性最好）

PyTorch（TorchScript 格式）

TensorFlow / TensorFlow Lite

Caffe

DarkNet

3.2 ONNX 模型转换（推荐路径）

步骤一：准备 ONNX 模型

以 YOLOv5 为例，先导出 ONNX：

import torch

from models.experimental import attempt_load

model = attempt_load('yolov5s.pt', map_location='cpu')

model.ｅｖａｌ()

dummy_input = torch.randn(1, 3, 640, 640)

torch.onnx.export(model, dummy_input, 'yolov5s.onnx',

                  opset_version=12,

                  input_names=['images'],

                  output_names=['output'])

步骤二：编写转换脚本

from rknn.api import RKNN

def convert_onnx_to_rknn(onnx_path, rknn_path, target_platform='rk3588'):

    # 创建RKNN对象

    rknn = RKNN(verbose=True)

    # 配置模型

    print('--> Config model')

    rknn.config(

        mean_values=[[0, 0, 0]],

        std_values=[[255, 255, 255]],

        target_platform=target_platform,

        quantized_dtype='asymmetric_quantized-u8',

        optimization_level=3

    )

    print('done')

    # 加载ONNX模型

    print('--> Loading model')

    ret = rknn.load_onnx(model=onnx_path)

    if ret != 0:

        print('Load ONNX model failed!')

        exit(ret)

    print('done')

    # 构建模型（INT8量化）

    print('--> Building model')

    ret = rknn.build(

        do_quantization=True,

        dataset='dataset.txt',

        rknn_batch_size=1

    )

    if ret != 0:

        print('Build RKNN model failed!')

        exit(ret)

    print('done')

    # 导出RKNN模型

    print('--> Export RKNN model')

    ret = rknn.export_rknn(rknn_path)

    if ret != 0:

        print('Export RKNN model failed!')

        exit(ret)

    print('done')

    rknn.release()

if __name__ == '__main__':

    convert_onnx_to_rknn('yolov5s.onnx', 'yolov5s_rk3588.rknn', 'rk3588')

3.3 量化校准数据集配置

dataset.txt 格式：

images/calib_001.jpg

images/calib_002.jpg

images/calib_003.jpg

...

量化关键要点：

校准集建议 100-500 张代表性图片

图片必须覆盖实际部署场景的光照、角度、目标尺寸

校准集与验证集必须分开，不可混用

量化类型默认 INT8 非对称量化，精度损失可接受时性能最优

精度要求高的场景可关闭量化（FP16 模式）

3.4 PyTorch 模型直接转换

from rknn.api import RKNN

rknn = RKNN()

rknn.config(target_platform='rk3588')

# 加载PyTorch TorchScript模型

ret = rknn.load_pytorch(

    model='resnet18.pt',

    input_size_list=[[1, 3, 224, 224]]

)

rknn.build(do_quantization=True, dataset='dataset.txt')

rknn.export_rknn('resnet18.rknn')

3.5 使用 rknn_convert 批量转换

通过 YAML 配置文件批量转换：

python -m rknn.api.rknn_convert -t rk3588 -i model_config.yml -o ./output

3.6 模型精度验证

# PC端模拟推理验证

outputs = rknn.inference(inputs=[img_data])

# 精度分析

rknn.accuracy_analysis(inputs=['test_image.jpg'])

# 性能评估

rknn.eval_perf()

# 内存评估

rknn.eval_memory()

四、板端部署推理

4.1 Python 部署（RKNN Lite2）

完整推理示例：

import cv2

import numpy as np

from rknnlite.api import RKNNLite

def init_rknn(model_path):

    rknn_lite = RKNNLite()

    # 加载RKNN模型

    ret = rknn_lite.load_rknn(model_path)

    if ret != 0:

        print('Load RKNN model failed')

        exit(ret)

    # 初始化运行时环境

    ret = rknn_lite.init_runtime(core_mask=RKNNLite.NPU_CORE_0_1_2)

    if ret != 0:

        print('Init runtime failed')

        exit(ret)

    return rknn_lite

def inference(rknn_lite, img_path):

    # 读取并预处理图像

    img = cv2.imread(img_path)

    img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)

    img = cv2.resize(img, (640, 640))

    # 推理

    outputs = rknn_lite.inference(inputs=[img])

    return outputs

if __name__ == '__main__':

    rknn = init_rknn('yolov5s_rk3588.rknn')

    result = inference(rknn, 'test.jpg')

    print('推理结果:', result)

    rknn.release()

NPU 核心配置：

NPU_CORE_0：单核（适合低功耗）

NPU_CORE_0_1：双核

NPU_CORE_0_1_2：三核全开（性能最高，RK3588 6TOPS）

4.2 C++ 部署（RKNN Runtime）

RKNN Runtime 提供 C API，性能优于 Python 接口，适合生产环境部署。

核心流程：

#include <rknn_api.h>

// 1. 初始化上下文

rknn_context ctx;

rknn_init(&ctx, model_data, model_size, 0, NULL);

// 2. 查询模型信息

rknn_input_output_num io_num;

rknn_query(ctx, RKNN_QUERY_IN_OUT_NUM, &io_num, sizeof(io_num));

// 3. 设置输入

rknn_input inputs[1];

inputs[0].index = 0;

inputs[0].buf = input_data;

inputs[0].size = input_size;

rknn_inputs_set(ctx, 1, inputs);

// 4. 执行推理

rknn_run(ctx, NULL);

// 5. 获取输出

rknn_output outputs[1];

rknn_outputs_get(ctx, 1, outputs, NULL);

// 6. 释放资源

rknn_outputs_release(ctx, 1, outputs);

rknn_destroy(ctx);

4.3 Android 12 部署

环境准备：

# 通过adb推送运行时库

adb root && adb remount

adb push librknnrt.so /vendor/lib64/

adb push rknn_server /vendor/bin/

# 启动rknn_server服务

adb shell rknn_server &

Android 应用集成：

通过 JNI 调用 RKNN Runtime C API

或使用 Rockchip 提供的 Android NNAPI 驱动

模型文件放置在 /sdcard/ 或应用私有目录

4.4 性能优化建议

1. 输入尺寸优化：在满足精度前提下尽量减小输入分辨率

2. 量化策略：优先使用 INT8 量化，关键层可使用混合量化

3. 多核调度：多模型场景可分配到不同 NPU 核心并行运行

4. 内存复用：重复使用输入输出缓冲区，避免频繁分配释放

5. 预处理加速：使用 RGA 硬件加速进行图像缩放、格式转换

6. 异步推理：数据预处理与 NPU 推理流水线并行

五、常见问题排查

5.1 烧写相关问题

无法识别设备：检查驱动安装、OTG 线质量、按键操作时序

烧写失败：尝试进入 MaskRom 模式，先擦除 Flash 再烧写

启动失败：确认镜像与开发板型号匹配，检查分区表参数

5.2 模型转换问题

算子不支持：使用 rknn.analysis() 查看支持情况，替换不支持算子

量化后精度下降：

增加校准集数量和代表性

调整量化算法（quantized_algorithm）

使用混合量化，对敏感层关闭量化

检查预处理参数（均值、标准差、通道顺序）是否与训练一致

转换超时：减少 batch_size，降低优化级别

5.3 板端推理问题

初始化失败：检查 NPU 驱动版本与 RKNN 版本匹配性

推理结果异常：

确认模型目标平台为 rk3588

检查输入预处理与转换时配置一致

验证通道顺序（RGB/BGR）

性能不达预期：确认开启三核，检查是否跑在大核上

六、版本兼容性说明

RKNN-Toolkit2 版本需与板端 RKNN Runtime 版本匹配

推荐使用 2.3.0 及以上版本，支持更多算子和优化

RK3588 目标平台生成的模型不能在 RK3568 等其他芯片上运行

Android 12 系统需使用对应版本的 RKNN 运行时库

家具美容培训

家具维修培训