rknn-toolkit-lite2 的使用方法

1.1. rknn-toolkit-lite2 介绍

RKNN-Toolkit-Lite2 是 Rockchip 针对自家 RK 系列芯片（RV1126B、RK3576、RK3588 等）专门开发的轻量级 AI 模型部署工具包，聚焦于边缘/嵌入式设备上的模型推理场景。它无需复杂的环境依赖，并且系统资源消耗非常低。其核心功能是加载并运行由 RKNN 工具链转换后的 AI 模型，同时支持适配从 TensorFlow、PyTorch 等主流框架导出的模型。

该工具包提供 C/C++ 和 Python 双语言 API，接口设计简单且易于使用。同时，它针对 RK 芯片的 NPU 硬件加速进行了深度优化，可大幅提升模型推理效率。它适用于智能安防、IoT、家电等边缘 AI 场景，可帮助开发者快速实现模型在边缘侧的部署，并显著降低嵌入式 AI 开发门槛。

rknn-toolkit-lite2 目前已完成对 EASY-EAI-Nano-TB 的适配，用户可使用它进行深度学习算法的纯 Python 开发。同时，它也支持已经编译完成的模型，只需几行代码即可完成算法推理，从而大幅降低开发成本。与此同时，它也有效降低了许多不熟悉 C/C++ 的算法开发者的开发门槛。本文档用于说明如何基于已完成 RKNN 模型转换的模型在开发板上进行推理。

1.1. rknn-toolkit-lite2 介绍 图1

1.2. 环境搭建

1.2.1 安装 git 工具

sudo apt update && sudo apt install git

1.2.2 安装 miniforge3 工具

为了防止多个不同版本的 Python 环境的系统需求发生冲突，建议使用 miniforge3 来管理 Python 环境。请确认是否已经安装 miniforge3 和 conda 的版本信息；如果已经安装，则可以跳过本节步骤。

下载 miniforge3 安装包：

cd /userdata
wget
https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-aarch64.sh

1.2.2 安装 miniforge3 工具 图2

安装 miniforge3：

chmod 777 Miniforge3-Linux-aarch64.sh
bash Miniforge3-Linux-aarch64.sh

1.2.2 安装 miniforge3 工具 图3

1.2.2 安装 miniforge3 工具 图4

1.2.2 安装 miniforge3 工具 图5

1.2.3 创建 Conda 环境

进入 Conda base 环境：

source ~/miniforge3/bin/activate

使用 Python 3.8 版本（推荐版本）创建名为 `RKNN-Toolkit-lite2` 的 Conda 环境：

conda create -n RKNN-Toolkit-lite2 python=3.8

进入 RKNN-Toolkit Conda 环境：

conda activate RKNN-Toolkit-lite2

退出 Conda 环境：

conda deactivate

删除 Conda 环境：

conda remove -n RKNN-Toolkit-lite2 --all

1.2.4 安装 RKNN-Toolkit-Lite2 和 OpenCV 库

从云盘下载：

pip install rknn_toolkit_lite2-2.3.2-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

1.2.4 安装 RKNN-Toolkit-Lite2 和 OpenCV 库 图6

pip install opencv-python

1.2.4 安装 RKNN-Toolkit-Lite2 和 OpenCV 库 图7

1.3. 在开发板上进行 Demo 测试

下载 rknn-toolkit-lite2 的“测试程序 inference_with_lite2.tar.bz2”，并将文件传输到 EASY-EAI-Nano-TB 开发板目录中。

执行以下命令进行解压：

tar -xvf inference_with_lite2.tar.bz2

1.3. 在开发板上进行 Demo 测试 图8

执行以下命令切换目录并运行测试程序：

cd /userdata/inference_with_lite/
python test.py

结果如下所示：

1.3. 在开发板上进行 Demo 测试 图9

1.4. rknn-toolkit-lite2 流程说明

1.4.1 使用流程图

RKNN Toolkit Lite2 的使用流程如下：

1.4.1 使用流程图 图10

1.4.2 示例程序

第 3 节中的示例程序如下：

# -*- coding: utf-8 -*-
import cv2
import numpy as np
from rknnlite.api import RKNNLite

# ==================== 配置项（请根据实际情况修改） ====================
RKNN_MODEL_PATH = "10class_ResNet50_rv1126b.rknn"  # RKNN模型路径
TEST_IMAGE_PATH = "./test-1.jpg"                   # 测试图片路径
INPUT_SHAPE = (224, 224)                           # 模型输入尺寸（必须与模型转换时保持一致）
INPUT_CHANNELS = 3                                 # 输入通道数
CLASSES = ("SUV", "bus", "family sedan", "fire engine", "heavy truck", "jeep", "minibus", "racing car", "taxi", "truck")

# ==================== 核心函数 ====================
def preprocess_image(image_path, input_shape):
    """
    图像预处理：读取→RGB转换→调整大小→维度扩展→NCHW转换→类型转换
    返回值为4维NCHW格式的输入张量
    """
    # 1. 读取图像
    img = cv2.imread(image_path)
    if img is None:
        raise ValueError(f"无法读取图像：{image_path}。请检查路径是否正确！")
    print(f"原始图像shape: {img.shape}")  # 输出原始维度（H,W,C）

    # 2. BGR转RGB（OpenCV默认为BGR，模型训练通常使用RGB）
    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    print(f"RGB转换后的shape: {img_rgb.shape}")

    # 3. 调整为模型输入尺寸
    img_resized = cv2.resize(img_rgb, input_shape)
    print(f"调整尺寸后的shape: {img_resized.shape}")  # (224,224,3)

    # 4. 扩展为4维（重要！添加Batch维度，N=1）
    img_4d_nhwc = np.expand_dims(img_resized, axis=0)
    print(f"扩展Batch维度后的shape (NHWC): {img_4d_nhwc.shape}")  # (1,224,224,3)

    # 5. 转换为NCHW格式（模型日志中会显示 framework layout: NCHW）
    img_4d_nchw = np.transpose(img_4d_nhwc, (0, 3, 1, 2))
    print(f"NCHW转换后的shape: {img_4d_nchw.shape}")  # (1,3,224,224)

    # 6. 类型转换（RKNN Lite2推荐使用float32或uint8。请根据模型的量化类型进行调整）
    img_input = img_4d_nchw.astype(np.float32)
    print(f"最终输入shape: {img_input.shape}, 类型: {img_input.dtype}")

    return img_input

def softmax(x):
    """Softmax归一化，将输出转换为概率"""
    x = x - np.max(x)  # 防止数值溢出
    return np.exp(x) / np.sum(np.exp(x))

def predict(rknn_lite, input_tensor):
    """模型推理，显式指定输入格式"""
    try:
        # 显式指定data_format为NCHW（重要！告知RKNN Runtime输入格式）
        outputs = rknn_lite.inference(
            inputs=[input_tensor],
            data_format='nchw'  # 强制指定输入格式，避免自动识别错误
        )
        return outputs
    except Exception as e:
        print(f"推理失败：{str(e)}")
        return None

# ==================== 主程序 ====================
if __name__ == "__main__":
    # 1. 初始化 RKNN Lite
    rknn_lite = RKNNLite()
    print("--> 正在加载RKNN模型")
    ret = rknn_lite.load_rknn(RKNN_MODEL_PATH)
    if ret != 0:
        print(f"模型加载失败。错误代码：{ret}")
        exit(ret)
    print("模型加载完成")

    # 2. 初始化运行环境（核心修改：删除target参数，让系统自动识别硬件）
    print("--> 正在初始化运行环境")
    ret = rknn_lite.init_runtime()  # 删除target，让系统自动识别RV1126B
    if ret != 0:
        print(f"运行环境初始化失败。错误代码：{ret}")
        exit(ret)
    print("运行环境初始化完成")

    # 3. 图像预处理（强制生成4维输入）
    print("--> 图像预处理")
    try:
        input_tensor = preprocess_image(TEST_IMAGE_PATH, INPUT_SHAPE)
    except ValueError as e:
        print(e)
        exit(1)

    # 4. 模型推理
    print("--> 正在执行推理")
    outputs = predict(rknn_lite, input_tensor)
    if outputs is None or len(outputs) == 0:
        print("推理没有输出！")
        rknn_lite.release()
        exit(1)

    # 5. 结果解析
    print("\n--> 推理结果解析")

1.5. API 详细说明

1.5.1 RKNNLite2 的初始化与对象释放

使用 RKNN Toolkit Lite2 时，首先需要调用 RKNNLite() 方法初始化 RKNNLite 对象，使用完毕后需要调用该对象的 release()` 方法释放资源。 初始化 RKNNLite 对象时，可以设置 verbose 和 verbose_file 参数来输出详细日志信息。verbose 参数用于指定是否在屏幕上输出详细日志信息。如果设置了 verbose_file 参数，并且 verbose` 参数值为 True，则日志信息也会写入该参数指定的文件中。

示例如下：

# 将详细的日志信息输出到屏幕，并同时写入到 inference.log 文件中
rknn_lite = RKNNLite(verbose=True, verbose_file='./inference.log')

# 仅将详细的日志信息输出到屏幕
rknn_lite = RKNNLite(verbose=True)
...
rknn_lite.release()

1.5.2 加载 RKNN 模型

项目	参数名 / 值	说明
API	Load_rknn	加载 RKNN 模型。
参数	path	RKNN 模型文件的路径。
	load_model_in_npu	是否直接加载 NPU 内的 RKNN 模型。此时，path 为 NPU 内 RKNN 模型的路径。仅当 RKNN Toolkit Lite 运行在连接了 NPU 设备的 PC 上，或运行在 RK3399Pro Linux 开发板上时，才可以设置为 True。默认值为 False。
返回值	0	加载成功
	-1	加载失败

示例如下：

ret = rknn_lite.load_rknn('10class_ResNet50_pre.rknn')

1.5.3 初始化运行时环境

在进行模型推理之前，需要先初始化运行时环境，并确定模型运行在哪个芯片平台上。

项目	参数名 / 值	说明
API	init_runtime	初始化运行时环境。确定模型运行的设备信息（芯片型号、设备 ID）。
参数	target	目标硬件平台。目前支持“rk3399pro”、“rk1806”、“rk1808”、“rv1109”、“rv1126”。默认值为 None，会根据应用程序运行所在的开发板自动选择。
	device_id	设备编号。当 PC 连接多个智能设备时，需要指定该参数。设备编号可通过“list_devices”接口查看。默认值为 None。
	async_mode	是否使用异步模式。调用推理接口时包含三个阶段：设置输入图像、模型推理、获取推理结果。启用异步模式后，当前帧的输入设置会与上一帧的推理同时进行，因此除第一帧外，后续每一帧都可以隐藏输入设置耗时，从而提升性能。在异步模式下，每次返回的推理结果都是上一帧的结果。默认值为 False。
返回值	0	成功（原文：加载成功）
	-1	失败（原文：加载失败）

示例如下：

# init runtime environment
print('--> Init runtime environment')
ret = rknn_lite.init_runtime(target=None)
if ret != 0:
    print('Init runtime environment failed')
    exit(ret)
print('done')

1.5.4 模型推理

项目	参数名 / 值	说明
API	inference	对指定输入执行推理，并返回推理结果。
参数	inputs	用于推理的输入（例如由 cv2 处理后的图像）。类型为 list，列表中的元素为 ndarray。
	data_type	输入数据类型。可指定以下值：‘float32’、‘float16’、‘uint8’、‘int8’、‘int16’。默认值为 ‘uint8’。
	data_format	数据模式（格式）。可指定以下值：“nchw”、“nhwc”。默认值为 ‘nhwc’。两者的区别在于 channel（通道）所在的位置。
	inputs_pass_through	将输入透传给 NPU 驱动。在非透传模式下，工具会在将输入传给 NPU 驱动前，对输入执行减均值、除方差等操作；而在透传模式下，不会执行这些操作。该参数的值为数组，例如 input0 透传、input1 不透传时，该参数值为 [1, 0]。默认值为 None，表示所有输入均不透传。
返回值	results	推理结果。类型为 list，列表中的元素为 ndarray。

示例如下（以 resnet50 等分类模型为例，完整代码请参考第 3 节）：

# Inference
print('--> Running model')
outputs = rknn_lite.inference(inputs=[resize_img])

print("outputs[0]:", outputs[0])
print("outputs[0].shape:", outputs[0].shape)
show_outputs(softmax(np.array(outputs[0][0])))

1.5.5 查询 SDK 版本

项目	参数名 / 值	说明
API	get_sdk_version	获取 SDK API 和驱动的版本号。 注意：使用该接口前，需要先完成模型加载和运行时环境初始化。
参数	无
返回值	sdk_version	API 和驱动的版本信息。类型为字符串。

示例如下：

# SDK版本信息获取
...
sdk_version = rknn_lite.get_sdk_version()

返回的 SDK 信息如下所示：

1.5.5 查询 SDK 版本 图11