第4章模型转换入门

4、模型转换入门：ONNX模型格式、模型导出与转换工具（如onnx2npu）、精度校验

模型转换，说白了就是让AI模型换个“语言”，从训练框架的“方言”变成芯片能听懂的“普通话”。

我刚开始接触这活儿时，觉得不就是改个文件格式嘛，有啥难的？结果第一次把PyTorch模型转成ONNX，跑在NPU上，精度直接掉了两个点。嗯，从那以后我再也不敢小看这一步了。

4.1 ONNX模型格式：AI模型的“通用语言”

ONNX（Open Neural Network Exchange）是什么？你可以把它想象成AI界的“USB接口”。不管你的模型是用PyTorch、TensorFlow还是其他框架训练的，只要导出成ONNX格式，就能在不同推理引擎和芯片上跑起来。

我个人习惯把ONNX看作一个“中间表示层”。它不关心你怎么训练的，只关心网络结构长什么样、权重是多少。说白了，它就是个计算图，把卷积、池化、全连接这些算子串起来。

  ONNX的核心优势：
  框架无关：一次导出，到处运行
算子标准化：定义了AI模型常用的操作集合
生态成熟：几乎所有主流框架和芯片都支持

我在项目中遇到过一个问题：ONNX版本不兼容。比如你用ONNX opset 15导出的模型，芯片的推理引擎只支持opset 11。结果就是模型加载失败，或者某些算子被降级成低效实现。所以，导出前一定要确认芯片支持的opset版本。

4.2 模型导出：从训练框架到ONNX

模型导出这一步，其实没那么玄乎。以PyTorch为例，核心就几行代码。但这里面的坑，我踩过不少。

import torch
import torch.onnx

# 假设你有一个训练好的模型
model = YourTrainedModel()
model.eval()

# 创建一个示例输入
dummy_input = torch.randn(1, 3, 224, 224)

# 导出ONNX
torch.onnx.export(
    model,
    dummy_input,
    "model.onnx",
    export_params=True,
    opset_version=11,
    do_constant_folding=True,
    input_names=['input'],
    output_names=['output'],
    dynamic_axes={
        'input': {0: 'batch_size'},
        'output': {0: 'batch_size'}
    }
)

这里有几个关键点，我特别想强调：

model.eval()：一定要切换到推理模式。我见过有人忘了这步，结果导出的模型里还带着Dropout和BatchNorm的训练状态，推理结果完全不对。
dummy_input：这个示例输入的shape要和实际推理时一致。如果你后面要支持动态batch，记得设置dynamic_axes。
opset_version：选芯片支持的版本。我建议先查芯片文档，再决定用哪个版本。

小技巧：导出后，可以用onnxruntime跑一下，验证模型能不能正常推理。我每次都会做这一步，能提前发现很多问题。

4.3 转换工具：onnx2npu 实战

拿到ONNX模型后，下一步就是转成芯片能跑的格式。不同芯片厂商都有自己的工具链，比如华为的MindStudio、瑞芯微的RKNN Toolkit、地平线的OE包等。我这里以通用的“onnx2npu”为例，讲讲转换流程。

转换工具的核心工作，说白了就是三件事：

解析ONNX图：把计算图读进来
算子映射：把ONNX算子映射到NPU支持的算子
量化优化：把FP32的权重转成INT8，同时做图优化

# 伪代码示例：onnx2npu转换流程
from onnx2npu import Converter

converter = Converter(
    model_path="model.onnx",
    output_path="model.npu",
    precision="int8",          # 量化精度
    calibration_data="calib.bin",  # 校准数据
    input_shape=[1, 3, 224, 224]
)

# 开始转换
converter.convert()

# 保存转换报告
converter.save_report("conversion_report.json")

我曾经遇到过一个坑：模型里有个自定义算子，芯片不支持。结果转换工具直接报错，说“Unsupported operator”。怎么办？

方案一：用芯片支持的算子替换。比如把某个自定义激活函数换成ReLU或LeakyReLU。
方案二：写一个自定义算子插件。这需要芯片厂商提供SDK，我一般只在万不得已时才用。
方案三：回退到CPU执行。有些工具链支持“算子回退”，把不支持的算子留在CPU上跑。但这样会降低性能，我建议尽量少用。

注意：转换过程中，工具会做很多图优化，比如算子融合、常量折叠。这些优化对性能提升很大，但也可能引入精度误差。所以，转换后一定要做精度校验。

4.4 精度校验：别让模型“变傻”了

模型转换后，精度掉了怎么办？这是我最常被问到的问题。精度校验，说白了就是对比转换前后的模型输出，看看差异有多大。

我一般用余弦相似度和最大绝对误差这两个指标：

import numpy as np

def check_accuracy(original_output, npu_output):
    # 余弦相似度
    cos_sim = np.dot(original_output.flatten(), npu_output.flatten()) / (
        np.linalg.norm(original_output) * np.linalg.norm(npu_output)
    )
    
    # 最大绝对误差
    max_error = np.max(np.abs(original_output - npu_output))
    
    print(f"余弦相似度: {cos_sim:.6f}")
    print(f"最大绝对误差: {max_error:.6f}")
    
    if cos_sim < 0.99:
        print("警告：精度可能有问题，建议检查量化参数")
    elif max_error > 0.1:
        print("注意：存在较大误差，建议检查特定层")
    else:
        print("精度校验通过")

精度下降的原因，我总结了几种常见情况：

问题类型	典型表现	解决方案
量化误差	整体精度下降，但分布均匀	使用更好的校准数据集，或尝试混合精度
算子精度差异	特定层输出偏差大	检查该层的算子实现，考虑替换
数值溢出	输出出现NaN或Inf	检查输入范围，调整量化参数
图优化错误	转换后模型结构变化	关闭某些优化选项，逐步排查

我个人习惯的做法是：先用100张图片做快速校验，如果精度没问题，再用完整测试集做最终验证。这样能快速发现问题，不用每次都跑全量数据。

避坑指南：我曾经遇到过一个案例，模型转换后精度看起来没问题，但实际部署时发现某些输入会触发数值溢出。后来排查发现，是校准数据分布和实际数据分布不一致导致的。所以，校准数据一定要覆盖实际场景。

4.5 知识体系总览

为了让你更直观地理解模型转换的完整流程，我画了一张图：

模型转换这件事，说难不难，说简单也不简单。关键是要理解每个环节在做什么，以及可能出什么问题。我见过太多人一上来就转模型，结果精度不对、性能不达标，最后花大量时间排查。

我的建议是：先小规模验证，再大规模转换。拿一个小模型跑通全流程，确认每个环节都没问题，再处理大模型。这样能省下不少时间。

📚 课程目录

4、模型转换入门：ONNX模型格式、模型导出与转换工具（如onnx2npu）、精度校验

4.1 ONNX模型格式：AI模型的“通用语言”

4.2 模型导出：从训练框架到ONNX

4.3 转换工具：onnx2npu 实战

4.4 精度校验：别让模型“变傻”了

4.5 知识体系总览