4、模型转换入门：从ONNX/PyTorch/TensorFlow到RKNN的转换流程、量化选项、输出配置与常见错误排查

RKNN-Toolkit2 是 Rockchip 提供的模型转换与推理工具链，其核心作用是将训练框架中的浮点模型转换为能够在 RK3588、RK3566 等 NPU 上高效运行的 RKNN 格式。转换过程并非简单的格式翻译，而是涉及计算图解析、算子映射、权重重排、量化校准以及目标硬件适配的复合工程。理解这一流程的内在逻辑，是后续进行推理时延优化的前提——因为许多性能瓶颈（如算子碎片化、量化精度损失、内存访问不连续）在转换阶段就已埋下伏笔。

上图展示了 RKNN 转换的整体链路。从左侧的多种训练框架输入，经过中间的解析、量化与平台配置，最终输出右侧的板端可执行文件。值得注意的是，转换不是一次性的“导出”动作，而是一个需要反复迭代的调优过程。实际项目中，我们往往需要根据 NPU 的算子支持列表、内存带宽和量化敏感度，对原始模型结构进行针对性调整，才能获得既满足精度要求又具备低时延的 RKNN 模型。

4.1 转换前的模型准备与格式选择

核心原理：为什么推荐 ONNX 作为中间格式

RKNN-Toolkit2 虽然支持直接解析 PyTorch 和 TensorFlow 模型，但在工程实践中，ONNX 是最稳定、最可控的中间表示。原因有三：其一，ONNX 的计算图是静态的，便于工具链进行算子融合和内存规划；其二，PyTorch 的动态控制流（如 if/else、for 循环）在直接 trace 时容易丢失或产生错误的结构，而 ONNX 导出过程会强制将动态图转换为静态图；其三，ONNX 的算子集（opset）版本管理清晰，便于排查算子兼容性问题。

操作流程：从 PyTorch 到 ONNX 的标准步骤

import torch
import torchvision.models as models

# 1. 加载模型并设为评估模式
model = models.resnet18(pretrained=True).eval()

# 2. 构造示例输入（注意与训练时的预处理一致）
dummy_input = torch.randn(1, 3, 224, 224)

# 3. 导出 ONNX
torch.onnx.export(
    model,
    dummy_input,
    "resnet18.onnx",
    opset_version=15,
    do_constant_folding=True,  # 折叠常量，减小模型体积
    input_names=["input"],
    output_names=["output"],
    dynamic_axes={"input": {0: "batch"}, "output": {0: "batch"}}
)
print("ONNX 导出完成")

导出后，建议使用 onnxsim 工具进行图简化，去除冗余的 Shape 节点和恒等映射，这能显著减少后续 RKNN 转换时的解析时间，并避免一些不必要的算子拆分。

案例拆解：TensorFlow 模型转换的“坑”

某项目需要将 TensorFlow 2.x 训练的 EfficientNet-B0 转换为 RKNN。初始直接使用 model.save('model.h5') 保存的模型进行转换，结果报错“Unknown layer: KerasLayer”。分析后发现，TF2 的 SavedModel 格式包含了 Keras 元数据，RKNN 解析器无法直接识别。解决方案是：先使用 tf.compat.v1.graph_util.convert_variables_to_constants 将模型冻结为 .pb 文件，再通过 tf2onnx 工具转换为 ONNX，最后才交给 RKNN-Toolkit2。整个过程耗时 2 小时，但避免了后续反复排错。

4.2 RKNN 转换配置与量化选项详解

核心原理：量化如何影响时延与精度

RKNN 支持 fp16 和 int8 两种量化格式。int8 量化能将模型体积缩小 4 倍，并利用 NPU 的整数计算单元大幅提升吞吐量，但会引入精度损失。量化过程分为量化感知训练（QAT）和训练后量化（PTQ）。RKNN-Toolkit2 默认采用 PTQ，需要提供校准数据集（通常 100-500 张代表性图片），工具会统计每层激活值的动态范围，从而确定缩放因子（scale）和零点（zero point）。

操作流程：rknn.config 与 rknn.build 的关键参数

from rknn.api import RKNN

rknn = RKNN()
# 1. 配置转换参数
rknn.config(
    mean_values=[[123.675, 116.28, 103.53]],  # 与训练预处理一致
    std_values=[[58.395, 57.12, 57.375]],
    target_platform='rk3588',                 # 目标 NPU 平台
    quantized_dtype='int8',                   # 可选 'fp16', 'int8'
    quantized_algorithm='normal',             # 可选 'normal', 'mmse', 'kl_divergence'
    optimization_level=3,                     # 0-3，3 为最高优化
    quantized_method='layer',                 # 逐层量化
    cpu_quantize=False                        # 是否强制 CPU 算子量化
)

# 2. 加载 ONNX 模型
ret = rknn.load_onnx(model='resnet18.onnx')
assert ret == 0, "加载失败"

# 3. 构建 RKNN 模型（此步骤执行量化）
ret = rknn.build(do_quantization=True, dataset='calib_data.txt')
assert ret == 0, "构建失败"

# 4. 导出 RKNN 文件
ret = rknn.export_rknn('resnet18.rknn')
assert ret == 0, "导出失败"
rknn.release()

其中 quantized_algorithm 的选择对精度影响显著：normal 速度最快但精度一般；kl_divergence 适合分类模型；mmse（最小均方误差）适合回归或检测模型。如果模型对精度极其敏感，可以尝试 quantized_method='channel' 进行逐通道量化，但会增加模型体积和计算开销。

案例拆解：YOLOv5s 的量化调优实战

某安防项目需要将 YOLOv5s 部署到 RK3588，目标帧率 ≥ 30 FPS。初始使用默认配置（normal 算法，layer 量化），转换后 mAP 从 0.72 降至 0.58，且检测框偏移明显。分析过程：

1. 现象确认：使用 300 张真实监控截图作为校准集，量化后模型在夜间场景漏检率高达 40%。
2. 原因定位：YOLOv5 的 Detect 头包含大量动态尺寸的 anchor 网格，逐层量化时这些层对误差敏感。
3. 调整策略：将 quantized_algorithm 改为 mmse，并将 quantized_method 改为 channel，同时将校准集扩充至 500 张并加入夜间增强数据。
4. 结果对比：mAP 回升至 0.68，帧率维持在 32 FPS，满足需求。

复盘经验：量化不是“一键完成”的，需要针对模型结构特点进行多次实验。对于检测模型，建议优先尝试 mmse 算法，并检查 Detect 头是否被错误地强制量化。

4.3 输出配置与板端推理接口

核心原理：RKNN 输出的数据布局与内存管理

RKNN 模型的输出张量默认采用 NHWC 布局（与 TensorFlow 一致），而 PyTorch 模型通常为 NCHW。在板端使用 C API 推理时，需要特别注意输出数据的维度顺序。此外，NPU 输出的数据可能未对齐到 16 字节，直接使用会导致内存访问异常。RKNN Runtime 提供了 rknn_outputs_get 接口，可以设置 want_float 属性来控制输出格式（float32 或 uint8）。

操作流程：Python API 推理示例

from rknnlite.api import RKNNLite

# 初始化
rknn_lite = RKNNLite()
ret = rknn_lite.load_rknn('resnet18.rknn')
assert ret == 0, "加载失败"
ret = rknn_lite.init_runtime(core_mask=RKNNLite.NPU_CORE_0_1_2)
assert ret == 0, "初始化失败"

# 推理
import numpy as np
input_data = np.random.randn(1, 3, 224, 224).astype(np.float32)
# 注意：输入需要按 mean/std 归一化
outputs = rknn_lite.inference(inputs=[input_data])
print(outputs[0].shape)  # 输出为 (1, 1000) 的 float32 数组

在 C 环境中，使用 rknn_inputs_set 时需设置 pass_through 标志。若输入是 uint8 格式（如摄像头原始数据），可设置 type=RKNN_TENSOR_UINT8 并配合 mean/std 参数，让 NPU 自动完成归一化，减少 CPU 负担。

常见误区与排查清单