📚 课程目录第1章课程导入

1. 课程导入

在智能驾驶与边缘AI量产项目中，算法团队通常使用 PyTorch、ONNX 等框架完成模型训练与验证，而真正部署到地平线征程（Journey）系列芯片上时，模型必须经过一套完整的转换与编译流程，才能变成芯片可高效执行的定点量化模型。本课程围绕“地平线模型转换流程”展开，帮助你建立从训练框架模型到板端可运行模型的端到端认知。本节作为导入课，重点回答三个问题：为什么要做模型转换、转换流程包含哪些关键环节、以及你应该按什么路径学习。

核心目标：学完本课程后，你应能独立完成“浮点模型 → ONNX → 量化校准 → 编译产物 → 板端推理验证”的全链路操作，并能定位转换过程中的精度损失与算子不支持问题。

一、为什么需要模型转换：核心价值

地平线芯片采用自研的 BPU（Brain Processing Unit）架构，其指令集、数据排布与内存层级与通用 GPU 差异很大。训练框架中的算子（如动态 shape 的 Reshape、自定义 Attention）无法直接在 BPU 上执行，必须经过图优化、算子映射、量化与编译。模型转换流程的核心价值体现在四个方面：

硬件适配：将通用算子映射为 BPU 支持的算子集合，生成可在征程芯片上加载的 .hbm 或 .bin 模型。
性能提升：通过算子融合、内存复用、指令调度，把推理延迟从数百毫秒压缩到几十毫秒级。
精度可控：通过量化校准（Calibration）把 FP32 模型转为 INT8，在精度损失可接受的前提下降低带宽与功耗。
工程闭环：转换工具链与仿真、板端验证打通，形成“训练—转换—评测—迭代”的可复现流程。

如果跳过转换流程直接部署，常见后果是模型无法加载、算子回退到 CPU 导致性能骤降，或量化后精度崩塌。因此，理解转换流程是算法落地工程师的必备能力。

二、整体框架：转换流程全景

地平线模型转换的整体框架可以概括为“五阶段一闭环”。下图展示了从原始模型到板端部署的完整数据流与工具链关系，其中每个阶段都有明确的输入、输出与检查点。

从图中可以看到，流程并非单向直线，而是带有反馈闭环：当仿真或板端验证发现精度下降、算子回退或性能不达标时，需要回到模型结构、ONNX 导出或量化策略阶段进行调整。理解这个闭环，是后续排查问题的关键。

三、方法流程：每个阶段的关键动作

为了让学习路径更清晰，下面用清单形式列出各阶段的核心动作与常见检查点：

模型准备：确认输入输出 shape 固定，去除训练专用算子（如 Dropout、自定义 Loss），将后处理尽量移出模型。
ONNX 导出：设置合适的 opset 版本，使用 torch.onnx.export 并验证 ONNX 与原始模型输出一致。
模型检查：运行 hb_mapper checker，查看算子是否全部被 BPU 支持，识别需要替换或拆分的节点。
量化校准：准备 100～500 张有代表性的校准图片，配置 calibration_type 与 preprocess，生成量化参数。
编译构建：执行 hb_mapper build，得到 .hbm 模型，并关注编译日志中的警告与回退算子。
验证评测：先用仿真工具对比浮点与量化输出，再上板运行，检查精度、延迟与内存占用。

下面是一段典型的转换配置片段，展示了量化与编译阶段的关键参数：

model_parameters:
  onnx_model: './model/yolov5s.onnx'
  output_model_file_prefix: 'yolov5s_640x640'
input_parameters:
  input_name: 'images'
  input_shape: '1x3x640x640'
  input_type_rt: 'nv12'
  input_type_train: 'rgb'
  norm_type: 'data_scale'
  scale_value: 0.003921568627
calibration_parameters:
  cal_data_dir: './calib_data'
  calibration_type: 'default'
  max_percentile: 0.99996
compiler_parameters:
  compile_mode: 'latency'
  optimize_level: 'O3'
  debug: False

四、案例场景：一个典型的转换落地过程

假设你有一个 YOLOv5s 检测模型，在 GPU 上 mAP 为 0.42，需要在征程 5 上以 30FPS 运行。转换过程中可能遇到三类典型问题：

算子不支持：模型中存在 NonMaxSuppression，BPU 不支持，需要将其移到 CPU 后处理。
量化精度下降：直接量化后 mAP 掉到 0.36，通过调整校准集、使用 max_percentile 截断、对敏感层保留浮点，可恢复到 0.41。
性能不达标：编译后单帧 45ms，通过开启 optimize_level O3、调整输入分辨率与算子融合，降到 28ms。

这个案例说明，转换流程不是“一键完成”，而是需要结合日志、评测数据反复迭代的工程过程。

五、常见误区与复盘

误区	表现	正确做法
认为转换就是格式转换	只导出 ONNX 就上板，忽略量化与编译	把量化校准与编译验证作为必经环节
校准集随意选取	用训练集少量图片，量化后精度波动大	选取覆盖真实场景的 100～500 张图片
忽略算子回退	部分算子跑在 CPU，延迟骤增	查看 checker 与编译日志，替换或拆分算子
只看仿真不看板端	仿真精度正常，板端结果异常	仿真与板端双重验证，检查前后处理一致性

学习建议：先跑通一个最小模型（如简单分类网络）的完整转换流程，再逐步替换为检测、分割等复杂模型。每遇到一个问题，记录日志与解决方式，形成自己的转换检查清单。

六、学习路径

本课程后续将按照“环境与工具 → ONNX 导出 → 模型检查 → 量化校准 → 编译构建 → 仿真与板端验证 → 性能调优 → 综合实战”的顺序展开。建议你按以下路径推进：

第一遍：理解每个阶段的目标与输入输出，能看懂转换日志。
第二遍：动手完成一个完整模型的转换，记录每一步命令与结果。
第三遍：针对精度或性能问题，练习定位与调优，形成可复用的配置模板。

当你能够独立完成一次“训练模型到板端部署”的闭环，并解释每一步为什么这样做时，就真正掌握了地平线模型转换流程的核心能力。