4、RKNN模型转换基础：核心API与精度关键参数

RKNN-Toolkit2 是 Rockchip 提供的模型转换与推理工具链，它将 PyTorch、ONNX、TensorFlow 等格式的模型转换为 RKNN 格式，以便在 RK3588、RK3566 等 NPU 上高效运行。在 batch size 调整后，模型转换的精度验证必须从理解转换 API 和参数语义开始。本章将深入剖析 rknn.config()、rknn.load_onnx() 等核心 API 的调用方式，重点解释 mean_values、std_values、target_platform 等参数对量化精度和推理结果的影响，并给出可操作的验证流程。

上图展示了 RKNN 模型转换的核心链路：从输入模型开始，经过 config 参数配置、load_onnx 加载、build 构建，最终进入精度验证环节。其中 config 阶段的参数设置直接决定了后续量化与优化的行为，是精度控制的源头。

4.1 核心 API 功能与调用语义

4.1.1 rknn.config()：全局配置的基石

rknn.config() 是转换流程中第一个被调用的 API，它定义了模型转换的全局策略。其关键参数包括：

• mean_values：各通道的均值列表，用于输入归一化。例如 mean_values=[[123.675, 116.28, 103.53]] 对应 ImageNet 统计值。该参数必须与训练时的预处理一致，否则会导致输入分布偏移，精度显著下降。
• std_values：各通道的标准差列表，与 mean_values 配合完成 (x - mean) / std 归一化。若训练时使用 scale=1/255，则此处应设置 std_values=[[255, 255, 255]] 且 mean_values=[[0, 0, 0]]。
• target_platform：指定目标 NPU 平台，如 'rk3588'、'rk3566'。不同平台的指令集和算子支持度不同，错误指定会导致算子映射失败或精度损失。
• quantized_dtype：量化数据类型，可选 'w8a8'（权重和激活均为 8 位）或 'w16a16'（16 位）。8 位量化速度更快但精度损失更大，16 位反之。
• optimization_level：优化等级，0 到 3。等级越高，算子融合和内存复用越激进，但可能引入数值误差。

rknn.config(
    mean_values=[[123.675, 116.28, 103.53]],
    std_values=[[58.395, 57.12, 57.375]],
    target_platform='rk3588',
    quantized_dtype='w8a8',
    optimization_level=3
)

4.1.2 rknn.load_onnx()：模型加载与输入规格声明

rknn.load_onnx() 负责读取 ONNX 模型文件，并声明输入张量的形状和布局。其核心参数为：

• model_path：ONNX 文件路径。
• input_size_list：输入形状列表，例如 [[1, 3, 224, 224]]。当 batch size 调整时，此处的第一维必须与后续 build 阶段的 dataset 对齐。
• input_layout：输入布局，'NCHW' 或 'NHWC'。RKNN 内部默认使用 NHWC，若模型为 NCHW，转换器会自动插入转置算子，但会增加额外开销。
• fp16：是否以半精度加载权重，适用于混合精度场景。

4.2 转换参数对精度的影响机制

4.2.1 mean_values 与 std_values 的匹配性

归一化参数直接决定了输入张量进入网络前的数值范围。假设训练时使用 transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])，则对应的像素值均值和标准差需乘以 255：

mean_values = [0.485*255, 0.456*255, 0.406*255]  # [123.675, 116.28, 103.53]
std_values  = [0.229*255, 0.224*255, 0.225*255]  # [58.395, 57.12, 57.375]

若错误地将 mean_values 设为 [0, 0, 0] 而 std_values 设为 [1, 1, 1]，则输入范围变为 [0, 255] 而非 [-1, 1]，激活值分布偏移，量化误差放大。实际测试中，这种错误会导致 Top-1 准确率下降 5-10 个百分点。

4.2.2 target_platform 的算子映射差异

不同 NPU 平台支持的算子集合不同。例如，RK3588 支持更丰富的激活函数和池化变体，而 RK3566 可能缺少某些算子。当 target_platform 设置错误时，转换器会尝试用多个基础算子组合替代，导致计算图膨胀和精度损失。建议使用 rknn.list_support_platform() 查询当前版本支持的平台列表。

4.2.3 batch size 对量化统计的影响

在 rknn.build() 阶段，dataset 参数提供了校准数据，用于统计激活值的动态范围。当 batch size 增大时，每个 batch 内的样本数增多，统计出的 min/max 更接近真实分布，量化精度通常更高。但若 batch size 过大，校准集样本不足，会导致过拟合于特定 batch 的统计量，反而降低泛化能力。

4.3 精度验证的完整操作流程

4.3.1 准备校准集与参考模型

精度验证的核心是比较 RKNN 模型与原始浮点模型的输出差异。操作步骤如下：

1. 固定随机种子：在 PyTorch 或 ONNX Runtime 中设置 torch.manual_seed(42)，确保每次推理结果可复现。
2. 准备校准集：从验证集中随机抽取 100-500 张图片，覆盖各类别。将图片预处理为与训练一致的格式（resize、crop、normalize）。
3. 获取参考输出：使用原始 ONNX 模型在 CPU 或 GPU 上推理，保存每张图片的输出张量（logits 或 feature map）。
4. 转换 RKNN 模型：按 4.1 节配置参数，调用 rknn.build() 生成 RKNN 模型。
5. NPU 推理：使用 RKNN-Toolkit2 的 inference() 方法，输入相同图片，获取输出。

4.3.2 相似度计算与阈值判定

常用的相似度指标包括余弦相似度和欧氏距离。对于分类任务，还可以比较 Top-5 准确率。推荐使用余弦相似度，因为它对尺度不敏感，能更好地反映方向一致性。

import numpy as np
def cosine_similarity(a, b):
    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

# 假设 ref_output 和 rknn_output 为形状相同的 numpy 数组
cos_sim = cosine_similarity(ref_output.flatten(), rknn_output.flatten())
print(f"Cosine Similarity: {cos_sim:.4f}")

经验阈值：当 cos_sim > 0.99 时，认为精度损失可接受；若 cos_sim < 0.95，则需要检查参数配置或量化策略。

4.4 案例拆解：batch size 从 1 调整到 8 的精度验证

4.4.1 背景与初始现象

某目标检测项目使用 YOLOv5s 模型，原始转换时 batch size 为 1，部署后单帧推理正常。为提升吞吐量，尝试将 batch size 调整为 8。修改 input_size_list 和 dataset 后，发现 RKNN 模型输出的检测框置信度普遍下降 0.1-0.2，部分目标漏检。

4.4.2 分析过程

首先检查 mean_values 和 std_values，确认与训练配置一致。然后对比原始 ONNX 与 RKNN 在相同输入下的输出：

• 原始 ONNX 输出：置信度 0.85，框坐标 [100, 200, 150, 250]
• RKNN 输出：置信度 0.72，框坐标 [98, 198, 152, 252]

余弦相似度为 0.93，低于阈值。进一步检查发现，校准集只有 50 张图片，batch size 为 8 时仅 6 个 batch，统计量波动较大。此外，optimization_level=3 启用了激进算子融合，可能改变了中间张量的数值范围。

4.4.3 操作步骤与结果

1. 将校准集扩充至 200 张图片，确保每个 batch 有足够样本。
2. 将 optimization_level 降为 1，减少算子融合带来的数值扰动。
3. 重新转换并验证，余弦相似度提升至 0.985。
4. 进一步将 quantized_dtype 改为 'w16a16'，余弦相似度达到 0.995，置信度恢复至 0.83。

4.4.4 复盘与经验

本次调优的代价是推理速度下降约 15%（w16a16 比 w8a8 慢），但换来了精度恢复。对于检测任务，置信度下降 0.1 可能直接导致漏检，因此精度优先。经验总结：

• batch size 调整后，优先检查校准集是否充足，建议样本数 ≥ 10 × batch size。
• 优化等级并非越高越好，需在精度和速度间权衡。
• 当精度不达标时，按“校准集 → 优化等级 → 量化位宽”的顺序逐步排查。

4.5 常见误区与总结