本文原发表于OpenCV.org官方网站,经OpenCV.org授权转载。

OpenCV的DNN模块允许用户在读取图像、处理视频和绘制结果的同一应用程序中运行训练好的神经网络。用户可以将模型导出为ONNX格式,用OpenCV加载后直接使用其预测结果,而无需在应用程序中加载训练框架。

OpenCV 5在这一工作流程的基础上,构建了一个全新的推理引擎,可支持更广泛的现代ONNX模型。在本教程中,我们将使用它完成两项任务:基于YOLO26的目标检测和基于RF-DETR的实例分割。前者为每个检测到的物体绘制边界框,后者则添加显示每个实例所属像素的掩码。

两个示例均在CPU上运行,并将结果保存为图像文件。教程包含Python和C++两种实现方式。在完成模型导出后,Python推理仅需OpenCV、NumPy和Python标准库;C++推理则仅需OpenCV和C++标准库。

版本说明:本文示例在OpenCV 5.0.0版本上执行测试。当前5.x开发版API已于2026年9月20日单独核查:其内置引擎名为ENGINE_OPENCV,而5.0.0版本中则称为ENGINE_NEW。下文代码对两种命名方式均做了兼容处理。关于上一版本教程,请参见《OpenCV 4 DNN模块》。

DNN模块的作用是什么

典型的部署流程包含四个步骤:准备图像、运行网络、解读输出结果,以及展示或使用预测结果。OpenCV提供了图像处理函数和推理API,而应用程序需要提供模型所需的预处理和输出解码逻辑。

训练过程仍然是独立的步骤。在本文示例中,原始模型包负责下载预训练权重并导出ONNX文件。应用程序随后使用cv2.dnn.readNetFromONNX()加载.onnx文件,而不会加载原始的PyTorch检查点文件。

当应用程序已经使用OpenCV时,这种分离方式十分有用。同一帧图像可以依次经过缩放、推理、绘制和视频输出等环节,而部署时无需使用训练框架。

OpenCV 5带来了哪些变化

最大的变化是重写了DNN推理引擎,改进了对动态形状、子图和现代ONNX特性的支持。OpenCV 5还增加了可选的ONNX Runtime集成,其示例覆盖的网络范围也更广,包括视觉语言模型。详见OpenCV 5发布概览。

引擎的选择发生在模型加载阶段。当前5.x开发版API定义了以下几种选项:

对于暴露当前API的构建版本,显式选择方式如下所示。当前API已不再暴露ENGINE_NEW或ENGINE_CLASSIC。DNN_BACKEND_OPENCV是一个独立的后端常量,并非上述提到的引擎参数。这些定义已在当前API源码中得到核实,并固定于被检查的提交版本。

用于测试的已发布5.0.0版本包使用的是较早的选择API:ENGINE_NEW可显式选择重写后的引擎,而ENGINE_AUTO会在加载过程中先尝试该引擎,如失败则回退到传统引擎。详见5.0.0版API定义。完整示例代码优先使用ENGINE_OPENCV(如果可用),否则使用ENGINE_NEW。

在Python示例中,DNN_ENGINE保存选定的枚举值;engine_name是用于日志记录的本地字符串。这两个变量均不属于cv2.dnn的属性。

建议使用具名常量,因为其数值在不同API版本间已发生变化。脚本要求取消设置OPENCV_FORCE_DNN_ENGINE环境变量,以避免旧的数值覆盖选中其他引擎。当前5.x API不假定存在传统引擎的回退机制。

新引擎的性能表现如何

OpenCV项目公布了与ONNX Runtime 1.25.1对比的CPU推理测量数据。以下是YOLO26 Nano的测试结果,保留了原始数据来源中使用的硬件标签:

数值越低越好。在报告中的Apple M1和AMD配置下,OpenCV表现更快;而在其他三种配置下,ONNX Runtime表现更快。这些数据是在列出的系统上不同运行时之间的比较,而非OpenCV 4到OpenCV 5性能提升的测量结果。数据来源:完整的OpenCV 5 DNN基准测试。

已发布的表格未提供足够详细的信息,如模型导出方式、输入形状、确切的CPU型号、线程设置或计时流程,因此无法完全复现每一项数值。建议使用这些数据来确定值得测试的配置,然后针对自己的模型和应用程序进行实际测量。下文教程中使用的是独立导出的模型;其输出图像仅用于展示推理效果,并非对上述基准测试的复现。

安装OpenCV 5

请使用Python 3.11或更高版本;本文示例在Python 3.14.3上经过测试。建议在全新的虚拟环境中开始。由于示例代码会保存文件而不会打开图形界面窗口,因此使用无头(headless)版本的软件包即可满足需求。

版本检查应显示5.0.0。上述软件包版本号用于示例验证;请使用两个软件包均支持的Python版本。请勿在同一环境中安装多个OpenCV wheel变体版本,因为它们共享cv2命名空间。如果您的应用程序需要OpenCV图形界面窗口,请选择opencv-python而非无头版本。详见OpenCV Python软件包说明。

模型导出步骤需要额外的依赖项。建议将这些依赖项保存在独立环境中,以避免模型包替换掉用于推理的OpenCV安装。一旦导出完成,ONNX文件及其标签文件即可复制到推理应用程序中使用。

构建C++示例

本教程提供的下载包中包含两个示例的C++版本、共享的dnn_engine.hpp文件,以及用于一起构建这两个示例的CMakeLists.txt文件。模型导出仍需使用下文所述的Python环境。一旦ONNX文件生成完毕,C++推理仅需OpenCV和C++标准库支持。

需安装带有C++头文件、库文件的OpenCV 5,并包含core、imgproc、imgcodecs和dnn模块。仅安装Python wheel包无法提供此类C++开发环境配置。下载包中的README文件包含用于验证测试的源码构建方法。此外还需要CMake和支持C++17标准的编译器。

从解压后的下载目录(即包含CMakeLists.txt的目录)中运行相关命令即可。

请将OpenCV_DIR设置为包含OpenCVConfig.cmake文件的OpenCV 5目录。CMake配置会检查您的头文件提供的具名引擎常量:它会优先选用ENGINE_OPENCV,并在已测试的5.0.0发布版本中支持ENGINE_NEW。请将共享头文件和CMake文件与示例文件保存在一起。代码中未硬编码任何引擎编号。

以下命令假定在macOS或Linux上进行单一配置构建。如果在Windows上使用Visual Studio,请从build\Release目录运行可执行文件,并使用.exe后缀。在Windows终端中输入多行shell命令时,请将其整理为一行。C++命令行解析器使用--option=value格式。

示例一:使用YOLO26进行目标检测

本示例将使用YOLO26 Nano模型,固定输入尺寸为640×640。该示例使用其端到端的检测输出:每个预测结果已包含边界框、置信度分数和类别ID,推理代码中无需单独的非极大值抑制(NMS)步骤。关于模型家族及可用任务的详细信息,请参见Ultralytics YOLO26官方文档。

一次性导出模型

下载示例代码并打开yolo26文件夹。该轻量级下载包包含脚本、示例图像、标签文件和验证记录;运行导出脚本即可获取模型文件。请创建独立的导出环境,并安装指定版本的依赖项。

在Windows系统中,请将.venv-export-yolo/bin/python替换为.venv-export-yolo\Scripts\python.exe。直接使用该解释器可以使导出安装环境与当前使用的推理环境保持独立。

该导出脚本会下载预训练的yolo26n.pt检查点文件和示例图像bus.jpg,根据模型的类别名称写入coco80.json文件,并生成yolo26n.onnx文件。其关键设置如下:

该方法配置固定使用Ultralytics 8.4.27版本。在该版本中,end2end=True用于选择端到端检测头,nms=False则避免添加单独的NMS封装层。导出选项在不同软件包版本间可能有所变化,因此请将所提供的依赖文件与导出脚本保持配套使用。经测试的计算图接受[1, 3, 640, 640]格式输入,并返回[1, 300, 6]格式输出;每行数据格式为[x1, y1, x2, y2, 置信度, 类别ID]。坐标为640×640输入图像中的像素坐标。上述细节已通过对照导出计算图和特定版本的Ultralytics检测头进行核实。

准备图像并运行推理

YOLO模型要求输入为RGB像素,并将数值缩放至0到1范围内。我们在保持图像宽高比的同时进行缩放,并使用数值114对剩余区域进行填充,这种处理方式称为letterboxing(信箱式填充)。为了将预测结果绘制到原始图像上,需要先减去填充部分,再除以缩放比例。

请注意,代码会将剩余的填充像素分配到相对的两个边缘。如果填充的像素数为奇数,则会将多出的一个像素分配给其中一个边缘,以确保输入尺寸精确为640×640。

请将以下内容保存为tutorial_yolo26.py文件,或直接使用下载包中提供的该文件。在OpenCV推理环境下,从yolo26文件夹中运行该脚本即可。

C++版YOLO26实现

在导出同一个yolo26/yolo26n.onnx模型后,从解压后的下载目录中运行以下命令。

该C++版本使用了相同的640×640信箱式填充变换、RGB数值缩放、0.35置信度阈值,以及端到端输出解码方式,并可在不使用单独NMS步骤的情况下将边界框映射回原始图像。下文完整源代码使用了下载包中提供的共享引擎选择器。

所提供代码的实际输出结果:在0.35置信度阈值下检测出一辆公交车和四个行人。源图像为Ultralytics提供的公交车示例图片。图像左右边缘部分可见的行人也各自获得了独立的边界框。

如需处理您自己的图像,可使用下载包中更灵活的detect_yolo26.py脚本。

示例二:使用RF-DETR进行实例分割

边界框只能告诉我们物体所在的位置,而实例掩码则能添加其可见轮廓,将物体的像素与邻近物体及背景区分开来。当应用程序需要的不仅仅是矩形区域时(例如在测量物体可见面积之前将其分离出来),这一功能就十分有用。

本示例将使用RF-DETR Seg Nano,即该系列的实例分割变体模型,其输入尺寸为312×312。RF-DETR分割文档详细介绍了该模型系列。仅支持检测功能的RF-DETR检查点无法提供本示例所需的掩码输出。

导出分割模型

打开下载包中的rfdetr文件夹,并创建其导出环境。

在Windows系统中,请将.venv-export-rfdetr/bin/python替换为.venv-export-rfdetr\Scripts\python.exe。

依赖文件中固定使用RF-DETR 1.6.3版本、PyTorch 2.10.0版本,以及兼容的导出依赖项。该导出脚本会加载预训练的分割检查点文件,并生成models/inference_model.onnx文件,批量大小为1,固定输入尺寸为312×312,ONNX操作集版本为17。关于通用导出流程,请参见RF-DETR的导出文档;若要复现这一特定计算图,请使用提供的指定版本依赖项。

导出后的模型具有三个输出项。

所谓对象查询(object query),是指网络生成的候选物体。在后处理过程中,其边界框、类别分数和掩码必须始终与同一查询索引保持关联。

使用RF-DETR的预处理和输出解码方式

输入为RGB格式,直接缩放至312×312尺寸,数值缩放至0到1范围,并使用均值[0.485, 0.456, 0.406]和标准差[0.229, 0.224, 0.225]进行归一化处理。本示例使用OpenCV的双线性图像缩放算法,这是一种特定的预处理选择,并不代表与所有训练框架中的缩放实现在像素级别上完全等效。

在解码输出结果时,需对类别逻辑值(logits)应用sigmoid函数,并在按置信度过滤之前,先选取排名前100的查询/类别对。在获取掩码时,需保留每个被选中的查询索引。该检查点使用的是存在间隙的COCO类别ID体系,因此其91个分数列无法直接使用YOLO连续的80类别列表进行标注。

对于掩码处理,需要先将浮点型逻辑值缩放至原始图像尺寸,再应用零阈值进行判断:逻辑值大于零对应sigmoid概率大于0.5。如果先对较小的掩码进行阈值处理再放大,会产生不同的边界效果。这一处理顺序遵循了RF-DETR 1.6.3版本的后处理实现方式。

以下完整脚本已包含在rfdetr_segment.py文件中。请切换回OpenCV推理环境并运行该脚本。

在Windows系统中,请将命令输入为单独一行。

C++版RF-DETR分割实现

使用相同的已导出分割模型和示例图像。

该版本构建了归一化的NCHW张量,获取dets(检测框)、labels(标签)和masks(掩码)输出,并确保每个被选中的查询与其对应的掩码保持配对关系。与Python版本相同,该版本会先缩放掩码逻辑值,再应用零阈值判断。默认置信度阈值为0.5。

所提供代码的实际输出结果:在0.5置信度阈值下检测出五个实例,彩色掩码准确贴合了图中可见的公交车和行人轮廓。由于两个模型使用了不同的输入尺寸和阈值设置,这两张图像仅用于展示检测与分割效果,并非对模型精度或速度的对照比较。

测试情况说明

C++17程序使用Apple Clang 17编译器,并基于官方源码发布版本构建的OpenCV 5.0.0进行编译测试。两个程序在同一示例图像上均输出了一辆公交车和四个行人的检测结果。与Python版本相比,YOLO26的边界框和置信度分数在数值精度范围内保持一致,而RF-DETR生成的全部五个掩码在该图像上均实现了像素级完全一致。下载包中包含C++构建过程及比对记录。

Python脚本在Apple M5 Pro设备上运行,使用了OpenCV 5.0.0的新版CPU引擎。测试还在全新环境中重新运行,该环境仅安装了opencv-python-headless==5.0.0.93和numpy==2.3.5作为应用程序依赖项,推理环境中未安装PyTorch、Ultralytics、RF-DETR和ONNX Runtime。

YOLO26的输出结果已针对同一预处理输入与源PyTorch模型进行了核对。RF-DETR的输出张量已与ONNX Runtime进行核对,其解码后的掩码也已针对相同张量与原始RF-DETR后处理结果进行了核对。下载包中包含验证记录和导出设置。这些检查证实了所提供示例能够在测试环境中正确执行并解码输出结果,但并非数据集层面的精度评估。较新的ENGINE_OPENCV API已通过源码核实验证;本文并未对当前开发分支构建版本进行执行测试方面的声明。

GPU推理与OpenCV 4迁移说明

本文所使用的OpenCV内置引擎运行于CPU,经核查的当前5.x版本头文件仍保留这一限制。仅在这些示例中设置DNN_TARGET_CUDA并不能将其转移至GPU运行。原始5.0.0版本中描述的传统引擎GPU路径,仅适用于仍提供该引擎及所需加速器后端的构建版本;当前5.x API已不再提供ENGINE_CLASSIC选项。建议核查您所部署的具体API和构建版本,而非假定原始发布版本的回退机制仍然适用。相关内容详见当前引擎API及5.0.0迁移指南。

OpenCV可选的ONNX Runtime集成是另一种部署途径,在适当配置的构建版本中可支持GPU执行提供程序。该集成必须被编译进OpenCV中;仅安装Python版onnxruntime软件包并不会为现有OpenCV wheel包添加该集成功能。OpenCV 5构建概览文档中介绍了相关的CMake配置选项。

在迁移过程中,还应重新审视旧的模型加载代码。OpenCV 5已移除Caffe和Darknet解析器,需将相关模型导出或转换为ONNX格式。ONNX文件仍需要兼容的运算符、受支持的张量形状,以及正确的预处理方式。建议记录检查点文件、导出设置、OpenCV构建版本以及已知的测试图像,以便在未来升级时可对照已验证可用的参考方案进行检查。已移除的格式详情记录在OpenCV 5模型加载实现文档中。

如果想立即尝试使用您自己的图像,请保持模型和预处理方式不变,仅替换图像路径即可。如果您切换到不同尺寸的模型或自定义检查点,则需要同步更新预期输入尺寸、输出形状和类别映射关系,这些细节与ONNX文件名一样,都是模型接口的重要组成部分。

作者:Satya Mallick

OpenCV.org首席执行官

Edge AI and Vision Alliance - Latest News