#常见故障处理

以下故障按 ONNX 模型量化编译链路的阶段分组组织。若已知具体报错关键字，可直接搜索对应关键字定位。若尚不确定问题落在哪一阶段，请先按分组概述判断范围，再看具体故障。

#通用故障 Segmentation fault: core dumped

该报错可能是物理机内存不足，工具版本老旧，模型非法，或工具 bug 导致。请通过以下方式进行排查：

1. 确认当前物理机是否存在其他任务正在占用内存（或更换至更大内存的开发机）。

2. 升级工具链版本至最新，重新转换模型。

3. 确认原始模型本身是否合法，如 onnx 模型是否能在 ONNX Runtime 中正确运行。

4. 若以上检查后仍无法解决，请联系地平线团队。

何时需地平线技术支持介入：完成以上 1-3 步排查后仍无法定位。

需要提供的产物清单：

• 原始 ONNX 模型（或 Caffe prototxt 与 caffemodel）。

• hb_compile.log。

• 报错时的 shell 输出或 core dump 信息。

• 使用的 yaml 配置文件。

#模型解析 / 优化阶段故障 ERROR The input model is invalid

模型解析阶段完成 Caffe 到 ONNX 的转换与算子命名，模型优化阶段执行常量折叠、算子替换、算子融合等等价优化。

该报错是模型本身非法导致，即不满足公版 ONNX Runtime 的检查逻辑，请自行检查模型。

何时需地平线技术支持介入：模型可在 ONNX Runtime 正常推理但工具仍报此错。

需要提供的产物清单：

• 原始 ONNX 模型。

• hb_compile.log。

• ONNX Runtime 推理结果说明。

#校准 / 量化阶段故障

校准阶段依据 quant_config 对算子做伪量化模拟并计算量化阈值，量化阶段对查表算子做定点化处理并生成 quantized.bc。

关于 Calibrated Cosine / Quantized Cosine 列出现 NaN 的详细分析（含 where -Inf、concat / equal 传播全 0 tensor 等场景），参考 ONNX 模型量化常见问题章节中的 Calibrated Cosine 出现 NaN 的几种情况。

quant_config 配了但没生效相关分析，参考 ONNX 模型量化常见问题章节中的 quant_config 配置未生效。

#编译阶段故障 ERROR Wrong mean_value num received

编译阶段将定点化后的 HBIR 模型编译为板端可加载运行的 hbm 指令集文件。

ERROR yaml file parse failed. Please double check your config file inputs
ERROR Wrong mean_value num received. input mean_value num n is not equal to input num m

该报错是 yaml 文件中的 mean_value 参数数量与模型输入节点数量不一致导致，请对应检查。 不同输入节点的 mean_value 需要用 “;” 号隔开； 若模型为混合多输入模型（即同时包含图像和 featuremap 输入节点），则需要与 input_name 对应，用 "None" 给 featuremap 节点的 mean_value 参数占位。

何时需地平线技术支持介入：按照上述规则修正后仍报错。

需要提供的产物清单：

• 使用的 yaml 配置文件。

• hb_compile.log。

#板端 / 部署阶段故障

板端 / 部署阶段涉及 hbm 上板加载、板端推理与前后处理适配。此阶段的一致性问题排查参考 ONNX 模型部署一致性分析 章节。

上板性能不及预期的排查方向，参考 ONNX 模型量化常见问题章节中的 上板性能不及预期。

quantized.bc 精度正常但 hbm 精度掉点的排查方向，参考 ONNX 模型量化常见问题章节中的 quantized.bc 精度正常但 hbm 精度掉点。