如何用RKNN Toolkit完成RV1126/RV1109模型转换与量化校准？

在瑞芯微RV1126和RV1109这类边缘AI芯片上部署神经网络时，模型通常需要从训练框架导出的浮点格式转换为NPU可执行的rknn格式。RKNN Toolkit是官方提供的模型转换与仿真工具，支持Caffe、TensorFlow、TensorFlow Lite、ONNX、Darknet以及PyTorch等主流框架。仅做格式转换并不能充分发挥NPU的定点算力，量化校准才是决定模型落地后精度表现的核心环节。本文将围绕模型导入、量化参数配置、校准数据集准备以及板上验证展开，给出可直接参考的实现代码。

一、模型转换的基本流程

RKNN Toolkit的模型转换通常分为四步：初始化RKNN对象、加载源模型、配置量化与预处理参数、导出rknn文件。以ONNX模型为例，核心代码如下：

from rknn.api import RKNN

# 创建RKNN对象
rknn = RKNN(verbose=True)

# 加载ONNX模型，需指定输入输出节点名称
ret = rknn.load_onnx(model='./model.onnx',
                     inputs=['input'],
                     input_size_list=[[1, 3, 224, 224]],
                     outputs=['output'])
if ret != 0:
    print('Load ONNX model failed')
    exit(ret)

# 配置预处理参数与量化类型
ret = rknn.config(mean_values=[[123.675, 116.28, 103.53]],
                  std_values=[[58.395, 57.12, 57.375]],
                  quantized_dtype='asymmetric_quantized-8',
                  target_platform='rv1126')
if ret != 0:
    print('Config failed')
    exit(ret)

# 执行模型构建
ret = rknn.build(do_quantization=True, dataset='./calib_dataset.txt')
if ret != 0:
    print('Build failed')
    exit(ret)

# 导出rknn模型
ret = rknn.export_rknn('./model.rknn')
if ret != 0:
    print('Export failed')
    exit(ret)

rknn.release()

上述流程中的mean_values和std_values必须与训练阶段的归一化方式完全一致。如果训练时使用0到1归一化，mean_values应设为0，std_values设为1；若使用ImageNet常用的减均值除标准差，则需要根据实际像素顺序填写。对于RV1126和RV1109，target_platform必须指定为rv1126，否则生成的模型可能包含NPU不支持的算子映射。

另一个容易被忽略的点是输入节点名称。导出ONNX时若使用了动态输入，RKNN Toolkit需要明确的input_size_list来固定形状。建议在导出ONNX时就将batch维和空间尺寸固定，避免转换阶段的形状推导失败。对于PyTorch模型，可以先导出ONNX再转换，也支持直接加载pt文件，但推荐使用ONNX作为中间格式以降低版本依赖。

二、量化校准的关键配置与精度调优

RV1126/RV1109的NPU对int8和非对称量化支持较完善，量化推理速度远高于float16。RKNN Toolkit默认的asymmetric_quantized-8会使用校准数据集统计每一层的激活值范围，进而将浮点权重和激活映射到int8区间。校准数据集的代表性直接决定量化后精度，建议从训练集或真实场景数据中随机抽取200至500张图片，并保持与训练预处理一致。

import os
import numpy as np
from PIL import Image

calib_dir = './calib_images'
dataset_file = './calib_dataset.txt'

image_list = sorted(os.listdir(calib_dir))[:300]
with open(dataset_file, 'w') as f:
    for img_name in image_list:
        img_path = os.path.join(calib_dir, img_name)
        img = Image.open(img_path).convert('RGB')
        img = img.resize((224, 224))
        img_array = np.array(img).astype(np.float32)
        # 与训练预处理保持一致的归一化
        img_array = (img_array - [123.675, 116.28, 103.53]) / [58.395, 57.12, 57.375]
        img_array = np.transpose(img_array, (2, 0, 1))  # HWC to CHW
        flat = img_array.flatten()
        line = ' '.join([str(v) for v in flat])
        f.write(line + '\n')
print('calibration dataset written to', dataset_file)

对于分类网络，这种简单的随机抽校通常足够。对于检测或分割网络，建议按类别均衡采样，尤其是小目标或稀有类别占比过少时，量化后容易在该类别上出现明显掉点。校准图片数量并非越多越好，超过一定规模后精度提升趋缓，但构建时间会线性增加。一般300张左右即可覆盖大部分场景。

如果int8量化后精度下降超过可接受范围，可以尝试混合量化。RKNN Toolkit支持通过hybrid_quantization_step1和hybrid_quantization_step2接口把部分敏感层保留为float16，其余层使用int8。敏感层通常位于网络头部或输出层，也可以通过逐层精度对比来定位。混合量化需要额外调用量化配置步骤，代码示例如下：

from rknn.api import RKNN

rknn = RKNN(verbose=True)
rknn.load_onnx(model='./model.onnx', inputs=['input'],
               input_size_list=[[1, 3, 224, 224]], outputs=['output'])
rknn.config(mean_values=[[123.675, 116.28, 103.53]],
            std_values=[[58.395, 57.12, 57.375]],
            quantized_dtype='asymmetric_quantized-8',
            target_platform='rv1126')

# 第一步：生成混合量化配置文件
ret = rknn.hybrid_quantization_step1(dataset='./calib_dataset.txt')
if ret != 0:
    print('hybrid step1 failed')
    exit(ret)

# 修改生成的配置文件，将部分层设为float16后保存

# 第二步：根据修改后的配置重新构建
ret = rknn.hybrid_quantization_step2(model_input='./model.model',
                                     data_input='./model.data',
                                     model_quantization_cfg='./model.quantization.cfg')
if ret != 0:
    print('hybrid step2 failed')
    exit(ret)

rknn.export_rknn('./model_hybrid.rknn')
rknn.release()

执行完hybrid_quantization_step1后，工具会在当前目录生成model.model、model.data以及模型名.quantization.cfg等文件，其中cfg文件列出了每一层算子的量化类型。把需要保持精度的层对应的类型从int8改为float16，再调用hybrid_quantization_step2即可。混合量化能有效恢复精度，但代价是这些层会占用更多NPU资源，推理速度也会下降，需要在实际硬件上测试权衡。

三、模拟器推理与板上部署验证

生成rknn文件后，不要直接部署到设备。RKNN Toolkit提供了仿真器，可以在PC端模拟NPU推理，提前发现算子兼容性和输出数值问题。通过init_runtime即可加载模型并执行推理，输入输出均为numpy数组，方便与原始框架结果对比。

from rknn.api import RKNN
import numpy as np
import cv2

rknn = RKNN(verbose=True)
rknn.load_rknn('./model.rknn')
ret = rknn.init_runtime(target='rv1126')
if ret != 0:
    print('init runtime failed')
    exit(ret)

# 读取并预处理图片
img = cv2.imread('./test.jpg')
img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
img = cv2.resize(img, (224, 224))
img = img.astype(np.float32)
img = (img - [123.675, 116.28, 103.53]) / [58.395, 57.12, 57.375]
img = np.transpose(img, (2, 0, 1))
img = np.expand_dims(img, axis=0)

outputs = rknn.inference(inputs=[img])
print('output shape:', outputs[0].shape)
print('top prediction:', np.argmax(outputs[0][0]))
rknn.release()

仿真器输出与原始框架输出之间的余弦相似度或最大误差可以作为量化精度评估指标。通常int8量化后分类网络top1误差增加不超过1%可以接受，检测网络mAP下降不超过2%尚在可控范围。如果误差超标，应回头检查校准数据集和预处理参数，而不是直接上板。

仿真通过后，将rknn模型拷贝到RV1126或RV1109设备，使用RKNN Runtime的C API或Python API加载。板上推理时要注意NPU内存分配，同一时间只能运行一个模型实例，频繁切换模型会导致额外开销。对于多模型任务，可以考虑模型融合或将多个小模型合并为一个rknn文件。此外，板上运行前务必使用sync或刷写确保模型文件完整，否则可能出现加载失败但无明确报错的情况。

四、常见问题与调试技巧

模型转换过程中最常见的错误是算子不支持。RV1126和RV1109的NPU支持算子列表有限，部分新颖激活函数或自定义算子无法直接映射。遇到Unsupported operator错误时，可以查看详细日志定位到具体层名，然后在训练框架中替换为等价算子，例如把HardSwish替换为ReLU6近似，或在ONNX中做图简化。RKNN Toolkit也提供自定义算子接口，但开发成本较高，一般只在无法绕开时使用。

另一个高频问题是输入layout错误。RKNN默认使用NCHW格式，而OpenCV读取图片是HWC，需要显式transpose。如果预处理时忘记转置，推理结果会完全错误，但仿真器不会报错，因为数据形状可能仍然匹配，只是数值含义错位。建议在仿真阶段逐层输出中间特征与原始框架对比，而不是只看最终输出。

关于量化校准，还需注意校准数据文件中的每一行必须是一张图片展开后的一维浮点数组，长度等于输入元素个数，顺序为NCHW。如果输入尺寸较大，文件体积可能很大，此时可以改用npy或内存方式传递校准数据，减少磁盘IO。RKNN Toolkit某些版本支持dataset参数直接传numpy数组列表，可查阅对应版本文档确认。调试过程中打开verbose=True可以输出每一层的量化范围和统计信息，有助于快速定位异常层。

RKNN ToolkitRV1126量化校准修改时间：2026-08-30 17:41:58