4. 模型转换：使用地平线工具链将ONNX/PyTorch/TensorFlow模型转换为地平线中间表示（IR）的完整流程

模型转换是地平线旭日系列芯片部署流程中的第一道关键工序，其目标是将训练框架中产出的浮点模型转换为地平线自定义的中间表示（Intermediate Representation，IR），并在此过程中完成算子映射、权重重排、量化感知准备等操作。IR 文件是后续模型编译、板端运行的唯一输入来源，其质量直接决定最终部署的精度与性能。本章将围绕 ONNX、PyTorch、TensorFlow 三种主流框架，系统讲解转换前的环境准备、转换命令、产物解析、精度验证方法，并结合实际案例剖析常见失败原因与调优策略。

上图展示了模型转换的整体链路：输入侧支持 PyTorch、TensorFlow、ONNX 三种主流格式，经过地平线工具链的 converter、calibrator、evaluator 三大组件处理后，输出包含可视化报告、权重二进制文件和配置元信息的 IR 包。整个流程并非简单的格式翻译，而是涉及算子映射、数据布局调整、量化参数预计算等多个层面的深度处理。下面从核心原理开始逐步展开。

4.1 核心原理：IR 的本质与转换器的工作机制

地平线 IR（Intermediate Representation）是一种面向旭日系列芯片计算架构的图表示，它不同于 ONNX 或 PyTorch 的图结构。IR 的设计目标有三个：一是将训练框架中五花八门的算子收敛到芯片硬件支持的算子集合内；二是将浮点计算图转换为适合定点推理的形态，例如提前插入伪量化节点；三是将张量的内存布局（如 NCHW 与 NHWC）统一为芯片 DMA 引擎更高效的形式。转换器（hb_mapper）本质上是一个图重写引擎，它执行以下操作：

• 算子映射：将 ONNX 的 Conv、BatchNormalization、Relu 等算子映射到地平线 IR 的对应算子；对于不支持的算子，尝试拆解为多个基础算子组合。
• 图优化：进行常量折叠、算子融合（如 Conv+BN+ReLU 融合为单个算子）、冗余节点消除等操作，减少推理时的内存访问次数。
• 量化锚点插入：在激活值可能发生较大动态范围变化的位置插入伪量化节点，为后续校准过程提供统计锚点。
• 数据布局转换：将输入张量的通道维从第三维（NCHW）转换为第四维（NHWC），以匹配旭日芯片的卷积加速器数据通路。

转换器的工作方式分为两种模式：普通模式（float 模型直接转换）和 量化感知模式（QAT 模型转换）。普通模式适用于先转换后量化的流程，工具链会在 IR 中保留浮点精度信息；量化感知模式则直接读取训练时已插入的伪量化节点，保留其 scale 和 zero_point 参数。理解这一机制有助于后续排查转换失败时的问题根源——多数失败并非工具链 bug，而是模型结构超出了工具链的算子支持范围。

4.2 操作流程：从环境准备到产物验证的完整步骤

模型转换的标准流程可以拆解为五个阶段，每个阶段都有明确的输入输出和检查点。以下以 ONNX 模型为例，给出完整命令序列。

4.2.1 环境准备

地平线工具链推荐在 Docker 环境中运行，以避免宿主机依赖冲突。标准做法是拉取地平线提供的镜像并启动容器：

# 拉取工具链镜像（以 x3 版本为例）
docker pull horizonrobotics/horizon_x3_toolchain:latest

# 启动容器并挂载模型目录
docker run -it --name hb_converter \
  -v /host/models:/workspace/models \
  -v /host/output:/workspace/output \
  horizonrobotics/horizon_x3_toolchain:latest /bin/bash

进入容器后，验证工具链是否可用：

hb_mapper --help
# 预期输出包含 version、convert、infer 等子命令

4.2.2 模型预处理

在转换前，需要确认输入模型的规范性。对于 ONNX 模型，建议先用 onnxsim 进行简化，消除冗余的 Shape 节点和 Constant 节点：

python3 -m onnxsim model.onnx model_sim.onnx \
  --overwrite-input-shape "1,3,224,224" \
  --check-n 3

同时需要准备一个校准数据集的描述文件（通常为 calibration_data.txt），每行记录一张图片的路径。校准集一般选取 100~200 张具有代表性的图片，覆盖各类别和光照条件。对于分类模型，建议从训练集中随机抽取；对于检测模型，则需确保包含不同尺度和遮挡情况的目标。

4.2.3 编写转换配置 YAML

转换配置是控制整个转换过程的中心文件，核心字段如下：

# model_converter.yaml
model:
  onnx_model: './model_sim.onnx'
  input_shape: [1, 3, 224, 224]
  input_name: 'input'
  output_name: 'output'

calibration:
  cal_data_dir: './calibration_images/'
  cal_data_type: 'float32'
  preprocess:
    type: 'normalize'
    mean: [0.485, 0.456, 0.406]
    std: [0.229, 0.224, 0.225]

compiler:
  optimization_level: 'O2'
  quantize_method: 'per_channel'

其中 input_shape 必须与模型实际输入一致，preprocess 中的 mean/std 必须与训练时完全一致，否则会导致精度严重下降。quantize_method 支持 per_tensor 和 per_channel 两种，per_channel 精度更高但计算量略大，旭日 X3 芯片两者均支持。

4.2.4 执行转换

运行转换命令：

hb_mapper convert --model-type onnx \
  --model ./model_sim.onnx \
  --config ./model_converter.yaml \
  --output-dir ./output/ir

转换过程中，终端会打印每个算子的映射日志。重点关注两类信息：WARNING 表示算子被拆解或替换，ERROR 表示算子无法映射。转换完成后，输出目录中会生成以下文件：

4.2.5 精度验证

转换完成后，必须使用工具链自带的评估器对比浮点模型与量化模型的输出差异。评估命令如下：

hb_mapper infer --model ./output/ir/model_quantized.onnx \
  --input ./test_images/ \
  --output ./output/predictions/

同时用原始 ONNX 模型对同一批图片进行推理，计算两者的余弦相似度或 Top-1 准确率差异。一般要求量化模型相对浮点模型的精度损失不超过 1%（分类任务）或 mAP 下降不超过 2%（检测任务）。

4.3 案例拆解：ResNet50 转换实战与精度调优

下面通过一个完整的 ResNet50 分类模型转换案例，展示从原始 PyTorch 模型到 IR 产物的全过程，并重点分析一次精度异常问题的排查思路。

背景与约束：某安防项目需要在旭日 X3 上部署 ResNet50 进行人员属性识别。训练框架为 PyTorch 1.9，模型输入为 224×224×3，训练时采用 ImageNet 标准的 mean=[0.485,0.456,0.406]、std=[0.229,0.224,0.225] 归一化。项目要求 INT8 量化后 Top-1 准确率不低于浮点模型的 98%。

初始现象：首次转换后，量化模型在验证集上的 Top-1 准确率为 68.3%，而浮点模型为 76.5%，精度损失高达 8.2%，远超 2% 的容忍线。

分析过程：首先检查校准报告，发现第 3 个残差块的输出激活值动态范围异常大（min=-12.3, max=11.8），而其他层大多在 ±5 以内。进一步查看模型结构，发现该残差块之后紧跟一个 Downsample 路径，其中包含一个 stride=2 的 Conv 层。校准图片中，该层输出在某些样本上出现极端值，导致量化 scale 被拉大，低比特量化时精度损失严重。

实际操作步骤：

1. 将校准集从随机选取的 100 张增加到 500 张，并确保包含 20% 的暗光样本和 15% 的过曝样本，使激活值分布更接近真实场景。
2. 在 YAML 配置中将 quantize_method 从 per_tensor 改为 per_channel，使每个输出通道拥有独立的 scale。
3. 对 Downsample 路径中的 Conv 层，在配置中指定 activation_quant: false，即对该层输出不进行量化，保持浮点计算（旭日 X3 支持混合精度推理）。

结果对比：经过上述调整后，量化模型 Top-1 准确率提升至 75.8%，相对浮点模型仅损失 0.7%，满足项目要求。推理耗时从 12.3ms 略微增加至 13.1ms，仍在 15ms 的预算内。

风险与代价：混合精度策略会增加约 6% 的内存带宽消耗，且 per_channel 量化会略微增加编译时间。但相比精度损失，这些代价是可接受的。

复盘经验：转换前的校准集构建是精度保障的第一道防线，不能简单随机抽样；遇到异常层时，优先检查激活值分布，而非盲目调整量化算法。

4.4 常见误区与总结复盘

模型转换环节的常见误区往往源于对工具链机制的不了解，以下列出高频问题及应对策略：