RKNN Toolkit2 安装与使用

目标平台： RK3576 | NPU 算力： 6 TOPS | 文档版本： V1.0
适用板型： C-3576BQ 核心板 + M4-R2 底板
最后更新： 2026-10-23

1. 概述

1.1 功能简介

RKNN Toolkit2 是 Rockchip 官方提供的 NPU 开发工具套件，包含模型转换、量化、推理测试等完整的开发功能。在 RK3576 平台上，RKNN Toolkit2 充分支持其 6 TOPS 算力 NPU 的完整开发流程。

本工具套件的核心功能包括：

  • 模型格式转换：将主流深度学习框架模型（ONNX、PyTorch、TensorFlow、Caffe、Darknet）转换为 RKNN 格式
  • 模型量化：支持 FP32 到 INT8/INT16 的量化压缩，降低模型体积并提升推理速度
  • 板端推理：在 RK3576 目标板上执行模型推理，支持 Python 和 C/C++ 两种 API
  • 性能评估：评估模型在 NPU 上的推理性能（延迟、吞吐量等指标）
  • 模型部署：支持负载均衡分配，满足不同算力需求

RKNN Toolkit2 包含两个主要组件：

组件运行环境功能
rknn-toolkit2宿主机（x86/ARM64）模型转换、量化、导出
rknn-lite2RK3576 目标板板端模型加载与推理执行

1.2 应用场景

RKNN Toolkit2 在 RK3576 平台上适用于以下典型应用场景：

  • 图像分类：ResNet、MobileNet、EfficientNet 等分类模型部署
  • 目标检测：YOLOv5/YOLOv8、SSD、Faster R-CNN 等检测模型
  • 语义分割：DeepLabV3、UNet 等分割模型
  • 人脸识别：人脸检测、特征提取、活体检测
  • 姿态估计：多人姿态估计、手部关键点检测
  • 超分辨率：Real-ESRGAN 等图像超分辨率模型

RK3576 的 6 TOPS NPU 算力使其能够运行主流边缘 AI 模型，适合智能摄像头、智能零售、工业质检等边缘 AI 应用场景。

1.3 工作原理

RKNN 开发流程分为两个阶段：宿主机上的模型转换阶段和目标板上的推理执行阶段。

宿主机（x86/ARM64）                        目标板（RK3576）
┌──────────────────┐                    ┌──────────────────┐
│  RKNN Toolkit2   │                    │  rknpu2 驱动     │
│  ┌────────────┐  │    scp / adb       │  ┌────────────┐  │
│  │ 模型加载   │  │  ───────────→      │  │ 模型加载   │  │
│  │ (ONNX/     │  │   .rknn 文件       │  │ (RKNN格式) │  │
│  │  PyTorch/  │  │                    │  └────────────┘  │
│  │  TF/Caffe) │  │                    │        ↓         │
│  └────────────┘  │                    │  ┌────────────┐  │
│        ↓         │                    │  │ NPU 推理   │  │
│  ┌────────────┐  │                    │  │ (单核6TOPS)│  │
│  │ 量化构建   │  │                    │  └────────────┘  │
│  │ (INT8/16)  │  │                    │        ↓         │
│  └────────────┘  │                    │  ┌────────────┐  │
│        ↓         │                    │  │ 后处理     │  │
│  ┌────────────┐  │                    │  └────────────┘  │
│  │ 导出.rknn  │  │                    │                  │
│  └────────────┘  │                    │                  │
└──────────────────┘                    └──────────────────┘

核心流程说明：

  1. 模型转换：宿主机上的 rknn-toolkit2 将原始模型解析为内部计算图，经过图优化、算子融合等操作后生成 RKNN 格式模型
  2. 量化压缩：在转换过程中可选择对模型进行 INT8 或 INT16 量化，需要提供校准数据集
  3. 模型部署：将生成的 .rknn 文件传输到 RK3576 目标板
  4. NPU 推理：目标板上的 rknpu2 驱动加载模型，在单核 NPU 上执行推理计算
  5. 结果输出：推理结果通过 API 返回给用户程序进行后处理

2. 硬件准备

2.1 硬件需求

组件型号/规格数量备注
主控板C-3576BQ 核心板 + ShimetaPi M4-R2 底板1已烧录 Linux 系统
调试串口线USB 转 TTL（3.3V）1波特率 1500000（1.5Mbps）
网线标准 RJ45 网线1用于 SSH 登录和文件传输
电源5V/2A（Type-C 或 6pin）1空载最小 1000mA
电脑Windows/Linux/Mac1安装 rknn-toolkit2

2.2 NPU 硬件规格

RK3576 内置的 NPU 具有以下规格：

参数规格
算力6 TOPS（INT8）
NPU 核心数1 个核心
支持精度INT8、INT16、FP16
内存接口共享 DDR 内存
设备节点/dev/rknpu0

2.3 引脚连接

调试串口引脚定义（具体引脚以底板原理图为准）：

主控板引脚功能连接调试器
UART_TX_DEBUG发送调试器 RX
UART_RX_DEBUG接收调试器 TX
GND地调试器 GND

串口网络标注以底板原理图（S-04，04-硬件资料/1-底板/shimetapi-3576（M4-R2）_v10_20260304_leda.pdf）为准。 注意：请勿将 TX/RX 反接，且不要连接 VCC 引脚。

3. 软件准备

3.1 宿主机安装 rknn-toolkit2

宿主机环境要求：

项目要求
操作系统Ubuntu 18.04/20.04/22.04（x86_64）或 ARM64 Linux
Python 版本3.6 ~ 3.10（推荐 3.8）
内存建议 8GB 以上

方法一：pip 安装（推荐）

python3 -m venv rknn-env
source rknn-env/bin/activate
pip3 install rknn-toolkit2

说明：pip 包版本随 RKNN Toolkit2 版本更新而变化，以 Rockchip 官方发布的版本号为准。

方法二：从源码安装

git clone https://github.com/airockchip/rknn-toolkit2.git
cd rknn-toolkit2
pip3 install -r rknn-toolkit2/packages/requirements_cp38-2.3.0.txt
pip3 install rknn-toolkit2/packages/rknn_toolkit2-2.3.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

验证安装

python3 -c "from rknn.api import RKNN; print('RKNN Toolkit2 安装成功')"

3.2 目标板运行时安装

RK3576 Debian 系统通常已预装 rknpu2 驱动和运行时库。需要确认以下组件：

# 检查 rknpu 内核模块
lsmod | grep rknpu
# 预期输出：rknpu

# 检查 NPU 初始化日志
dmesg | grep npu
# 预期输出包含：rknpu: ... initialized

# 检查运行时库
ls /usr/lib/librknnrt.so
# 确认动态库存在

# 检查 NPU 设备节点（RK3576 为单核 NPU）
ls -la /dev/rknpu*
# 预期输出：/dev/rknpu0

如果目标板缺少 rknpu2 驱动，需要安装：

dpkg -i rknpu2-driver-*.deb

3.3 Python 运行时环境

目标板需要安装 rknn-lite2 用于板端推理：

pip3 install rknn-lite2
# 或从系统包安装
pip3 install /usr/lib/python3/dist-packages/rknnlite/

验证：

python3 -c "from rknnlite.api import RKNNLite; print('RKNNLite 安装成功')"

3.4 C/C++ 开发环境

使用 C/C++ API 推理时，需确认头文件和库文件：

ls -la /usr/include/rknn_api.h
ls -la /usr/lib/librknnrt.so*

4. 操作步骤

4.1 RKNN API 基本使用流程

4.1.1 ONNX 模型转换示例

from rknn.api import RKNN

rknn = RKNN()

# 配置模型参数
# target_platform 必须指定为 'rk3576'
rknn.config(
    mean_values=[[123.675, 116.28, 103.53]],
    std_values=[[58.395, 57.12, 57.375]],
    target_platform='rk3576',
    quantized_dtype='asymmetric_quantized-8'
)

# 加载原始模型
ret = rknn.load_onnx(model='model.onnx')
if ret != 0:
    print('加载模型失败')
    exit(ret)

# 量化构建
# dataset 指定校准数据文件（每行一个样本路径）
ret = rknn.build(do_quantization=True, dataset='calibration_data.txt')
if ret != 0:
    print('构建模型失败')
    exit(ret)

# 导出 RKNN 模型
ret = rknn.export_rknn('model.rknn')
if ret != 0:
    print('导出模型失败')
    exit(ret)

rknn.release()

4.1.2 PyTorch 模型转换示例

from rknn.api import RKNN

rknn = RKNN()
rknn.config(
    mean_values=[[123.675, 116.28, 103.53]],
    std_values=[[58.395, 57.12, 57.375]],
    target_platform='rk3576'
)

# 加载 PyTorch 模型（需先导出为 ONNX）
ret = rknn.load_pytorch(model='model.pth', input_size_list=[[1, 3, 224, 224]])
if ret != 0:
    print('加载模型失败')
    exit(ret)

ret = rknn.build(do_quantization=True, dataset='calibration_data.txt')
if ret != 0:
    print('构建模型失败')
    exit(ret)

ret = rknn.export_rknn('model.rknn')
if ret != 0:
    print('导出模型失败')
    exit(ret)

rknn.release()

4.1.3 量化校准数据文件格式

校准数据文件（calibration_data.txt）格式为每行一个样本的绝对路径：

/path/to/sample1.jpg
/path/to/sample2.jpg
/path/to/sample3.jpg

推荐使用 20-100 个有代表性的样本进行量化校准。

4.2 板端 Python 推理

4.2.1 基本推理流程

from rknnlite.api import RKNNLite
import numpy as np

rknn = RKNNLite()

# 加载 RKNN 模型
ret = rknn.load_rknn('model.rknn')
if ret != 0:
    print('加载模型失败')
    exit(ret)

# 初始化运行时
# core_mask 指定 NPU 核心分配（RK3576 为单核，使用 NPU_CORE_0）
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0)

# 准备输入数据（224x224 RGB 图像，NHWC 格式）
input_data = np.random.randint(0, 255, (1, 224, 224, 3), dtype=np.uint8)

# 执行推理
outputs = rknn.inference(inputs=[input_data])
print('推理输出 shape:', outputs[0].shape)

# 后处理（softmax + argmax）
logits = outputs[0][0]
probs = np.exp(logits) / np.sum(np.exp(logits))
pred = np.argmax(probs)
print('预测类别:', pred)

rknn.release()

4.2.2 NPU 核心分配模式

RK3576 拥有 1 个 NPU 核心（6 TOPS），支持以下分配模式：

# 单核模式（全部算力，默认推荐）
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0)

# 自动分配（等价于单核）
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_AUTO)

说明：RK3576 为单核 NPU，不存在多核组合模式（如 NPU_CORE_0_1_2）。NPU_CORE_AUTO 与 NPU_CORE_0 在单核平台上效果一致。

4.3 C/C++ 推理

4.3.1 完整 C 推理示例

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "rknn_api.h"

int main(int argc, char *argv[]) {
    rknn_context ctx;
    rknn_input inputs[1];
    rknn_output outputs[1];
    rknn_input_output_num io_num;

    // 读取 RKNN 模型文件
    FILE *fp = fopen("model.rknn", "rb");
    fseek(fp, 0, SEEK_END);
    int model_size = ftell(fp);
    fseek(fp, 0, SEEK_SET);
    void *model_data = malloc(model_size);
    fread(model_data, 1, model_size, fp);
    fclose(fp);

    // 初始化 RKNN 上下文
    int ret = rknn_init(&ctx, model_data, model_size, 0, NULL);
    if (ret < 0) {
        printf("rknn_init 失败: %d\n", ret);
        free(model_data);
        return -1;
    }
    free(model_data);

    // 查询输入输出数量
    ret = rknn_query(ctx, RKNN_QUERY_IN_OUT_NUM, &io_num, sizeof(io_num));
    printf("输入数量: %d, 输出数量: %d\n", io_num.n_input, io_num.n_output);

    // 设置输入
    memset(inputs, 0, sizeof(inputs));
    inputs[0].index = 0;
    inputs[0].type = RKNN_TENSOR_UINT8;
    inputs[0].size = 224 * 224 * 3;
    inputs[0].fmt = RKNN_TENSOR_NHWC;
    inputs[0].buf = input_data;
    ret = rknn_inputs_set(ctx, io_num.n_input, inputs);

    // 执行推理
    ret = rknn_run(ctx, NULL);

    // 获取输出（want_float=1 表示输出为浮点数）
    memset(outputs, 0, sizeof(outputs));
    outputs[0].index = 0;
    outputs[0].want_float = 1;
    ret = rknn_outputs_get(ctx, io_num.n_output, outputs, NULL);

    // 后处理
    float *output_buf = (float *)outputs[0].buf;
    int output_size = outputs[0].size / sizeof(float);
    for (int i = 0; i < output_size; i++) {
        printf("output[%d] = %.6f\n", i, output_buf[i]);
    }

    // 释放资源
    rknn_outputs_release(ctx, io_num.n_output, outputs);
    rknn_destroy(ctx);
    return 0;
}

编译命令：

gcc -o rknn_demo rknn_demo.c -lrknnrt -lm

4.4 命令行工具

模型信息查看

python3 -m rknn.tool.show model.rknn

输出包含模型的输入输出 tensor 信息、算子列表、量化参数等。

板端性能评估

rknn-lite-perf model.rknn

4.5 完整部署工作流

# 步骤1：宿主机上执行模型转换
python3 convert_model.py

# 步骤2：传输模型到目标板
scp model.rknn rk3576@192.168.1.100:/home/rk3576/

# 步骤3：板端执行推理测试
ssh rk3576@192.168.1.100
python3 inference.py

# 步骤4：性能评估
rknn-lite-perf model.rknn

说明：M4-R2 默认登录用户为 rk3576（root 无密码），IP 地址以实际网络配置为准。

5. 代码详解

5.1 RKNN API 调用流程

RKNN()
  → config()       设置量化参数、目标平台
  → load_xxx()     加载原始模型（ONNX/PyTorch/TF/Caffe/Darknet）
  → build()        量化 + 构建 RKNN 图
  → export_rknn()  导出 .rknn 文件
  → release()      释放资源

5.2 板端运行时流程

RKNNLite()
  → load_rknn()    加载 .rknn 模型
  → init_runtime() 初始化 NPU 核心
  → inference()    执行推理
  → release()      释放资源

5.3 NPU 核心分配策略

RK3576 拥有 1 个 NPU 核心，算力 6 TOPS（INT8）。

分配模式算力适用场景
NPU_CORE_06 TOPS默认推荐，全部算力
NPU_CORE_AUTO自动运行时自动分配（单核）

多模型并发示例（单核串行执行，通过锁避免并发竞争）：

import threading

lock = threading.Lock()

def safe_inference(rknn, inputs):
    """多模型并发时使用锁保证 NPU 访问串行化"""
    with lock:
        return rknn.inference(inputs=inputs)

5.4 输入数据预处理

RKNN 模型的输入预处理需要与训练时保持一致。如果在 config() 中已设置 mean_values 和 std_values，则输入数据应为 uint8 原始像素值，RKNN 会自动进行归一化。

import cv2
import numpy as np

def preprocess(image_path, input_size=224):
    """图像预处理：Resize → BGR → RGB → uint8"""
    img = cv2.imread(image_path)
    img = cv2.resize(img, (input_size, input_size))
    img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    img = img.astype(np.uint8)  # RKNN 会自动归一化
    img = np.expand_dims(img, axis=0)  # HWC → NHWC
    return img

5.5 输出后处理

import numpy as np

def postprocess_classification(outputs, top_k=5):
    """分类模型后处理：softmax + top-k"""
    logits = outputs[0][0]
    exp_logits = np.exp(logits - np.max(logits))
    probs = exp_logits / np.sum(exp_logits)
    top_indices = np.argsort(probs)[::-1][:top_k]
    return [(idx, probs[idx]) for idx in top_indices]

6. 常见问题

6.1 rknn-toolkit2 安装失败

现象： pip install 报错，提示依赖不满足或找不到匹配的 wheel 文件。

解决方案：

# 检查 Python 版本（需要 3.6-3.10）
python3 --version

# 安装基础依赖
pip3 install numpy flatbuffers protobuf

# 使用指定版本 wheel 安装
pip3 install rknn_toolkit2-2.3.0-cp38-cp38-*.whl

6.2 模型转换报 "not support op"

现象： 模型转换过程中提示某些算子不被支持。

解决方案：

# 查看支持的算子列表
python3 -c "from rknn.api import RKNN; r=RKNN(); print(r.get_support_op_list())"

建议使用更简单的替代算子，或使用 ONNX opset 11-13 导出模型。

6.3 推理结果全为 0

现象： 板端推理输出全部为 0 或异常值。

解决方案：

# 检查输入数据格式和预处理是否与训练一致
rknn.config(
    mean_values=[[123.675, 116.28, 103.53]],
    std_values=[[58.395, 57.12, 57.375]],
    target_platform='rk3576',
    quantized_dtype='asymmetric_quantized-8'  # 确认量化类型
)

# 检查输入 tensor shape（应为 NHWC 格式）
print("输入 shape:", input_data.shape)

# 检查输入数据类型（应为 uint8）
print("输入 dtype:", input_data.dtype)

6.4 板端推理报错 "init runtime failed"

现象： RKNNLite.init_runtime() 返回错误。

解决方案：

# 确认 rknpu2 驱动已加载
lsmod | grep rknpu

# 确认 NPU 设备节点存在（RK3576 为单核，节点为 /dev/rknpu0）
ls -la /dev/rknpu*

# 确认运行时库存在
ls -la /usr/lib/librknnrt.so*

# 检查 NPU 错误日志
dmesg | grep -i npu

6.5 模型转换后精度下降严重

现象： 量化后的模型精度相比 FP32 模型下降明显。

解决方案：

  • 增加校准数据量（建议 50-200 个样本）
  • 使用混合精度量化
  • 尝试不量化（使用 FP16）
# 不量化，使用 FP16
rknn.build(do_quantization=False)

6.6 推理速度不符合预期

现象： 推理延迟远高于预期。

解决方案：

# 使用性能评估工具确认实际性能
rknn-lite-perf model.rknn

检查是否启用了预编译：

rknn.build(do_quantization=True, pre_compile=True)
rknn.init_runtime(core_mask=RKNNLite.NPU_CORE_0)

6.7 多模型并发推理时部分失败

现象： 多个模型同时推理时，部分模型报错。

解决方案：

  • RK3576 为单核 NPU，多模型推理为串行执行，确认使用锁避免并发冲突
  • 检查内存是否充足（多个大模型同时加载可能超出 DDR 容量）
  • 使用锁保证 NPU 访问串行化
import threading
lock = threading.Lock()

def safe_inference(rknn, inputs):
    with lock:
        return rknn.inference(inputs=inputs)

7. 相关文档

文档名称路径说明
NPU 架构与性能概览NPU架构与性能概览RK3576 NPU 架构和算力介绍
模型转换与量化模型转换与量化模型转换和量化详细教程
分类模型部署分类模型部署(LeNet-ResNet)图像分类模型部署实战
NPU 性能调优与调试NPU性能调优与调试NPU 性能调优和问题排查