Profiler调试工具用法及高一致性策略实战

1.基础知识

工具链用户手册对 profiler debug 工具的基本操作已做详述，按常规流程走一遍即可上手。但实际部署时，总会碰到“手册未覆盖”的盲区。本文聚焦几个典型痛点，梳理如何把这个工具用到实处。

精度异常时，先排除前后处理环节的干扰，剩下的问题就可以交给 profiler debug 处理。但动手前，必须理清过程中涉及的几个模型类型，下图一目了然：

2.profiler debug 工具使用场景

若 calib 精度不符合预期，直接使用 profiler debug 对比 float_model 与 calib_model 即可定位。

如果精度损失出现在 export / convert 阶段，先别急于上 debug 工具——优先尝试高一致性策略。若无效，再引入 profiler debug 对比：

• qat_pt vs pre_export_pt
• pre_export_pt vs quantized_bc

下面先介绍高一致性 QAT 策略，再通过一个实际案例演示 profiler debug 的具体操作。

2.1 高一致性 QAT 策略【beta 功能】

注意事项：

1. 高一致性策略仅影响 convert 前后的数值一致性，对查表转定点无作用。
2. level0 全局开启会额外增加约 10%~20% 的 latency，极端场景可达 40%。
3. level2 对 latency 有正向收益，建议优先选用。
4. 目前仅适用于 J6EM 平台。
5. 实现方式后续会持续优化，具体细节务必参考用户手册《QAT-训练部署一致性-高一致性 QAT 策略》章节。

该策略封装在 horizon_plugin_pytorch.qat_mode.ConsistencyStrategy 下，通过 set_consistency_level 接口即可配置。

当前支持 0 到 4 共五个等级。等级越高一致性越强，但 QAT 精度可能受到轻微影响。推荐直接使用 level 2——绝大多数场景下对 QAT 精度无影响，反而能缓解截断误差引发的精度问题，在提升性能一致性的同时保证精度。

若已有未采用高一致性策略训练好的 QAT 模型，且不想重新训练，可在 prepare export 前将等级设为 0（不重训条件下仅 level 0 生效，level 1-4 需重训）。

from horizon_plugin_pytorch.qat_mode import ConsistencyStrategy
# 必须在 prepare 之前设置一致性策略
ConsistencyStrategy.set_consistency_level(2)
...
qat_pt = prepare(float_model)
...
qat_bc = export(qat_pt, example_inputs)

# 如果在prepare前设置 ConsistencyStrategy.set_consistency_level(0)，可以做如下检查
# print(qat_bc._high_precision_qpp)
# 需要是 true，不要用assert检查

2.2 profiler debug 工具用法

2.2.1 calib 产生的误差

float 精度与可视化结果正常，但 calib 后精度大幅下降——此时应运行 calib 阶段的 debug 流程。

from horizon_plugin_profiler import QuantAnalysis

# float.pt和calib.pt跑一致性敏感度和逐层对比
qa = QuantAnalysis(float_pt, calib_pt, "fake_quant", out_dir="./float_vs_calib")
qa.set_bad_case(bad_example_input)
qa.run()
qa.compare_per_layer()
qa.sensitivity()

2.2.2 pre_export 转查表 产生的误差

qat_pt 精度与可视化均正常，但 pre_export_pt 出现异常——问题出在转查表环节。

from horizon_plugin_profiler import QuantAnalysis
from horizon_plugin_pytorch.quantization.hbdk4 import pre_export

qa = QuantAnalysis(qat_pt, pre_export_pt, "pre_export", out_dir="./qatpt_vs_qatexportpt")
qa.set_bad_case(bad_example_input)
qa.run()
qa.compare_per_layer()
qa.sensitivity()

2.2.3 export 非转查表 产生的误差

pre_export_pt 一切正常，但 qat_bc 的可视化内容有误——表明 export 阶段出现了异常。

from horizon_plugin_profiler import QuantAnalysis

qa = QuantAnalysis(pre_export_pt, qat_bc, "export", out_dir="./pre_export_pt_vs_qatbc")

# torch 与 bc 可接受同一格式输入时，一起跑统计量
qa.set_bad_case(badcase)
qa.run()

# torch 与 bc 不可接受同一格式输入时，分开跑统计量，pt_badcase 与 bc_badcase 除格式外全部相同。
qa.set_bad_case(pt_badcase)
qa.run(run_baseline_model=True, run_analysis_model=False)

2.2.4 convert 产生的误差

pre_export_pt 与 qat_bc 均正常，但最终 quantized.bc 出现问题——需排查 convert 环节。

from horizon_plugin_profiler import QuantAnalysis
from horizon_plugin_pytorch.quantization.hbdk4 import pre_export

# qat.bc 和 quantized.bc 跑逐层对比
qa = QuantAnalysis(qat_bc, quantized_bc, "convert", out_dir="./qatbc_vs_quantizedbc")
qa.set_bad_case(bad_example_input)
qa.run()
qa.compare_per_layer()

# qat.export.pt 跑一致性敏感度，quantzed_bc起到占位作用

2.3 profiler debug 工具实例

2.3.1 标准实例

全流程示例代码，重点留意两处：不同阶段输入的具体类型，以及不同 debug 场景下配置参数的差异。

import torch
import torch.nn as nn
from typing import Dict, List
from hbdk4.compiler import load, Hbm
from horizon_plugin_pytorch import set_march, March
set_march(March.NASH_E)
from horizon_plugin_pytorch.quantization import prepare, set_fake_quantize, FakeQuantState
from horizon_plugin_pytorch.quantization import QuantStub
from horizon_plugin_pytorch.quantization.hbdk4 import export
from horizon_plugin_pytorch.quantization.qconfig_template import calibration_8bit_weight_16bit_act_qconfig_setter

2.3.2 input 中存在“task”字符串

部分模型的输入是 dict[str, tensor] 加上一个 task: list[str]——task 仅用于决定 forward 走哪个任务分支，部署时并非实际输入。

float 推理时的 example_input 结构如下：

需注意以下要点：

1. float、calib、export 阶段均需传入 task 输入，因为模型需要根据 task 确定执行哪个推理分支。
2. 进行 float vs calib 的 debug 时，浮点模型需区分任务，因此输入必须包含 task。
3. 进行 qat.bc vs quantized.bc 的 debug 时，bc 模型结构已固定，输入中不应再包含 task 参数。

全流程示例代码如下，再次提示：不同阶段的输入格式与 debug 配置切勿混淆。

import torch
import torch.nn as nn
from typing import Dict, List
from hbdk4.compiler import load, Hbm
from horizon_plugin_pytorch import set_march, March
set_march(March.NASH_E)
from horizon_plugin_pytorch.quantization import prepare, set_fake_quantize, FakeQuantState
from horizon_plugin_pytorch.quantization import QuantStub
from horizon_plugin_pytorch.quantization.hbdk4 import export
from horizon_plugin_pytorch.quantization.qconfig_template import calibration_8bit_weight_16bit_act_qconfig_setter

2.3.3 后处理添加与去除

debug 时一个常见困惑：模型后处理是否需要包含在输入中？这里给出统一说明。

若希望将后处理整合到 debug 工具中，可按以下方式编写：

当后处理封装为 class 时，对应代码示例如下：

import torch
import torch.nn as nn
from typing import Dict, List
from hbdk4.compiler import load, Hbm
from horizon_plugin_pytorch import set_march, March
from horizon_plugin_pytorch.quantization import prepare, set_fake_quantize, FakeQuantState
from horizon_plugin_pytorch.quantization import QuantStub
from horizon_plugin_pytorch.quantization.hbdk4 import export
from horizon_plugin_pytorch.quantization.qconfig_template import calibration_8bit_weight_16bit_act_qconfig_setter
from torch.quantization import DeQuantStub

运行上述示例后，产出物中将包含后处理相关的信息：