#量化精度调优指南

#背景

#量化误差

如上是一个标准的对称量化公式，产生误差的地方主要有：

1. round 产生的舍入误差。例如：当采用 int8 量化，scale 为 0.0078 时，浮点数值 0.0157 对应的定点值为 round(0.0157 / 0.0078) = round(2.0128) = 2, 浮点数值 0.0185 对应的定点值为 round(0.0185 / 0.0078) = round(2.3718) = 2。两者均产生了舍入误差，且由于舍入误差的存在，两者的定点值一致。

2. clamp 产生的截断误差。当 qmax * scale 无法覆盖需要量化的数值范围时，可能产生较大截断误差。例如：当采用 int8 量化，scale 为 0.0078 时，qmax * scale = 127 * 0.0078 = 0.9906，大于 0.9906 的值对应的定点值将被截断到 127。

量化必然产生误差，但误差对模型精度的影响程度却不同，原因如下：

1. 有些离群点有较大截断误差对模型几乎没有影响。

2. 不同算子对误差的敏感程度不同。例如：sigmoid，softmax 等算子，对输入在特定定义域内误差的容忍度比较高，而 topk，sort 等算子对误差非常敏感。

3. 模型具有一定的鲁棒性，泛化性，小的误差可以视作训练中的一种正则。

#减小量化误差

1. 对于舍入误差，可以使用更小的 scale，这样可以使得单个定点值对应的浮点值范围变小。由于直接减小 scale 会导致截断误差，所以常用的方法是使用更高的精度类型，比如：将 int8 换成 int16，由于定点值范围变大， scale 将减小。

2. 对于截断误差，可以使用更大的 scale。scale 一般是由量化工具使用统计方法得到，scale 偏小的原因是校准数据不够全，校准方法不对，导致 scale 统计的不合理。比如：某一输入的理论范围为 [-1, 1]，但校准或 qat 过程中，没有观测到最大值为 1 或最小值为 -1 的样本或观测到此类样本的次数太少。应该增加此类数据或者根据数值范围，手动设置固定 scale。在截断误差不大的情况下，可以调整校准参数，通过不同的校准方法和超参缓解截断误差。

#量化精度调优

量化精度调优包括两个方面：

1. 模型结构和量化配置检查。检查主要目的是避免非调优类的问题影响量化精度，比如：qconfig 配置错误，使用了量化不友好的共享模块等。

2. 混合精度调优。先使用高精度算子为主的模型快速迭代出精度达标的模型，获取精度上限和性能下限，再使用精度调优工具分析并调整量化配置，得到兼顾精度与性能的量化模型。

需要重点说明的是，在进行如下精度调优之前需要先验证自己的 pipeline 的正确性。

#模型结构和量化配置检查

在模型完成 prepare 之后，首先需要检查量化配置错误和模型结构对量化不友好的情况。可以使用 debug 工具中的 check_qat_model 接口进行检查，接口使用方式可参考精度调优工具使用指南章节。

#算子融合

检查模型中是否存在可以融合但没有融合的模块。模型在 BPU 上部署时会将 conv / bn / add / relu 等算子融合，在 qat 模型中，这些算子会被替换为一个 Module，避免在中间插入伪量化节点。如果这些算子没有融合，那么中间会产生额外的量化节点，对精度和性能可能产生轻微影响。下面的例子表明 conv 和 relu 没有 fuse。

在 prepare 的不同 method 中，可能导致产生算子融合错误的原因和解决方法有：

1. PrepareMethod.JIT 和 PrepareMethod.JIT_STRIP：

   a. 动态代码块中包含算子融合，需要使用 dynamic_block 进行标注。

   b. 调用次数变化的部分在 trace 时仅执行了一次，需要使用能够让调用次数变化的部分执行多次的输入作为 example_inputs。

2. PrepareMethod.EAGER：未进行 fuse 操作或 fuse_modules 写错，需要检查并修复手写的 fuse 逻辑。

3. PrepareMethod.SYMBOLIC：可 fuse 的模块被包含在了 fx.wrap 中，需要将这些模块移出 fx.wrap，保证图中存在这些模块或使用 PrepareMethod.EAGER 的方式手动 fuse。

#共享模块

由于 horizon_plugin_pytorch 采用模块替换的方式插入量化节点，所以对于一个模块仅能统计一组量化信息。当一个模块对象被多次调用且多次调用的输出数据分布差异较大时，使用同一组量化参数将产生较大误差，需要将共享模块拆开。如果多次调用的输出数据分布差异不大，那么就不需要拆开共享模块。这里先对共享模块的概念做一个说明，后面逐层比较的时候可以结合这里的结果决定是否需要拆开共享模块。

三种常见理解中的“共享”与这里所说的“共享”的异同：

A. 一个 module 后接多个 module，module A 被认为是共享，但这里 module A 仅被调用一次，输出数据分布不存在差异，不会影响量化精度，在调用次数检查中也不会体现出来。

B. 一个 module 被反复调用多次，但多次输出数据分布差异较小。虽然在调用次数检查中可以看出来，但对量化精度影响较小，不需要修改。

C. 一个 module 被反复调用多次，多次输出分布差异较大。在调用次数检查中可以看出来，且对量化精度影响较大，需要手动将其复制拆分。

在 model_check_result.txt 中，可以查看每个 module 的调用次数。正常每个 op 仅调用 1 次，0 表示未被调用，超过 1 次则表示调用了多次。下面的例子中，conv 为共享模块。

#QConfig 配置错误

qconfig 使用错误可能导致模型未按照预期的方式量化，从而产生精度损失（比如：混用模板和 qconfig 属性两种设置方法）。这里主要检查每个算子的输入输出是否符合预期，在 model_check_result.txt 中查看：

1. dtype 是否与设置一致。

2. 是否开启高精度输出。

除此以外，model_check_result.txt 中还会有异常 qconfig 提示（如果有的话）。这里为工具识别到的需要您再检查一下的 qconfig 配置，具体看是否符合预期，不一定就是错误的。

1. Weight int16。S100P 不支持输入和 weight 双 int16，如果发现 weight int16 需要检查 input 是否为 int16。

2. Fixed scale。检查 fixed scale 设置是否符合预期。

#混合精度调优

#调优流程

整个流程首先进行全 int16 精度调优，此阶段用于确认模型的精度上限，排查工具使用问题和量化不友好模块。

1. 在确认全 int16 精度满足需求后，进行全 int8 精度调优。如果精度不达标则进行 int8 / int16 混合精度调优，在全 int8 的基础上逐步增加 int16 的比例，该阶段需要您在精度和性能间做权衡，在满足精度的前提下，找出性能尽可能好的量化配置。

2. 如果全 int16 精度不满足需求，则进行 int16 / fp16 混合精度调优。理想情况下 int16 / fp16 混合精度调优可以解决所有精度问题。在此基础上进行 int8 / int16 / fp16 混合精度调优，固定所有 fp16 算子的配置，按照 1 中 int8 / int16 混合精度调优的方法调整 int16 算子比例。

#基本调优手段

基本调优手段的目标是快速迭代，在全 int16 精度调优和全 int8 精度调优中，模型只是一个快速迭代的中间状态，一般仅使用基本调优手段。 而在混合精度调优中追求使用更少的高精度算子，需要按精度需求决定是否使用更加复杂的高级调优手段，这会带来更多的试错和迭代成本，但模型的精度和性能可以调得更好。

#Calibration

1. 调整校准 step。校准数据越多越好，但因为边际效应的存在，当数据量大到一定程度后，对精度的提升将非常有限。如果训练集较小，可以全部用来 calibration，如果训练集较大，可以结合 calibration 耗时挑选大小合适的子集，建议至少进行 10 - 100 个 step 的校准。

2. 调整 batch size。一般 batch size 要尽可能大，如果数据噪声较大或模型离群点较多，可以适当减小。

3. 使用推理阶段的前处理 + 训练数据进行校准。校准数据应接近真实分布，可以使用翻转这类数据增强，不要使用旋转，马赛克等会改变真实分布的数据增强方法。

#QAT

1. 调整学习率。

   a. 初始学习率：取消 warmup，取消 learning rate decay 策略，使用不同的固定学习率（1e-3, 1e-4, ...）finetune 少量 step，并观察评测指标，取效果最好的作为初始学习率。如果浮点模型不同模块学习率不同，那么这里也要做对应尝试。

   b. Scheduler：learning rate decay 策略与浮点对齐，但需要确保没有 warmup 类的策略，例如浮点 learning rate decay 策略为 cosine annealing，那么 qat 也应该使用 cosine annealing。

2. 尝试固定和更新 input / output scale 两种策略。一般来说，校准模型精度较好时，固定 input / output scale 进行 QAT 训练可以取得更好的效果，精度较差时，则不能固定。具体使用哪种策略，没有明确指标可以参考，需要分别进行尝试。

3. 训练 step 数一般不超过浮点训练的 20%，可结合训练的 loss 和评测结果酌情调整。

特别需要注意的点：

1. 除上述需要调整的内容以外，其余 qat 训练配置与浮点训练对齐。

2. 如果在浮点训练中使用了 freeze bn 的技巧，那么 qat 训练中需要将 qat mode 设置为 withbn。

#高级调优手段

高级调优手段一般需要花费较多时间不断尝试，在对精度有较高要求时使用。

#设置 Fixed Scale

模型中的某些地方很难依靠统计的方式获得最佳的量化 scale。常见的需要设置 fixed scale 的情况：算子的输出值域确定时需要设置 fixed scale。

比如：输入数据为速度 km / h，值域为 [0, 200], 对于 quantstub 而言，输出值域是固定的，需要将 scale 设置为 200 / 量化数值范围。之所以这么做是因为量化 scale 值是基于统计方法获取的，在正常的校准数据中，很难保证每一个样本都达到边界情况，统计方法为了消除离群点会使用滑动平均，导致得到的量化范围小于实际值。在上面输入数据为速度的例子中，如果不设置 fixed scale，那么统计出来的最大速度可能是大多数车辆的平均速度，导致所有超过这个速度的样本在输入时就产生较大的精度损失。您在这里可能很难识别所有需要设置 fixed scale 的情况，但在精度 debug 的逐层比较步骤中，将很容易发现此类问题。

下图中，输入 a 和 b 值域确定，输入 c 值域不确定，除 quantstub_c 和后一个 add 以外，其余算子均需要设置 fixed scale。

#Calibration

尝试不同的校准方法。Plugin 支持多种校准方法，推荐尝试 min max / percentile / kl / mse / mix 这几种方法，调参经验见Calibration 指南。

#QAT

1. 调整 weight decay。weight decay 会影响模型中权重的数值范围，更小的数值范围更加量化友好。有时，只调整 qat 阶段的 weight decay 还不足以解决问题，需要调整浮点训练阶段的 weight decay。

2. 调整数据增强。量化模型比浮点模型的学习能力更差，太强的数据增强会影响 qat 模型收敛，一般需要适当减弱数据增强。

#INT8 / INT16 混合精度调优 & INT16 / FP16 混合精度调优

混合精度调优的基本思路是在某一精度的基础上逐步增加更高精度算子的比例，直到达到精度需求。在 int8 / int16 混合精度调优中，以全 int8 模型为基础，逐步增加 int16 算子的数量。而在 int16 / fp16 混合精度调优中，则以全 int16 模型为基础，逐步增加 fp16 算子的数量。

上图中的校准和 qat 调优参考基本调优手段和高级调优手段章节，增加 int16 / fp16 的高精度算子数量依赖于精度 debug 工具产出的一系列 debug 结果。

qat 精度 debug 全部基于浮点模型和校准模型的对比，一般来说，不推荐您将浮点模型和 qat 模型进行对比，经过 qat 训练，浮点模型和 qat 模型已失去可比性，请先阅读精度调优工具使用指南章节了解相关背景。首先，提供数据集查找校准模型损失较大的 badcase，在 badcase 的基础上进行逐层比较并计算量化敏感度。

#查找 Badcase

精度 debug 的全部操作都围绕 badcase 展开。您需要提供一个量化精度较差的样本集，此过程会遍历样本集，对比每一个样本在浮点模型和校准模型输出上的误差。一般情况下，不需要您提供误差的度量函数。

使用 debug 工具中的 auto_find_bad_case 接口查找 badcase。

查找 badcase 完成后，查看结果文件，对于模型的每一个输出，在每一种误差度量下，debug 工具都会找一个最差的样本。在下面这个例子中，模型一共有 3 个输出，第一个表格表示每一个输出在每一种度量下的最差样本 index，第二个表格表示对应的误差是多少，第三个表格表示当前度量下，模型所有输出中误差最大的 badcase index。

#逐层比较

逐层比较会使用指定的 badcase 分别跑浮点模型和校准模型，并对比每一层的输出，对其进行统计并计算误差，可以使用 debug 工具中的 compare_per_layer 接口进行对比。compare_per_layer 适用于极为细致的精度问题分析，如果精度损失不明显，可以先跳过这一步，后面再结合敏感度结果做分析。

逐层比较的结果可以通过生成的文本文件来查看。在文本文件中，可以从上至下查看从哪个算子开始，误差被放大。

#计算量化敏感度

这一步会评估模型中的量化节点对精度的影响，可以使用 debug 工具中的 sensitivity 接口评估量化敏感度。具体的评估方法为，以 badcase 作为模型输入，分别将每一个量化节点打开，对比量化模型与浮点模型输出的误差，误差的度量标准与查找 badcase 时使用的一致。

量化敏感度的结果中，敏感度排名越高的算子对模型精度影响越大，需要将其设置为更高的精度类型。

sensitive_type 列有 weight / activation 两种，分别表示只打开该算子的 weight 量化节点/输出量化节点的情况。

设置需要用到敏感度模板，用法详见 qconfig 章节。若模型有多个输出，每个输出都会生成一个对应的敏感度表，您可以选取若干指标相差较大的输出所对应的敏感度表，设置敏感度模版。下面是 int8 / int16 混合精度调优中，设置 2 个输出敏感度表 int8 敏感度 top 20% int16 的例子。总的 int16 个数为两个表中 top 20% int16 算子的并集。之后不断调整 int16 的比例，直到找到满足精度需求的最少 int16 比例。

目前暂不提供根据敏感度批量设置 fp16 的接口，需要根据 int16 的敏感度结果，使用 ModuleNameQconfigSetter 设置少量 fp16。下面是 int16 / fp16 混合精度调优中，设置 int16 敏感度 top1 fp16 的例子。

S100P 浮点算力有限，如果没有必须使用 fp16 的情况，尽量使用 int8 / int16 混合精度调优。当全 int16 模型无论如何也不能达到精度要求时，需要在全 int16 模型中引入少量 fp16 算子。

造成全 int16 模型精度不达标的两种情况：

1. 需要使用双 int16：表现为量化敏感度表中某些算子在 activation 和 weight sensitive_type 下的敏感度都较高，设置 weight 和 activation 为 int16 后精度可以达标。由于 S100P 不支持 activation 和 weight 同时使用 int16，所以只能通过调整浮点模型的方式使两者其一变得更加量化友好。常用的方法有增大 weight decay，添加 norm 类算子等。

2. 不需要使用双 int16：表现为量化敏感度表中某些算子在 activation 或 weight sensitive_type 下的敏感度较高，一般是 plugin 使用问题，或部分算子需要设置 fixed scale，通过精度 debug 可以发现具体问题。

#INT8 / INT16 / FP16 混合精度调优

在进行 int8 / int16 / fp16 混合精度调优之前，您应该已经完成了 int16 / fp16 混合精度调优。复用 int16 / fp16 混合精度调优中 fp16 的配置，在 int8 / fp16 混合校准模型的基础上进行精度 debug。参考上一节的精度 debug 方法，不断调整 int16 的比例，直到找到满足精度需求的最少 int16 比例即可。

下面是 int8 / int16 / fp16 混合精度调优中，设置 int16 敏感度 top 1 fp16，int8 敏感度 top 20% int16 的例子。