RKNN（Rockchip Neural Network）是瑞芯微（Rockchip）针对其芯片平台设计的神经网络推理框架，支持将主流深度学习框架训练的模型转换为RKNN格式，以便在瑞芯微芯片上高效运行。转换过程涉及模型优化、量化和适配硬件加速器。

1、转换工具安装

在Linux系统中，新建虚拟环境（conda或者python env虚拟环境下）安装RKNN-Toolkit工具包，瑞芯微官方提供Python环境下的工具链：

pip install rknn-toolkit2  # 根据芯片型号选择版本
 

2、模型准备

准备模型文件 确保拥有冻结的模型（.pt文件）或训练检查点（.ckpt）。冻结模型需包含完整的计算图和权重。使用官方ultralytics的模型进行导出onnx没有问题，在后处理阶段对conf_thresh和nms都进行过滤。

另外，也可以参考野火鲁班猫的版本：

https://doc.embedfire.com/linux/rk356x/Ai/zh/latest/lubancat_ai/example/yolo11.html#id1

模型导出使用专门针对rknn优化的 ultralytics_yolo11 。

3、校准数据集

生成图片校准txt文件，在量化过程中需要使用。

import os

img_dir = './calibration_img'#校准图片位置
output_file = './dataset.txt'

extensions = ('.jpg', '.jpeg', '.png', '.bmp')

img_paths = [
    f for f in os.listdir(img_dir)
    if f.lower().endswith(extensions)
]

img_paths.sort()

with open(output_file, 'w') as f:
    for filename in img_paths:
        path = './{}/{}'.format(os.path.basename(img_dir), filename)
        f.write(path + '\n')

print(f'共写入 {len(img_paths)} 张图片路径到 {output_file}')

4、转换成rknn模型

编写转换脚本 创建Python脚本，使用RKNN-Toolkit加载原始模型并配置转换参数：

#安装了rknn toolkit使用
from rknn.api import RKNN
import os

# 配置路径
ONNX_PATH = "./onnx_models/640/yolov12n-640.onnx"  # 输入ONNX模型
RKNN_PATH = "./rknn_models/640/yolov12n-640.rknn"  # 输出RKNN模型
CALIB_PATH = "./dataset.txt"  # 校准图路径文件


def main():
    # 1. 创建RKNN实例，开启日志（方便调试）
    rknn = RKNN(verbose=True)
    # 2. 配置NPU运行参数（针对RK3588优化）
    print("=== 配置模型参数 ===")
    rknn.config(
        mean_values=[[0, 0, 0]],  # 归一化均值（YOLO11用0）
        std_values=[[255, 255, 255]],  # 归一化标准差（YOLO11用255，对应输入除以255）
        target_platform="rk3588",  # 目标硬件
        #optimization_level=3,  # 优化级别（3为最高）
        #quantize_input_node=True,  # 对输入节点量化（提升速度）
        # 若需混合精度量化（部分层用FP16），添加以下行：
        # precision_mode="hybrid",
        # float_dtype="fp16"
    )
    # 3. 加载ONNX模型（关键：指定输入尺寸和归一化参数）
    print("=== 加载ONNX模型 ===")
    ret = rknn.load_onnx(
        model=ONNX_PATH,
        # 声明输入节点信息：名称（从Netron查看）、尺寸、数据类型
        #inputs=["images"],  # YOLO11的输入节点名固定为images
        #input_size_list=[[3,320, 320]],  # NCHW格式

    )
    if ret != 0:
        print("加载ONNX模型失败！")
        exit(ret)



    # 4. 构建模型（量化核心步骤，耗时约10分钟）
    print("=== 构建模型 ===")
    ret = rknn.build(
        do_quantization=True,  # 开启INT8量化
        dataset=CALIB_PATH,  # 校准数据集
        #quantized_dtype="int8"  # 量化类型
    )
    if ret != 0:
        print("构建模型失败！")
        exit(ret)

    # 5. 导出RKNN模型
    print("=== 导出RKNN模型 ===")
    ret = rknn.export_rknn(RKNN_PATH)
    if ret != 0:
        print("导出模型失败！")
        exit(ret)

    # 6. 可选：测试模型在NPU上的推理效果（验证精度）
    print("=== 初始化运行时 ===")
    ret = rknn.init_runtime()
    if ret != 0:
        print("初始化运行时失败！")
        exit(ret)

    # 用一张测试图验证（可选）
    import cv2
    import numpy as np
    img = cv2.imread("platalea_minor.jpg")  # 随便选一张校准图
    img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    img = cv2.resize(img, (640, 640))
    #img = img.transpose(2, 0, 1)  # HWC→CHW
    img = img.astype(np.float32) / 255.0  # 归一化
    img = np.expand_dims(img, axis=0)  # 加batch维度

    print("=== 测试推理 ===")
    outputs = rknn.inference(inputs=[img])
    print(f"推理输出形状：{outputs[0].shape}")  # 应输出(1, 8400, 85)

    # 7. 释放资源
    rknn.release()
    print("=== 转换完成 ===")


if __name__ == "__main__":
    main()

关键参数说明

• target_platform: 指定目标硬件（如rk3566、rk3588等）。
• do_quantization: 启用量化可减少模型大小并提升推理速度。
• dataset: 量化时需提供校准数据集路径（文本文件列出样本路径）。

5、验证转换结果

以上代码中已经加了验证代码。

可以参考https://github.com/airockchip/rknn-toolkit2/tree/master/rknpu2/examples/rknn_yolov5_demo

https://gitee.com/LubanCat/lubancat_ai_manual_code

6、常见问题处理

1、板卡推理运行AttributeError: /usr/lib/librknnrt.so: undefined symbol: rknn_set_input_shapes
方法：使用 rknn-Toolkit2 的版本和板卡推理使用的 librknnrt.so 库版本保持一致。使用pip install进行升级或者降级；或者需要将librknnrt.so拷贝到对应的位置；

在linux平台上，我们需要添加librknnrt.so(鲁班猫板卡系统默认已经有，可以更新下)， 该文件从 RKNPU2 的runtime/XXXX/Linux/rknn_server目录下获取,或者教程配套例程中获取。为避免其他问题，
2、关于警告

W RKNN: Output(269/271/273): size_with_stride larger than model origin size

这个警告不影响结果，是 RKNN 内存对齐的提示，输出 tensor 因为 stride 对齐导致分配内存略大于实际数据大小，正常现象。

参考文献

1. https://doc.embedfire.com/linux/rk356x/Ai/zh/latest/lubancat_ai/env/toolkit2.html#id5
2. https://blog.csdn.net/weixin_46991199/article/details/158506610
3. https://github.com/airockchip/rknn-toolkit2/tree/master/rknpu2/examples/rknn_yolov5_demo
4. https://gitee.com/LubanCat/lubancat_ai_manual_code