中文

3.8.1

PTQ部署一致性分析

当您使用 PTQ（Post-Training Quantization）链路进行模型量化编译时，将按阶段生成以下产出物（其中 xxx 表示您的模型名称）：

文件名称	说明
xxx_original_float_model.onnx	原始浮点模型。对您的模型进行 `infer shape`，并对算子与张量进行合法性检查，作为后续处理的基准模型。
xxx_optimized_float_model.onnx	优化后的浮点模型。通过一系列等价模型优化提升模型的板端执行性能，包括但不限于如下操作：常量折叠（Constant Folding）算子替换（Operator Replacement）算子融合（Operator Fusion）冗余算子删除（Operator Elimination）算子重排（Operator Reordering）
xxx_calibrated_model.onnx	伪量化模型。根据您配置的 `quant_config`，对模型进行伪量化（Fake Quantization），在浮点域中模拟不同 bit 宽下的量化行为。
xxx_ptq_model.onnx	PTQ 模型。对查表类（LUT）等算子执行定点化处理，进一步贴近真实定点执行行为。
xxx_quantized_model.bc	定点模型（bc 格式）。将 ONNX 模型转换为 HBIR 模型(bc 格式)，并完成全模型定点化。
xxx.hbm	板端可执行模型。将 HBIR 模型编译为板端可直接加载和运行的指令集文件。

模型一致性与精度问题排查

如果您在实际部署中发现 模型精度明显下降，或怀疑不同阶段模型之间存在一致性问题，建议您通过 hb_verifier工具进行问题分析。

hb_verifier 支持对 任意两个阶段的模型 进行 逐节点输出的余弦相似度（Cosine Similarity）对比，用于定位误差来源。

注意

hbm 模型仅支持最终输出的一致性对比，无法进行逐节点分析。

参考命令如下：

hb_verifier \
  -m ./xxx_original_float_model.onnx,./xxx_quantized_model.bc \
  -i ./input.npy

常见分析结果与处理建议

情况一：各算子层及最终输出的余弦相似度均正常

各层余弦相似度未发现异常。
建议处理方式：
1. 优先检查精度验证流程 输入数据前处理流程（如归一化、色彩空间、维度顺序等）是否与训练阶段保持一致。
2. 若确认数据处理正确，请联系地平线技术支持人员进行问题分析。

情况二：所有算子层余弦相似度均异常

通常由 输入数据异常或格式不匹配 导致。
建议处理方式：
1. 检查输入数据的来源、格式及预处理逻辑。
2. 若确认输入数据正确，请联系地平线技术支持人员进行问题分析。

情况三：部分算子层余弦相似度明显偏低

表明误差可能在 特定模型阶段或特定算子 引入。
建议处理方式：基于中间产出物，使用 hb_verifier 进行 分阶段一致性对比分析，具体分析方法参见下方模型不同阶段的精度与一致性分析详细说明。

各阶段模型精度与一致性预期

xxx_original_float_model.onnx 到 xxx_optimized_float_model.onnx
- 该阶段仅包含 等价模型优化。
- 预期结果：输出余弦相似度应 ≥ 99.9%，模型精度表现应保持一致。
- 若发现精度下降，请联系地平线技术支持人员进行问题分析。

xxx_optimized_float_model.onnx 到 xxx_calibrated_model.onnx
- 该阶段引入 伪量化模拟，根据您配置的quant_config将算子模拟到对应的bit，此过程可能引入数值误差。
- 若发现 xxx_calibrated_model.onnx 精度下降：
  - 建议使用 PTQ精度debug工具进行精度调优。
  - 调优方法可参考：PTQ精度调优指导章节。

xxx_calibrated_model.onnx 到 xxx_ptq_model.onnx
- 该阶段我们对查表类算子的 定点化处理 可能引入误差。
- 若实测发现 xxx_ptq_model.onnx 精度下降，请联系地平线技术支持人员进行问题分析。

xxx_ptq_model.onnx 到 xxx_quantized_model.bc
- onnx模型转hbir模型(bc格式)在逻辑上应保持等价，但算子定点化可能进一步引入误差。
- 若发现 xxx_quantized_model.bc 精度下降，请联系地平线技术支持人员进行问题分析。

xxx_quantized_model.bc 到 xxx.hbm
- hbir模型(bc格式)转hbm模型的编译过程理论上不应引入数值不一致。
- 若发现 hbir模型(bc格式) 与 HBM 模型输出不一致，请联系地平线技术支持人员进行问题分析。