#精度调优工具使用指南

由于浮点转定点过程中存在误差，当您在使用量化训练工具时，难免会碰到量化模型精度掉点问题。通常来说，造成掉点的原因有：

1. 原有浮点模型不利于量化，如存在共享 op 或共享结构。

2. QAT 网络结构或配置异常，如模型中存在没有 fuse 的 pattern，没有设置高精度输出等。

3. 某些算子对量化比较敏感，该算子的量化误差在前向传播过程中逐层累积，最终导致模型输出误差较大。

针对上述情况，量化训练工具提供了精度调优工具来帮助您快速定位并解决精度问题，主要包括如下模块：

• 模型结构检查：检查模型中是否存在共享 op、没有 fuse 的 pattern 或者不符合预期的量化配置。

• QuantAnalysis 类：自动比对分析两个模型，定位到量化模型中异常算子或者量化敏感 op。

• ModelProfiler 类 和 HbirModelProfiler 类：获得模型中每一个 op 的数值特征信息，如输入输出的最大最小值等。这两个类的功能完全一致，区别在于 HbirModelProfiler 仅接受 qat hbir 模型作为输入。通常您无需手动调用该模块，可以直接通过 QuantAnalysis.run 来获得两个模型的数值信息。

#快速上手

当碰到量化模型精度掉点问题时，我们推荐按照如下的流程使用精度调优工具。

1. 检查模型中是否存在不利于量化的结构或者异常配置。

2. 使用 QuantAnalysis 模块进行分析，具体步骤如下：

   1). 找到一个 bad case 作为模型的输入。bad case 是指基准模型和待分析模型输出相差最大的那个输入。

   2). 进行量化敏感度分析，目前的经验是 L1 敏感度排序前 n 个通常为量化敏感 op（不同的模型 n 的数值不一样，暂无自动确定的方法，需要手动尝试，如前 10 个，20 个...）。将量化敏感 op 设置高精度量化（如 int16 量化），重新进行量化流程。

   3). 或者逐层比较两个模型的输入输出等信息，检查是否存在数据范围过大或者 scale 不合理等量化异常的 op，如某些具有物理含义的 op 应设置固定 scale。

整体的流程图如下：

一个完整的例子如下：

#API Reference

#模型结构检查

检查 calibration/qat 模型中是否存在不利于量化的结构以及量化 qconfig 配置是否符合预期。

参数

• model: 待检查模型。

• example_inputs: 模型输入。

• save_results: 是否将检查结果保存到 txt 文件。默认 False。

• out_dir: 结果文件 'model_check_result.txt' 的保存路径。默认空，保存到当前路径下。

输出

• 屏幕输出：检查出的异常层。

• model_check_result.txt：在 save_results = True 时生成。主要由 5 部分组成：

  1). 未 fuse 的 pattern。

  2). 每个 module 的调用次数。正常每个 op 仅调用 1 次，0 表示未被调用，超过 1 次则表示被共享了多次。未调用或者共享多次的会有异常提示。

  3). 每个 op 输出的 qconfig 配置。

  4). 每个 op weight（如果有的话）的 qconfig 配置。

  5). 异常 qconfig 提示（如果有的话）。

#QuantAnalysis 类

QuantAnalysis 类可以自动寻找两个模型输出最大的 bad case，并以此作为输入，逐层比较两个模型的输出。此外，QuantAnalysis 类还提供计算敏感度功能，您可以尝试将敏感度排名 topk 的节点设置高精度，如 int16 量化，来提升量化模型精度。

参数

• baseline_model: 基准模型（高精度）。

• analysis_model：待分析的模型（精度掉点）。

• analysis_model_type: 待分析的模型类型。支持输入：

  • fake_quant：待分析的模型可以是精度掉点的 calibration 模型，此时基准模型可以是原始浮点模型或者一个精度达标的 int8/int16 混合配置的 calibration 模型。

• device_ids：对比分析时模型运行的 GPU 设备 index。

• post_process：模型后处理。

• out_dir：指定比较结果的输出目录。

该类中各个 method 如下：

#auto_find_bad_case

自动寻找导致两个模型输出最差的 badcase。

参数

• data_generator：dataloader 或者一个自定义的迭代器，每次迭代产生一个数据。

• num_steps：迭代 steps 次数。

• metric：指定何种 metric 作为 badcase 的 metric。默认使用 ATOL 最差的结果。支持 COSINE/L1/ATOL。

• device：指定模型运行 device。

• custom_metric_func：自定义模型输出比较函数。

• custom_metric_order_seq：自定义模型输出比较函数的排序规则，仅支持 "ascending"/"descending"，表示升序/降序。

• cached_attrs：作为模型输入的某些属性。通常在时序模型中使用，如运行第二帧时，将第一帧的某些结果作为输入。

• dump_in_run: 是否在运行过程中保存 badcase。

输出

• badcase.txt：包含 3 部分内容

  • 各个输出在不同 metric 下找到的 badcase 输入。（在 data_generator 中的索引值）。

  • 各个输出在不同 metric 下找到的 badcase 输入对应的 metric 最差值。

  • 相同 metric 指标下，输出最差的 badcase 输入。

  The bad case input index of each output: Name/Index COSINE L1 ATOL ------------ -------- ---- ------ box0 16 0 0 box1 77 32 32 box2 66 46 56 scores 61 96 100 centerness 0 0 0 yawness 17 76 18 The metric results of each badcase: Name/Index COSINE L1 ATOL ------------ --------- --------- --------- box0 0.906329 84.7319 2.97311 box1 0.968623 38.602 2.98777 box2 0.799405 237.053 4.37895 scores 0.388762 0.0080612 0.0395061 centerness 0.904206 0.0456813 0.178009 yawness -0.325684 4.87353 1.27329 The bad case input index of the worst output: metric dataloader index -------- ------------------ COSINE 17 L1 46 ATOL 56

• badcase.pt：保存的输入数据，为参数 metric 指定的 metric 指标最差的输入。作为 run 函数的默认输入。

#set_bad_case

手动设置 badcase。

参数

• data: badcase 输入。

• baseline_model_cached_attr：基准模型的 cached_attrs。

• analysis_model_cached_attr：待分析模型的 cached_attrs。

#load_bad_case

从指定的文件中加载 badcase。

参数

• filename：指定的文件路径。默认从初始化时指定的 out_dir 目录中加载 auto_find_bad_case 函数保存的 badcase 相关文件。

#save_bad_case

将 badcase 保存到 {self.out_dir}/badcase.pt 文件。

#set_model_profiler_dir

手动指定 model_profiler 的输出保存路径。

某些情况下，在 QuantAnalysis 初始化之前，ModelProfiler 就已定义并运行，此时可以直接指定已有的 ModelProfiler 路径，跳过 QuantAnalysis 的 run 步骤，直接比较两个模型的输出。

参数

• baseline_model_profiler_path：基准模型的 profiler 路径。

• analysis_model_profiler_path：待分析模型的 profiler 路径。

#run

运行两个模型并分别保存模型中每一层的结果。

参数

• device：模型运行的 device。

• index：输入数据在 data_generator 中的 index。

#compare_per_layer

比较两个模型中每一层的结果。

参数

• prefixes：指定 op 名字的前缀。

• types：op 类型。

输出

• abnormal_layer_advisor.txt: 所有异常层，包括数据范围过大/包含 inf 或 NaN/输出没有高精度等情况。

• profiler.html: 可视化展示所有 metric 指标及模型中每一层的数据范围 diff。

• compare_per_layer_out.txt: 以表格的形式展示模型中每层 layer 的具体信息，包括各种指标、数据范围、量化 dtype 等。从左到右每一列分别表示：

  • Index：op index。

  • mod_name：该 op 名字，若 op 为 module 类型，则显示该 module 在模型中的 prefix name，若为 function 类型，则不显示。

  • base_op_type：基准模型中该 op 的 type，可能是 module 类型或者 function 名称。

  • analy_op_type：待分析模型中该 op 的 type，可能是 module 类型或者 function 名称。

  • Shape：该 op 输出的 shape。

  • quant_dtype：该 op 输出的量化类型。

  • Qscale：该 op 输出的量化 scale。

  • Cosine：该 op 在两个模型中输出的余弦相似度。

  • L1：该 op 在两个模型中输出的 L1 距离。

  • Atol：该 op 在两个模型中输出的绝对误差。

  • max_qscale_diff：该 op 在两个模型中输出最大相差了几个 scale。

  • base_model_min：基准模型中该 op 输出的最小值。

  • analy_model_min：待分析模型中该 op 输出的最小值。

  • base_model_max：基准模型中该 op 输出的最大值。

  • analy_model_max：待分析模型中该 op 输出的最大值。

  • base_model_mean：基准模型中该 op 输出的平均值。

  • analy_model_mean：待分析模型中该 op 输出的平均值。

    +----+------------+--------------------------------------------------------------------+--------------------------------------------------------------------+----------------------------+---------------+-----------+-----------+-----------+-----------+-------------------+------------------+-------------------+------------------+-------------------+-------------------+--------------------+ | | mod_name | base_op_type | analy_op_type | shape | quant_dtype | qscale | Cosine | L1 | Atol | max_qscale_diff | base_model_min | analy_model_min | base_model_max | analy_model_max | base_model_mean | analy_model_mean | |----+------------+--------------------------------------------------------------------+--------------------------------------------------------------------+----------------------------+---------------+-----------+-----------+-----------+-----------+-------------------+------------------+-------------------+------------------+-------------------+-------------------+--------------------| | 0 | quant | torch.ao.quantization.stubs.QuantStub | horizon_plugin_pytorch.nn.qat.stubs.QuantStub | torch.Size([1, 3, 32, 32]) | qint8 | 0.0078404 | 0.9999922 | 0.0019772 | 0.0039202 | 0.5000016 | 0.0002798 | 0.0000000 | 0.9996471 | 0.9957269 | 0.4986397 | 0.4986700 | | 1 | conv | torch.nn.modules.conv.Conv2d | horizon_plugin_pytorch.nn.qat.conv2d.Conv2d | torch.Size([1, 3, 32, 32]) | qint8 | 0.0056401 | 0.9999791 | 0.0020876 | 0.0092935 | 1.6477517 | -0.7193903 | -0.7162931 | 0.5436335 | 0.5414499 | -0.0423445 | -0.0413149 | | 2 | relu | torch.nn.modules.activation.ReLU | torch.nn.modules.activation.ReLU | torch.Size([1, 3, 32, 32]) | qint8 | 0.0056401 | 0.9999741 | 0.0009586 | 0.0088447 | 1.5681799 | 0.0000000 | 0.0000000 | 0.5436335 | 0.5414499 | 0.1555644 | 0.1557564 | | 3 | | horizon_plugin_pytorch.nn.interpolate.autocasted_interpolate_outer | horizon_plugin_pytorch.nn.interpolate.autocasted_interpolate_outer | torch.Size([1, 3, 41, 41]) | qint8 | 0.0056401 | 0.9924216 | 0.0160291 | 0.2094204 | 37.1305954 | 0.0000000 | 0.0000000 | 0.5149657 | 0.5301697 | 0.1550578 | 0.1559310 | | 4 | dequant | torch.ao.quantization.stubs.DeQuantStub | horizon_plugin_pytorch.nn.qat.stubs.DeQuantStub | torch.Size([1, 3, 41, 41]) | torch.float32 | | 0.9924216 | 0.0160291 | 0.2094204 | | 0.0000000 | 0.0000000 | 0.5149657 | 0.5301697 | 0.1550578 | 0.1559310 | +----+------------+--------------------------------------------------------------------+--------------------------------------------------------------------+----------------------------+---------------+-----------+-----------+-----------+-----------+-------------------+------------------+-------------------+------------------+-------------------+-------------------+--------------------+

• compare_per_layer_out.csv: 以 csv 的格式展示每层的具体信息。内容和 compare_per_layer_out.txt 完全一致，csv 文件的存储格式方便您通过 excel 等软件打开分析。

#sensitivity

模型中各个节点的敏感度排序。适用于 float 转 calibration 的精度掉点问题。

参数

• device：指定模型运行的 device。

• metric：相似度排序的 metric，默认 L1，支持 Cosine/MSE/L1/KL/SQNR。

• reserve：是否反序打印敏感度节点，以支持将某些 int16 算子退回 int8 来提升上板性能。

输出

• sensitive_ops.txt。文件中按照量化敏感度从高到低的顺序排列 op。从左到右每一列分别表示：

  • op_name：op 名字。

  • sensitive_type：计算量化敏感的类型，包括三种：

    • activation：仅量化该 op 输出的量化敏感度。

    • weight：仅量化该 op 权重的量化敏感度。

  • op_type：op 类型。

  • metric：计算敏感度的指标。按照敏感度从高到低的顺序排序。支持 Cosine/L1/MSE/KL/SQNR 五种指标。默认使用 L1。

    • L1：取值范围 [0, $+\infty$]，数值越大则该 op 对量化越敏感（从大到小排序）。

    • Cosine：取值范围 [0,1]，越接近 0 则该 op 对量化越敏感（从小到大排序）。

    • MSE：取值范围 [0, $+\infty$]，数值越大则该 op 对量化越敏感（从大到小排序）。

    • KL：取值范围 [0, $+\infty$]，数值越大则该 op 对量化越敏感（从大到小排序）。

    • SQNR：取值范围 [0, $+\infty$]，数值越小则该 op 对量化越敏感（从小到大排序）。

  • quant_dtype：该 op 输出的量化 dtype。通常为 qint8/qint16。

  • flops：该 op 的计算量以及在整个模型计算量中的占比。

• sensitive_ops.pt。使用 torch.save 保存的敏感度排序的列表，方便您后续加载使用。若存在多个输出，则每个输出都会生成一个敏感度表。列表格式见返回值部分说明。

返回值

敏感度 List，List 中每个元素都是记录一个 op 敏感度信息的子 list。子 List 中从左到右每一项分别为 [op_name, sensitive_type, op_type, metric, quant_dtype, flops]。

整个 List 示例如下：

您可以将量化敏感度排名前 n 的 op 配置高精度（如 int16）来尝试提升量化模型精度。

#clean

清除中间结果。仅保留比较结果等文件。

#ModelProfiler 类

统计模型 forward 过程中，每一层算子的输入输出等信息。

参数

• model: 需要统计的模型。

• out_dir: 相关文件保存的路径。

该类中其中各个 method 如下：

#get_info_manager

获得管理每个 op 信息的结构体。

返回值

管理存储的每个 op 信息的结构体 OpRunningInfoManager。其中两个重要的接口如下：

#table

在一个表格中展示单个模型统计量。存储到 statistic.txt 文件中。

参数

• out_dir：statistic.txt 文件的存储路径，默认 None，存储到 self.out_dir。

• prefixes：需要统计的模型中 op 的 prefixes。默认统计所有 op。

• types：需要统计的模型中 op 的 type。默认统计所有 op。

• with_stack: 是否显示每个 op 在代码中对应的位置。

输出

statistic.txt 文件，从左到右每一列分别为：

• Index：op index。

• Op Name：op type，module 类名或者 function 名。

• Mod Name：若是 module 类，则显示该 module 在模型中的 prefix name；若是 function 类型，则显示该 function 所在的 module prefix name。

• Attr：input/output/weight/bias。

• Dtype：tensor 的数据类型。

• Scale：tensor 的 scale。

• Min：当前 tensor 的最小值。

• Max：当前 tensor 的最大值。

• Mean：当前 tensor 的平均值。

• Var：当前 tensor 中数值的方差。

• Shape：tensor shape。

#tensorboard

在 tensorboard 中显示每一层输入输出直方图。

参数

• out_dir：tensorboard 相关文件保目录。默认保存到 self.out_dir/tensorboard 目录下。

• prefixes：需要统计的模型中 op 的 prefixes。默认统计所有。

• types：需要统计的模型中 op 的 type。默认统计所有。

• force_per_channel：是否以 per_channel 量化的方式展示直方图。

输出

tensorboard 文件，打开后截图如下：

#HbirModelProfiler 类

该类的功能和使用方式与 ModelProfiler 类完全一致。请参考 ModelProfiler 类 进行使用。