计算机视觉 / 系统课时
排查模型推理异常
排查模型推理异常
模型推理异常应先区分“模型没加载起来”“输入张量不符合模型约定”“前向计算失败”和“输出数值可计算但语义错误”四类问题。按阶段定位后,再分别检查模型格式、输入尺寸、预处理、输出形状和算子支持,比反复改参数更快。
学习目标
- 根据异常发生阶段区分模型加载、输入、前向计算和输出解析问题
- 用最小 DNN 脚本检查 ONNX 模型能否加载并完成一次前向推理
- 识别尺寸、颜色顺序、缩放方式、输出形状和不受支持算子的典型信号
先确定异常发生在哪个阶段
OpenCV DNN 的问题通常沿固定链路出现:模型文件先被解析成网络,再将图像预处理成 blob,随后执行 forward(),最后由业务代码解释输出。如果把这些阶段混在一起,加载错误很容易被误判成输入错误,输出解析错误也容易被误判成模型本身坏了。

最先记录三类事实:使用的模型文件、OpenCV 版本,以及异常是在加载时还是 forward() 时抛出。错误文本可以帮助判断阶段,但不同后端和版本的具体措辞可能不同,因此不要依赖某一句固定报错。
用最小脚本验证加载与前向计算
下面示例面向 ONNX。它接收模型路径和期望输入宽高,构造全零测试图像,仅用于验证“网络能否完成一次前向计算”和“输出是否为有限数值”,不用于判断模型精度。
import argparse
import cv2
import numpy as np
parser = argparse.ArgumentParser()
parser.add_argument("model", help="ONNX 模型路径")
parser.add_argument("--width", type=int, default=640)
parser.add_argument("--height", type=int, default=640)
args = parser.parse_args()
try:
net = cv2.dnn.readNetFromONNX(args.model)
except cv2.error as exc:
print("model_loaded=False")
print(f"load_error={exc}")
raise SystemExit(1)
print("model_loaded=True")
image = np.zeros((args.height, args.width, 3), dtype=np.uint8)
blob = cv2.dnn.blobFromImage(
image,
scalefactor=1.0 / 255.0,
size=(args.width, args.height),
mean=(0, 0, 0),
swapRB=True,
crop=False,
)
print(f"input_blob={blob.shape}")
net.setInput(blob)
try:
names = net.getUnconnectedOutLayersNames()
outputs = net.forward(names)
except cv2.error as exc:
print("forward_ok=False")
print(f"forward_error={exc}")
raise SystemExit(2)
print("forward_ok=True")
print(f"output_count={len(outputs)}")
for index, output in enumerate(outputs):
array = np.asarray(output)
print(f"output_{index}_shape={array.shape}")
print(f"output_{index}_finite={np.isfinite(array).all()}")运行命令
python diagnose_dnn.py "<PATH>" --width 640 --height 640预期输出
model_loaded=True
input_blob=(1, 3, 640, 640)
forward_ok=True
output_count=<VALUE>
output_0_shape=<VALUE>
output_0_finite=True<PATH> 替换为实际 ONNX 文件路径;<VALUE> 由模型的输出层数量与张量形状决定。若在加载阶段就退出,问题与输入图像无关;若加载成功而 forward() 失败,再继续检查输入规格和算子支持。
按症状定位根因
模型加载失败时,先确认路径指向真实文件,文件没有下载不完整,并且调用的加载接口与模型格式一致。ONNX 使用 readNetFromONNX() 最直观;其他框架可能需要成对的配置文件与权重文件。若错误指向某个无法解析或不支持的算子,应优先检查模型导出方式、opset、动态图结构,以及当前 OpenCV DNN 后端是否支持该算子,而不是修改输入尺寸碰运气。
输入尺寸不符时,要核对模型真正要求的宽高、通道数和布局。blobFromImage() 产生的常见布局是 NCHW,但模型还可能要求固定尺寸、动态尺寸或特定批次大小。尺寸正确也不代表预处理正确:BGR/RGB 顺序、scalefactor、mean、是否 letterbox、是否裁剪都会改变推理结果。
如果 forward() 能运行,但输出全是 NaN、Inf 或数值明显异常,先检查输入张量本身是否包含非法值,再检查归一化范围是否放大了数据。输出数值有限但检测框、类别或分数完全错误,则应把注意力转到输出 shape 和解码规则;不同模型的输出维度、坐标格式、是否已经过 sigmoid 或 NMS 都可能不同。
修复后做一致性验证
修复应使用一张已知内容的固定测试图,而不是每次换输入。记录输入原图尺寸、blob shape、输出层名称、每个输出张量 shape,以及是否包含 NaN/Inf;这些信息在升级 OpenCV、替换模型或更换后端后都可以直接对比。
若问题来自不受支持的算子,可选择重新导出为更兼容的 ONNX 图、调整模型结构,或改用能够完整执行该模型的推理后端。若问题来自输出解析,则应以模型导出端定义为准重新实现后处理。最终验收不是“程序不报错”,而是同一测试图在固定预处理下能得到形状正确、数值有效、语义也符合预期的结果。