计算机视觉 / 系统课时
加载 ONNX 模型
加载 ONNX 模型
加载 ONNX 模型的第一步不是立即推理,而是先确认文件存在、OpenCV 能完成解析,并且得到的网络对象非空。本课将实现一个可直接运行的加载检查脚本。
学习目标
- 使用
cv2.dnn.readNetFromONNX加载模型 - 通过网络状态和层数量验证解析结果
- 按顺序定位路径、文件和算子兼容问题
准备模型与环境
示例假设已经安装 Python 版 OpenCV,并准备好一个有效的 .onnx 文件。安装包通常使用 opencv-python;模型必须是完整文件,不能是下载未完成的临时文件或只包含外部权重引用的残缺文件。
把下面脚本保存为 load_onnx.py,运行时通过参数传入模型路径。脚本只检查加载与解析,不要求提前知道模型输入尺寸。
使用 readNetFromONNX 加载
from pathlib import Path
import argparse
import cv2
def load_onnx(model_path: Path):
if not model_path.is_file():
raise FileNotFoundError(f"模型文件不存在: {model_path}")
try:
# 专用入口会按 ONNX 格式解析网络结构和权重。
net = cv2.dnn.readNetFromONNX(str(model_path))
except cv2.error as exc:
raise RuntimeError("OpenCV 无法解析该 ONNX 模型") from exc
if net.empty():
raise RuntimeError("模型已读取,但得到的网络对象为空")
return net
def main() -> None:
parser = argparse.ArgumentParser(description="检查 ONNX 模型能否被 OpenCV DNN 加载")
parser.add_argument("--model", required=True, help="ONNX 模型文件路径")
args = parser.parse_args()
model_path = Path(args.model)
net = load_onnx(model_path)
layer_names = net.getLayerNames()
print("模型加载成功")
print(f"模型路径: {model_path.resolve()}")
print(f"网络层数: {len(layer_names)}")
if __name__ == "__main__":
main()运行命令:
python load_onnx.py --model model.onnx预期输出:
模型加载成功
模型路径: <PATH>/model.onnx
网络层数: <N><PATH> 会替换为实际绝对路径,<N> 取决于模型结构。脚本没有打印固定层数,因此可用于不同的 ONNX 模型。
如何判断解析成功
加载过程满足以下条件时,可以认为网络结构已经被 OpenCV 初步解析:调用未抛出 cv2.error,net.empty() 返回 False,并且 getLayerNames() 能返回层名称集合。
这只是结构级检查。它不能证明输入张量设置正确,也不能保证 forward() 时所有动态形状和算子路径都能正常执行。完整验证还需要使用符合模型要求的输入完成一次前向推理。
典型失败的定位顺序
先检查路径。出现“模型文件不存在”时,优先确认当前工作目录、文件名大小写和命令行参数,而不是修改模型代码。
再检查文件。若 ONNX 文件大小异常、下载中断或依赖外部权重,OpenCV 可能在解析阶段报错。可以重新导出或重新复制模型,并确认文件可被其他 ONNX 工具正常读取。
最后检查兼容性。若异常信息指向未知节点、未实现算子或不支持的属性,通常需要升级 OpenCV、重新导出较兼容的 ONNX 算子集,或在导出前替换不受支持的网络操作。不要通过捕获异常后继续运行来掩盖解析失败。
验证边界
同一模型在不同 OpenCV 版本或不同构建方式下,解析结果可能不同。部署环境必须执行同一加载检查,不能只以开发机成功为依据。
加载成功后还应记录模型要求的输入尺寸、颜色通道顺序、缩放系数和均值。下一阶段创建输入 Blob 时,这些参数必须与训练或导出配置一致。
本课总结
readNetFromONNX是加载 ONNX 模型的直接入口- 文件存在、网络非空和层信息可读取构成基础解析检查
- 加载成功不等于推理正确,仍需完成输入与前向计算验证
下一课预告
下一课将把图像转换为 DNN 所需的 Blob,并设置输入尺寸、通道顺序与归一化参数。