PTQ 精度 Debug 工具

01 前言

使用 PTQ 后量化的模型量化方案，可以帮助用户非常简单便捷地完成从浮点模型到地平线混合异构模型的转换，模型转换工具会基于用户提供的校准样本对模型进行校准量化并保障模型高效地部署在地平线计算平台上。

但是在模型转换的过程中，不可避免地会因为浮点高精度到定点低精度的量化过程而引入精度损失，因此为了帮助用户准确快速地定位模型精度损失的主要原因，地平线工具链提供了一套 PTQ 精度 Debug 工具。

本文将基于 征程5 工具链 1.1.62 版本的 OpenExplorer 开发包来详细介绍这些工具的使用方法和使用流程，以及对输出结果进行解读，来帮助用户快速上手。

对于 XJ3 工具链，PTQ 精度 Debug 工具的使用方法一致，但是暂不支持命令行配置和 runall 功能。

在本文开始之前，需要用户参考文章图片校准数据准备问题介绍与处理和模型精度验证及调优建议，掌握正确处理校准数据以及评测模型精度的方法，并且排除因输入数据预处理不当和欠佳的推理结果后处理等非模型自身造成的精度问题。

02 基础介绍

在 PTQ 模型后量化过程中，通常情况下造成精度损失的主要原因可能有以下几点：

1. 敏感节点量化问题。模型中的一部分节点对量化比较敏感会引入较大误差；

2. 节点量化误差累积问题。模型中各个节点的量化误差累积导致模型整体出现较大的校准误差，主要包含：权重量化导致的误差累积、激活量化导致的误差累积以及全量量化导致的误差累积。

针对上述情况，地平线工具链提供的精度 Debug 工具将协助用户自主定位模型量化过程中产生的精度问题，对校准模型进行节点粒度的量化误差分析并快速定位出现精度异常的节点。

PTQ 精度 Debug 工具提供的功能包括：

• 获取节点量化敏感度；

• 获取模型累积误差曲线；

• 获取指定节点的数据分布；

• 获取指定节点输入数据通道间数据分布箱线图等。

2.1 基本流程

使用精度 Debug 工具进行精度 Debug 的基本流程为：

1.校准模型和校准数据的准备。校准模型在模型转换过程中为常态化保存，无需用户额外操作，为模型转换的输出目录model_output下的calibrated_model；校准数据的保存需要用户在 Yaml 文件中的模型参数组中增加如下参数配置（配置后精度 Debug 功能同时开启，但需要用户重新编译一次模型，编译等级可以配置为 O0 以减少编译时间）：

model_parameters:
  debug_mode: "dump_calibration_data"

2.通过import horizon_nn.debug as dbg导入 Debug 模块（使用命令行则无需导入），加载校准模型和校准数据；

3.通过精度 Debug 工具提供的 API 或者命令行，对精度损失明显的模型进行分析。（详细的流程以及分析见后文。）

2.2 校准数据

校准数据（calibration_data）在模型转换的校准阶段使用，模型通过对这些数据进行前向推理来获取每个被量化节点的量化参数，量化参数包括：缩放因子（Scale）和阈值（Threshold）。

值得注意的是，此处保存的校准数据是经过颜色空间转换以及预处理之后的 npy 格式的数据，该数据可以通过np.load()直接送入校准模型进行推理，不同于在模型转换前数据准备阶段使用02_preprocess.sh脚本生成的校准数据。

使用脚本生成的校准数据是 bgr 颜色空间的数据，在工具链内部会将数据从 bgr 转换到 yuv444/gray 等模型实际输入的格式。

按照上述精度 Debug 流程中提到的操作保存校准数据后，自动在model_output目录下生成的calibration_data文件夹结构如下所示：

|-- calibration_data  #校准数据
    |---- input1  #文件夹名为模型的输入节点并保存对应的输入数据
          |-------- 0.npy
          |-------- 1.npy
          |-------- ...
    |---- input2  #对于多输入模型将保存多个文件夹
          |-------- 0.npy
          |-------- 1.npy
          |-------- ...
    |---- ...

2.3 校准模型

校准模型（calibrated_model.onnx）是将在校准阶段计算得到的每个被量化节点的量化参数保存在校准节点中，从而得到的模型。

模型转换过程中，模型转换工具将浮点模型进行结构优化后，通过校准数据计算得到每个节点对应的量化参数并将其保存在校准节点中，形成了校准模型。

因此校准模型是一种中间产物，主要特点是模型中包含校准节点，校准节点的节点类型为 HzCalibration。

校准节点主要分为两类：

1. 激活（activation）校准节点。激活校准节点的输入是当前节点的上一个节点的输出，并基于当前激活校准节点中保存的量化参数对输入数据进行量化和反量化后输出；

2. 权重（weight）校准节点。权重校准节点的输入是模型的原始浮点权重，并基于当前权重校准节点中保存的量化参数对输入的原始浮点权重进行量化和反量化后输出。

除了上述的校准节点，校准模型中的其他节点称为普通节点（node），普通节点的类型包括：Conv、Mul 和 Add 等。

下图直观地展示了校准节点和普通节点在校准模型中扮演的角色：

03 一键运行

为了方便用户快速获取 PTQ Debug 工具的结果，这里推荐使用一键运行功能，可以一键运行 PTQ Debug 工具中的全部功能。每个功能的详细解读可以参考第三部分功能详解。

根据经验，校准数据的数量对 PTQ Debug 的结果不会有太大影响，为了加速工具运行，建议用户使用一份校准数据即可，配置详见参数介绍。

此外 PTQ 精度