3. 地平线量化工具链概览

地平线（Horizon Robotics）的量化工具链并不是一个单一命令行程序，而是一组围绕“模型转换—量化校准—编译部署”构建的协同工具集合。理解这套工具链的组成与边界，是后续做校准数据设计、精度评估和部署验证的前提。本节从工具链组成、量化流程、模型格式与硬件平台四个维度展开，帮助你建立一张完整的“工具地图”。

一、工具链组成：从训练框架到板端可执行

地平线量化工具链的核心是 Horizon Open Explorer（OE） 工具包，它把模型转换、量化、编译、仿真和部署打包成一套可脚本化的流程。典型组件包括：

• 模型转换工具（hb_mapper / horizon_model_convert）：将 ONNX、Caffe 等浮点模型转换为地平线中间表示，并完成量化配置。
• 量化校准模块：读取校准数据集，统计激活值分布，生成量化参数（scale、zero_point）。
• 编译器（hbdk / horizon_compiler）：将量化后的模型编译为 BPU 可执行的 .hbm 或 .bin 文件。
• 仿真与精度评估工具：在 x86 上模拟 BPU 行为，输出逐层精度对比，用于定位量化损失。
• 板端运行时（libdnn / hb_dnn）：在开发板上加载模型、执行推理，并提供输入输出接口。

这些组件通过配置文件（如 config.yaml）和中间产物（.onnx → .hbir → .hbm）串联起来，形成一条可复现的流水线。

二、量化流程：五步走

地平线量化流程可以概括为五个阶段，每一步都有明确的输入输出和检查点：

1. 模型准备：将训练好的模型导出为 ONNX，确保算子在地平线支持列表内，必要时进行算子替换或拆分。
2. 配置量化参数：在 config.yaml 中指定输入节点、输出节点、校准数据路径、量化方式（如 default、kl、max）等。
3. 校准与量化：运行 hb_mapper，工具会遍历校准集，统计每层激活值分布，生成量化参数并输出量化模型。
4. 编译：使用 hbdk 将量化模型编译为 BPU 可执行文件，同时生成仿真用的中间文件。
5. 仿真与板端验证：先在 x86 上做逐层精度对比，确认无异常后再部署到开发板，用真实数据做端到端验证。

三、支持的模型格式与硬件平台

地平线工具链对模型格式和硬件平台有明确的适配范围。下表整理了常见组合，便于你在项目选型时快速对照：

四、案例场景：一次完整的量化编译

假设你有一个 PyTorch 训练好的分类模型，目标平台是征程 5。典型操作流程如下：

# 1. 导出 ONNX
python export_onnx.py --weights model.pth --output model.onnx

# 2. 准备校准数据（100~500 张代表性图片）
ls calib_data/
# img_0001.jpg  img_0002.jpg  ...  img_0500.jpg

# 3. 编写 config.yaml
model:
  onnx_model: model.onnx
  output_model: model_quantized.hbm
  input_shape: [1, 3, 224, 224]
  input_layout: NCHW
calibration:
  data_dir: calib_data/
  batch_size: 8
  method: kl
target:
  platform: j5

# 4. 执行量化编译
hb_mapper --config config.yaml

# 5. 仿真评估
hb_mapper --config config.yaml --simulate

执行完成后，工具会输出逐层精度报告。如果发现某层余弦相似度低于阈值（如 0.98），可以针对该层调整量化方式或将其加入混合精度白名单。

五、常见误区与复盘

• 误区一：校准集随便拿训练集凑数。训练集分布与真实部署分布不一致时，量化参数会偏，导致板端精度骤降。校准集应尽量贴近实际推理数据。
• 误区二：忽略算子支持列表。ONNX 里某些算子在地平线 BPU 上不支持，转换时会报错或静默回退到 CPU，影响性能。转换前应先用工具检查算子兼容性。
• 误区三：仿真通过就认为板端一定没问题。仿真模拟的是 BPU 计算行为，但板端还涉及内存布局、输入预处理、后处理等环节，必须做端到端验证。
• 误区四：量化方式一刀切。全部用 max 或全部用 kl 都不一定最优，建议先跑默认配置，再针对掉点层做局部调整。

复盘时建议保留每次量化的配置文件、校准集清单和精度报告，形成可追溯的记录。这样当模型迭代或更换硬件平台时，可以快速定位是数据问题、配置问题还是编译问题。