当您使用 PTQ 方案进行 ONNX 模型量化编译时，从 original_float.onnx 到最终部署使用的 hbm，中间还会经过 optimize、calibrate、ptq、quantize、compile 以及部署适配等多个步骤。如果这些步骤中的某一段引入了额外误差，就可能出现"训练侧结果正常，但部署侧结果不符合预期"的情况。

本章介绍在 ONNX 模型量化链路上如何避免这类问题，以及发生这类问题时如何按阶段初步定位、准备哪些产物再联系地平线技术支持。

#ONNX 量化链路涉及的模型产物

当您使用 PTQ 方案进行 ONNX 模型量化编译时，将按阶段生成以下产出物（其中 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_quantized_removed_model.bc	定点模型（bc 格式，含移除节点场景）。 模型量化过程中如存在移除输入/输出端节点的情况，会自动保存此模型。此种场景下，与 hbm 做一致性对比时，应使用本模型而不是 xxx_quantized_model.bc 与 hbm 对齐。
xxx.hbm	板端可执行模型。 将 HBIR 模型编译为板端可直接加载和运行的指令集文件。

#一致性分析路径快速判断

实际排查时，建议您先不要一上来就跑完整套工具，而是先用现象判断问题更可能落在哪一段，再进入下文对应阶段的详细分析。

当前现象	优先怀疑阶段	建议先做什么
optimized_float 与 original_float 输出不一致	模型优化阶段	等价优化在理论上不应有偏差，直接联系地平线技术支持，提供 original_float.onnx 与 optimized_float.onnx
calibrated 与 optimized_float 输出不一致	模型校准阶段	此阶段属于量化误差引入阶段，一定会有精度损失，与一致性概念不同。若量化后精度不达预期，优先使用 accuracy_debug 工具 做逐层敏感度分析，并参考 ONNX 模型精度调优指导 章节调整 quant_config。仍不达标再联系地平线技术支持
ptq 与 calibrated 输出不一致	查表算子定点化阶段	通常联系地平线技术支持，同时准备好 original / optimized / calibrated / ptq 全套 onnx
quantized.bc 与 ptq.onnx 输出不一致	onnx 转 hbir 定点化阶段	建议先导出一版不做任何模型修改的 quantized.bc 与 ptq.onnx 进行对比，排除模型修改本身引入的偏差。若仍不一致，优先排查 input_type_rt / mean-scale / Pyramid 或 Resizer 插入等结构性差异带来的输入准备偏差。仍不达标再联系地平线技术支持
hbm 与 quantized.bc（或 quantized_removed_model.bc）输出不一致	编译 / 板端部署阶段	若模型含浮点类型算子（fp16、fp32），quantized.bc 与 hbm 无法做到 bit 对齐一致，应以数据集精度、稳定 badcase 与多帧可视化为准，而不是单帧数值。除该特殊情况外，若模型无 CPU 算子，建议先用 hb_verifier 做整体输出一致性验证。若 pass，则自行排查板端前后处理代码，若 fail，则直接联系地平线技术支持。若模型含 CPU 算子，优先怀疑输入准备 / 板端前后处理 / stride 对齐 / 尾部输出类型平台差异（int32 vs fp32），参考下方 平台差异对一致性判读的影响 小节。无法定位再联系地平线技术支持

#平台差异对一致性判读的影响

一致性对比时，常见的平台差异要点如下（详细条目参考 平台差异说明 章节）：

• 尾部高精度输出类型差异：J6E/M 尾部高精度算子输出类型为 int32，J6B/H/P 尾部高精度算子输出类型为 fp32。板端后处理代码需要按平台适配，否则一致性对比会呈现为差异。

• nv12 stride 对齐差异：J6H/P 上 nv12 输入需满足 stride 64 对齐，J6E/M/B 上 nv12 输入需满足 stride 32 对齐。板端输入准备未按平台对齐时，hbm 输出与 quantized.bc 会出现不一致。

• input_no_padding / output_no_padding 影响：这两个开关是否打开会直接影响板端输入准备与 hbm 输出形式，一致性对比时的输入数据准备需要与实际打开状态匹配。

• quantized_removed_model.bc 与 hbm 对齐：模型量化过程中若存在移除输入/输出端节点，一致性对比应使用 quantized_removed_model.bc 与 hbm 对齐，而不是 quantized_model.bc。

#一致性分析可用工具

在按阶段排查前，先对齐一致性分析可用的工具及其用途：

工具	适用范围	什么时候用
hb_verifier	ONNX 与 ONNX / ONNX 与 HBIR / HBIR 与 HBIR 的余弦相似度对比，HBIR 与 HBM 的输出一致性对比	用于按任意两阶段模型做逐节点余弦相似度对比、定位误差来源。HBM 仅支持最终输出的一致性对比，无法进行逐节点分析
hb_analyzer	模型结构与算子部署分布分析	用于查看 CPU / BPU 算子分布、辅助判断结构差异是否会影响一致性判读
hbm_infer	X86 + 板端联合模式的 HBM 推理	用于以 X86 端做前后处理、板端 Server 执行实际推理的方式获取 HBM 输出，作为板端一致性对比的数据来源之一。注意实际推理仍在板端进行，与板端环境相关
hrt_model_exec	板端 HBM 推理	用于板端加载 HBM 实测输入输出，作为一致性对比的板端数据来源

#常见分析结果与处理建议

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

• 各层余弦相似度未发现异常。

• 建议处理方式：

  1. 优先检查精度验证流程 输入数据前处理流程（如归一化、色彩空间、维度顺序等）是否与训练阶段保持一致。

  2. 若确认数据处理正确，请联系地平线技术支持人员进行问题分析。

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

• 通常由 输入数据异常或格式不匹配 导致。

• 建议处理方式：

  1. 检查输入数据的来源、格式及预处理逻辑。

  2. 若确认输入数据正确，请联系地平线技术支持人员进行问题分析。

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

• 表明误差可能在 特定模型阶段或特定算子 引入。

• 建议处理方式：基于中间产出物，使用 hb_verifier 进行 分阶段一致性对比分析，具体分析方法参见下方各阶段一致性分析的详细说明。

#各阶段一致性分析

以下按阶段给出典型现象与理论预期、该阶段可用的工具、结构变化对一致性判读的影响提示，以及联系地平线时应保留的产物 checklist。

#xxx_original_float_model.onnx → xxx_optimized_float_model.onnx

典型现象与理论预期

• 该阶段仅包含等价模型优化（常量折叠、算子替换、算子融合、冗余算子删除、算子重排）。

• 预期输出余弦相似度应为 100%，模型精度表现应完全一致。

可用工具

• hb_verifier：做 ONNX → ONNX 的逐节点余弦相似度对比。

• hb_analyzer：确认优化前后算子部署分布是否符合预期。

结构变化影响提示

• 该阶段不涉及 input_type_rt / Pyramid / Resizer 等输入侧结构变化。

联系地平线时应保留的产物

• xxx_original_float_model.onnx。

• xxx_optimized_float_model.onnx。

• hb_compile.log。

• 用于复现的 input.npy。

#xxx_optimized_float_model.onnx → xxx_calibrated_model.onnx

该阶段引入伪量化模拟，根据您配置的 quant_config 将算子模拟到对应 bit 宽，此过程必然会引入数值误差，属于量化误差范畴，不属于一致性问题。若发现 xxx_calibrated_model.onnx 精度下降，请参考 ONNX 模型精度调优指导 章节做精度调优，本文不再展开。

#xxx_calibrated_model.onnx → xxx_ptq_model.onnx

典型现象与理论预期

• 该阶段对查表类（LUT）等算子执行定点化处理，可能进一步引入误差。

• 若 xxx_ptq_model.onnx 精度下降，通常需要联系地平线技术支持定位。

可用工具

• hb_verifier：做 ONNX → ONNX 的逐节点余弦相似度对比，定位查表算子的相似度变化。

结构变化影响提示

• 该阶段不涉及输入侧结构变化。

联系地平线时应保留的产物

• xxx_original_float_model.onnx。

• xxx_optimized_float_model.onnx。

• xxx_calibrated_model.onnx。

• xxx_ptq_model.onnx。

• hb_compile.log。

• 用于复现的 input.npy。

#xxx_ptq_model.onnx → xxx_quantized_model.bc

典型现象与理论预期

• ONNX 模型转 HBIR 模型（bc 格式）在逻辑上应保持等价，但算子定点化可能进一步引入误差。

• 若 xxx_quantized_model.bc 与 xxx_ptq_model.onnx 输出不一致，通常应优先排查输入准备侧的结构性差异。

可用工具

• hb_verifier：做 ONNX → HBIR 的逐节点余弦相似度对比。

• hb_analyzer：确认转换后的算子部署分布。

结构变化影响提示

• 当 input_type_rt 为 nv12 时，对应 quantized.bc 的输入 layout 为 NHWC，与 ptq.onnx 的输入形式不同，一致性对比时需要按对应 layout 准备输入数据，参考 数据准备 章节的推理准备小节。

• input_type_rt 到 input_type_train 的色彩转换、mean/scale 处理已固化到 quantized.bc 中，一致性对比的输入准备需要与之匹配。

• Pyramid / Resizer 输入通路会在模型输入端插入相应节点，直接使用 ptq.onnx 输入数据无法复现，应参考 数据准备 章节的推理准备小节配置输入。

联系地平线时应保留的产物

• xxx_ptq_model.onnx。

• xxx_quantized_model.bc。

• 使用的 quant_config.yaml / quant_config.json。

• hb_compile.log。

• 用于复现的 input.npy（包含匹配 input_type_rt 的对应版本）。

#xxx_quantized_model.bc → xxx.hbm

典型现象与理论预期

• HBIR 模型（bc 格式）转 HBM 模型的编译过程对整数定点算子理论上不应引入数值不一致。

• 若发现 bc 与 hbm 输出不一致，通常应优先排查板端输入准备、前后处理、stride 对齐及跨平台输出类型差异。

可用工具

• hb_verifier：做 HBIR → HBM 的最终输出一致性对比（HBM 不支持逐节点对比）。

• hbm_infer：在 x86 侧以 HBM 输入形式复现板端输出，排除板端环境差异。

• hrt_model_exec：在板端加载 HBM 实测输入输出，作为一致性对比的板端数据来源。

• hbdk4.compiler.hbm_perf：在 x86 侧生成 HBM 静态 perf 分析文件，交叉验证性能预期。

结构变化影响提示

• 若模型量化过程中存在移除输入/输出端节点，一致性对比应使用 quantized_removed_model.bc 与 hbm 对齐，而不是 quantized_model.bc。

• 板端 nv12 输入在 J6H/P 上需满足 stride 64 对齐要求，input_no_padding / output_no_padding 是否打开会影响板端 padding 处理与一致性对比的数据准备，详见 平台差异对一致性判读的影响 小节。

• 尾部高精度输出类型平台差异（J6E/M 为 int32，J6B/H/P 为 fp32）会体现在部署侧的输出解析代码上，若板端后处理未适配，会呈现为一致性差异。

联系地平线时应保留的产物

• xxx_quantized_model.bc（或 xxx_quantized_removed_model.bc）。

• xxx.hbm。

• 使用的 quant_config.yaml / quant_config.json。

• hb_compile.log。

• hbm_infer 的 x86 复现输出。

• hrt_model_exec 的板端实测输出。

• 用于复现的 input.npy 及对应板端输入。

#分析结束后的建议

• 若一致性对比结果指向量化配置或校准数据问题，参考 quant_config 说明 章节的平台经验模板小节，以及 ONNX 模型精度调优指导 章节。

• 若一致性对比结果指向结构性差异或工具侧误差，按各阶段"联系地平线时应保留的产物 checklist"整理产物，再联系地平线技术支持人员。