J6 Plugin Precision Tuning

J6 Horizon Plugin PyTorch 精度调优

核心原则

解决 PyTorch 侧 的训练/校准精度问题。

按下面顺序收敛问题：

1. 先看 Calibration / QAT 哪一段开始掉点。
2. 用 QuantAnalysis 围绕 badcase 做逐层比较和敏感度分析。
3. 只有基础问题基本排干净后，再做 int8 / int16 / fp16 混合精度取舍。

不要直接把 float 模型和 QAT 模型拿来做常规逐层比较。 常规精度 debug 优先比较 float vs calibration(fake_quant)；QAT 训练异常时，更多是用 float finetune、关 fake quant、lr=0 之类手段排查训练 pipeline。

执行前门禁

在给出调优建议、修改 qconfig、或要求用户重跑大量实验前，先确认下面信息够不够：

推荐补充信息

• 校准数据量、batch size、observer 类型。
• QAT 学习率、weight decay、是否 freeze BN。
• 是否已经试过关闭 fake quant、lr=0、float finetune。

如果缺少这些信息且会影响判断，先要求补充；不要在没有 badcase 或没有阶段归属的情况下直接开混合精度“盲调”。

先判断问题更像哪一类

正确 API 用法

1) prepare、QconfigSetter 与模板

当前仓库主推的混合精度配置方式是 QconfigSetter + templates：

import torch

from horizon_plugin_pytorch.quantization import (
    QconfigSetter,
    get_qconfig,
    prepare,
    qint8,
    qint16,
)
from horizon_plugin_pytorch.quantization.qconfig_setter import (
    ConvDtypeTemplate,
    MatmulDtypeTemplate,
    ModuleNameTemplate,
    SensitivityTemplate,
)

setter = QconfigSetter(
    reference_qconfig=get_qconfig(),
    templates=[
        ModuleNameTemplate({"": torch.float16}),
        ConvDtypeTemplate(input_dtype=qint8, weight_dtype=qint8),
        MatmulDtypeTemplate(input_dtypes=qint8),
        SensitivityTemplate(
            sensitive_table=table,
            topk_or_ratio=0.2,
            sensitive_type="activation",
            low_precision_dtype=qint8,
            high_precision_dtype=qint16,
        ),
    ],
)

qat_model = prepare(model, example_inputs=example_inputs, qconfig_setter=setter)

说明：

• SensitivityTemplate 是当前仓库里真实存在的模板接口。
• topk_or_ratio 可以传整数或比例。
• sensitive_type 取值为 activation / weight / both。
• ModuleNameTemplate 常用于 J6P 场景下把默认输出先设成 torch.float16。

2) get_qconfig

get_qconfig 支持的 observer 不是任意类，当前实现只接受：

• MinMaxObserver
• MSEObserver
• HistogramObserver

接口签名：

get_qconfig(
    observer=HistogramObserver,
    in_dtype=qint8,
    weight_dtype=qint8,
    out_dtype=qint8,
    fix_scale=False,
)

注意：此接口中的 fix_scale 表示对应的伪量化不再更新 scale。和 fixed_scale 不同，fixed_scale 是针对特定模块的特定输入/输出设置一个固定值域，而不是简单地禁止更新 scale。

如果要表达更复杂的自定义量化行为，优先通过 QConfig / QconfigSetter 模板组合实现，而不是强行把所有逻辑塞进 get_qconfig(...)。

3) FixedScaleObserver 正确用法

FixedScaleObserver 适用于需要强制固定 scale 和 zero_point 的场景（如输入图像归一化到 [0,1] 后的 QuantStub、输出层需要固定值域等）。它不会根据输入数据统计 scale，而是始终返回构造时传入的固定值。

务必使用 observer_v2 中的 FixedScaleObserver，observer 模块中的版本已废弃。

直接构造

from horizon_plugin_pytorch.quantization.observer_v2 import FixedScaleObserver
from horizon_plugin_pytorch.quantization import qint8

# 构造时传入 scale 和 zero_point
observer = FixedScaleObserver(scale=1 / 128.0, zero_point=0, dtype=qint8)

参数说明：

• scale（必传）：固定 scale 值，必须 > 0。也可传 torch.Tensor（per-channel 场景）。
• zero_point：固定 zero_point 值，默认 0。
• dtype：量化数据类型，默认 qint8，也可选 qint16。
• qscheme：量化方案，默认 torch.per_tensor_symmetric。
• ch_axis：per-channel 的通道轴，默认 -1（per-tensor）。

通过 QconfigSetter + ModuleNameTemplate 的 threshold 设置（推荐）

推荐使用 ModuleNameTemplate 的 threshold 参数来设置固定值域。模板内部会自动将 threshold 转换为 FixedScaleObserver 的 scale（计算方式：scale = threshold / (-quant_min)），无需手动构造 QConfig。

from horizon_plugin_pytorch.quantization import (
    QconfigSetter,
    get_qconfig,
    prepare,
    qint8,
    qint16,
)
from horizon_plugin_pytorch.quantization.qconfig_setter import ModuleNameTemplate

# 通过 threshold 设置固定值域：数据范围为 [-threshold, threshold]
setter = QconfigSetter(
    reference_qconfig=get_qconfig(),
    templates=[
        ModuleNameTemplate({
            "": qint8,                              # 全局默认 dtype
            "quant": {"threshold": 1.0},            # quant 模块 output 的 fixed scale，scale = 1.0 / 128
            "backbone.conv1": {
                "dtype": qint16,                     # 同时设置 dtype 和 threshold
                "threshold": {"output": 1.0, "input": 0.5},  # 分别设置 output 和 input 的 fixed scale
            },
        }),
    ],
)
model = prepare(model, example_inputs=example_inputs, qconfig_setter=setter)

ModuleNameTemplate 的 config_mapping 用法：

• 值为 dtype：应用到 output，如 {"conv": qint16}
• 值为 dict 且含 dtype/threshold 键：按 key-value 对指定，如 {"conv": {"dtype": qint16, "threshold": 1.0}}
• 值为 dict 且不含 dtype/threshold 键：当作完整的 dtype 映射，如 {"conv": {"output": qint16, "weight": qint8}}
• threshold 为 float：应用到 output，如 {"conv": {"threshold": 1.0}}
• threshold 为 dict：分别指定各端口，如 {"conv": {"threshold": {"input": 1.0, "output": 0.5}}}
• dtype 和 threshold 可同时给出

4) HistogramObserver.reset_scale

做过一次校准后，可以在 不重跑 calibration 数据 的前提下重算 scale：

from horizon_plugin_pytorch.quantization import qint8, qint16
from horizon_plugin_pytorch.quantization.observer_v2 import HistogramObserver

HistogramObserver.reset_scale(
    calib_model,
    method="percentile",
    method_kwargs={"percentile": 0.999999},
    dtype=qint8,
)

HistogramObserver.reset_scale(
    calib_model,
    method="percentile",
    method_kwargs={"percentile": 1.0},
    dtype=qint16,
)

可选地使用 prefix 只重算局部模块。调完后重新保存 state_dict 再评测。

5) QuantAnalysis

当前推荐从包入口导入：

from horizon_plugin_profiler import QuantAnalysis

典型流程：

qa = QuantAnalysis(float_model, calibration_model, "fake_quant")
qa.auto_find_bad_case(dataloader)
qa.run()
qa.compare_per_layer()
qa.sensitivity()

关键点：

• analysis_model_type 做 PyTorch 精度调优时常用的是 "fake_quant"。
• run() 前必须先 auto_find_bad_case(...)、set_bad_case(...) 或 load_bad_case(...)。
• load_bad_case() 默认读 out_dir/all_badcase_info.pt。

6) fake quant 状态切换

from horizon_plugin_pytorch.quantization import FakeQuantState, set_fake_quantize

set_fake_quantize(model, FakeQuantState.CALIBRATION)
set_fake_quantize(model, FakeQuantState.VALIDATION)
set_fake_quantize(model, FakeQuantState._FLOAT)

用途：

• CALIBRATION：只更新统计量，不做真实伪量化，通常配合 model.eval()。
• VALIDATION：固定 scale，开启伪量化，用于评测 calibration / qat 模型。
• _FLOAT：仅供诊断。关闭 fake quant，用于判断训练 pipeline 或 fake quant 使用方式是否有明显问题，不应把它当成正常精度结论。

7) QAT 模式

如果浮点训练里用了 freeze BN 技巧，QAT 中需要显式切换：

from horizon_plugin_pytorch.quantization import QATMode, set_qat_mode

set_qat_mode(QATMode.WithBN)

分阶段排查流程

1. Calibration 精度问题

适用：Calibration 后精度不达标，或者全 int16 calibration 都崩。

建议顺序：

1. 用 float_model 和 calibration_model 创建 QuantAnalysis。
2. 先 auto_find_bad_case(dataloader)，不要一开始就人工拍脑袋选样本。
3. 再 run() + compare_per_layer() 看误差从哪里开始放大。
4. 必要时结合 HistogramObserver.reset_scale(...) 试 mse / percentile。
5. 如果敏感算子大多是 QuantStub、共享模块或固定值输入相关节点，优先结合已有结构 / qconfig 检查结果，判断是不是设置特定 scale、输入值域或共享模块拆分问题。

观察原则：

• 极值明显被截断：更像 scale 太小、统计范围不够、缺特定的 fixed scale。
• 极值没怎么截断，但误差仍大：更像 dtype 分辨率不够、数值范围太宽、需要升高精度。

floatvscalib debug 结果解读

当用户要求解读 floatvscalib（float vs calibration）debug 结果时，必须在执行任何分析之前先读取 references/debug-analysis-framework.md。该文档包含完整的误差分类标准、逐算子分析流程和修复方案对照表，是 floatvscalib 场景的核心执行框架，不可跳过。

读取后严格按以下流程执行：

1. 提取 top-5 敏感算子列表：从 output_xxx_sensitive_ops.txt 中提取算子名和 ATOL 值
2. 逐算子检索逐层对比数据：对每个 top-5 算子，必须通过 Bash 执行 grep "<算子名>" compare_per_layer_out.csv 提取该算子的完整数据行。⛔ 禁止使用 Read 工具全文读取 compare_per_layer_out.csv——该文件通常有数千行（>500KB），Read 只返回开头部分（backbone 层），会遗漏 decoder 等后部算子数据。从 grep 结果中提取以下字段：
   • base_model_min, base_model_max（float 模型的值域）
   • analy_model_min, analy_model_max（calibration 模型的值域）
   • COSINE, ATOL（精度指标）
   • max_qscale_diff（scale 差异）
3. 误差类型分类：对比 base_model 和 analy_model 的 min/max 值域——值域被截断为截断误差，值域接近但精度仍差为舍入误差
4. 差异化修复方案：
   • 截断误差 → 从 abnormal_layer_advisor.csv 读取 Set fixed scale X 建议值 + 增加样本量
   • 舍入误差 → 提升 dtype 到 qint16，并给出具体的 fix-scale 数值建议（基于算子实际最大范围）
5. 结构化输出：对每个 top-5 算子输出排名、值域对比、误差类型和具体修复建议

不要将所有精度问题统一归为"提升 dtype"——必须先做误差归因，再给差异化建议。

2. QAT 精度或训练异常

适用：calibration 还行，但 QAT 精度崩、loss 不收敛、出现 nan。

按下面顺序排查：

1. 去掉 prepare，直接用 QAT pipeline finetune float 模型，看是否仍崩。若仍崩，更像训练 pipeline 没对齐。

2. 关掉 fake quant：

   set_fake_quantize(model, FakeQuantState._FLOAT)
   

   若关闭后训练正常，优先怀疑 fake quant 使用方式或量化配置。

3. 把 lr 设为 0。如果 lr=0 仍与 calibration 精度差很多，优先怀疑 pipeline 或 checkpoint 对齐问题。

4. 再去调学习率、scheduler、weight decay、数据增强强度。

对于 QAT 调参，不要忽略这些共识：

• QAT 其余配置尽量与 float 训练对齐。
• 一般不建议继续保留 warmup。
• 校准精度较好时，可以尝试固定 input / output scale；较差时不一定适合固定。

3. 混合精度调优

混合精度不是一开始就把最终比例拍死，而是：

1. 先得到一个“精度上限比较靠谱”的高精度基线。
2. 再逐步减少高精度算子比例，直到找到兼顾性能与精度的配置。

J6E/M

建议顺序：

1. 先做 全 int16，确认上限并排除使用问题。
2. 再尝试 全 int8。
3. 全 int8 不达标时，基于敏感度结果做 int8 / int16 混合精度。
4. 若全 int16 仍不够，再考虑少量 fp16，而不是过早全面铺开 fp16。

J6P

J6P 浮点能力更强，通常更自然的起点是：

• 非 GEMM 算子先走 torch.float16
• Conv / Matmul 等 GEMM 算子从 int8/int16 开始权衡

典型模板思路：

setter = QconfigSetter(
    reference_qconfig=get_qconfig(),
    templates=[
        ModuleNameTemplate({"": torch.float16}),
        ConvDtypeTemplate(input_dtype=qint16, weight_dtype=qint16),
        MatmulDtypeTemplate(input_dtypes=qint16),
    ],
)

4. 如何用敏感度结果落到配置上

优先推荐 SensitivityTemplate，因为它是当前仓库里的主线接口。

SensitivityTemplate(
    sensitive_table=table,
    topk_or_ratio=0.2,
    sensitive_type="activation",
    low_precision_dtype=qint8,
    high_precision_dtype=qint16,
)

经验：

• 先统一比例粗调，比如 20%、10%、5%。
• 精度达标后，再细调单个输出对应的敏感度表。
• 若敏感度表带 flops，性能优化时可以优先保留大算子为低精度。

5. 兼容旧工程时的旧式 setter

仓库里仍有旧式接口，但它们在 qconfig_template.py，不属于当前更推荐的模板主线：

from horizon_plugin_pytorch.quantization.qconfig_template import (
    sensitive_op_calibration_8bit_weight_16bit_act_qconfig_setter,
    sensitive_op_qat_8bit_weight_16bit_act_qconfig_setter,
)

可以用于兼容旧代码，但新方案优先使用 QconfigSetter + SensitivityTemplate。

输出报告模板

每次分析结束，都按下面格式输出，避免只给零散命令：

## 结论摘要
- 当前最可能的问题阶段：calibration / qat / mixed precision / 暂不能判断
- 主要证据：...

## 已确认事实
- 平台 / march：...
- 当前模型：float / calibration / qat
- 稳定指标：...
- badcase：...

## 已做检查
1. ...
2. ...

## 关键发现
- 第一个明显放大误差的算子：...
- 更像是截断误差 / 舍入误差 / 共享模块 / qconfig 错误 / 训练 pipeline 问题
- 相关产物：`compare_per_layer_out.txt` / `output_xxx_sensitive_ops.txt` / 其他已有分析结果

## 下一步最小动作
- ...

## 需要补充的输入
- ...

如果证据还不够，明确写“暂不能判断”，不要为了给结论而猜根因。

常见误区

何时不该用这个 skill

以下情况应切到别的 skill 或别的问题域：

• 问题已经确认出在 export / convert / compile / hbm / 板端。
• 用户当前问题还停留在 prepare 后的结构 / 融合 / qconfig 检查阶段。
• 用户要做的是 HBIR 导出，而不是 PyTorch 侧精度调优。
• 用户要分析的是部署一致性，而不是 calibration / QAT 阶段精度。

此时不要继续在 PyTorch 精度调优路径里打转。

floatvscalib 场景自动加载文档

以下文档在 floatvscalib debug 场景下必须立即加载，不要跳过：

按需加载参考文档

以下文档只在相关任务时才需要读取，不必在每次进入本 Skill 时全部加载：

（当前无其他按需加载文档）