PaddleX 开放词汇目标检测模块实战指南:零样本文本提示驱动的检测推理

原创2026-10-09 23:49:411,422 阅读
文章标签:人工智能机器学习深度学习计算机视觉OCR多模态语音模型推理服务模型优化预训练微调

PaddleX 开放词汇目标检测模块实战指南:零样本文本提示驱动的检测推理

开放词汇目标检测(Open Vocabulary Detection,OVD)突破了传统检测器"只能识别预训练类别"的限制,允许用户通过一段自然语言文本定义任意类别,模型即可在图像中定位并识别这些"从未见过"的物体。本文以 PaddleX 的开放词汇目标检测模块为核心,完整讲解其支持模型、推理 API、阈值与 prompt 用法、结果处理以及底层预处理/后处理实现,并结合仓库源码给出可验证的配置与调用依据。读完本文,你将能够基于 GroundingDINO-T 与 YOLO-Worldv2-L 用几行代码完成零样本检测推理,并理解其文本-图像跨模态推理链路。

一、模块定位:开放词汇目标检测是什么

传统目标检测方法只能识别预定义类别集中的物体,模型一旦训练完成,类别集合便固定下来。开放词汇目标检测则允许模型识别未在训练中出现过的物体:通过结合自然语言处理技术,用文本描述来定义新类别,模型据此识别和定位图像中的新物体,从而使目标检测具备更强的灵活性与泛化能力。

在 PaddleX 中,该能力以独立的模型模块形式提供,位于 paddlex/inference/models/open_vocabulary_detection/ 目录,其推理入口由 OVDetRunnerPredictor 实现(predictor.py),与普通目标检测的关键差异在于:推理时必须额外传入 prompt 文本,预处理阶段会将图像与文本一起编码,后处理阶段再依据文本与检测框的匹配程度输出类别标签。模块同时以 Pipeline 形式集成,见 paddlex/inference/pipelines/open_vocabulary_detection/pipeline.py。

二、支持模型列表与性能基准

PaddleX 当前为开放词汇目标检测模块提供两款预训练模型,均支持推理集成。下表整理自官方教程,其中推理耗时仅包含模型推理耗时,不包含前后处理耗时:

模型 模型下载链接 mAP(0.5:0.95) mAP(0.5) GPU推理耗时(ms)[常规模式 / 高性能模式] 模型存储大小(MB) 介绍
GroundingDINO-T 推理模型 49.4 64.4 - / - 658.3 基于 O365、GoldG、Cap4M 三个数据集训练的开放词汇目标检测模型。文本编码器采用 Bert,视觉模型整体采用 DINO,额外设计了一些跨模态融合模块,在开放词汇目标检测领域取得了较好的效果
YOLO-Worldv2-L 推理模型 44.4 59.8 292.14 / 292.14 421.4 基于 O365、GoldG 两个数据集训练的开放词汇目标检测模型。文本编码器采用 CLIP,视觉模型整体采用 YOLOv8,额外设计了一些轻量化的跨模态融合模块,在精度和速度之间取得了较好的均衡

测试环境说明:

  • 性能测试环境
    • 测试数据集: 基于 O365、GoldG、Cap4M 三个数据集训练的开放词汇目标检测模型。
    • 硬件配置: GPU 为 NVIDIA Tesla T4;CPU 为 Intel Xeon Gold 6271C @ 2.60GHz。
    • 软件环境: Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6;paddlepaddle 3.0.0 / paddlex 3.0.3。
  • 推理模式说明
模式 GPU配置 CPU配置 加速技术组合
常规模式 FP32精度 / 无TRT加速 FP32精度 / 8线程 PaddleInference
高性能模式 选择先验精度类型和加速策略的最优组合 FP32精度 / 8线程 选择先验最优后端(Paddle/OpenVINO/TRT等)

两款模型的官方配置文件位于 paddlex/configs/modules/open_vocabulary_detection/:其中 GroundingDINO-T.yaml 与 YOLO-Worldv2-L.yaml 均声明 mode: predict,即本模块当前仅支持预测推理,不支持训练。

三、快速集成:几行代码完成零样本检测

在快速集成前,请先安装 PaddleX 的 wheel 包,详细请参考 PaddleX本地安装教程。

完成 whl 包安装后,几行代码即可完成开放词汇目标检测模块的推理,你可以任意切换该模块下的模型,也可以将模块的模型推理集成到自己的项目中。运行以下代码前,请先下载示例图片到本地:

from paddlex import create_model
model = create_model(model_name='GroundingDINO-T')
results = model.predict(input='open_vocabulary_detection.jpg', prompt = 'bus . walking man . rearview mirror .', batch_size=1)
for res in results:
    res.print()
    res.save_to_img(f"./output/")
    res.save_to_json(f"./output/res.json")

运行后,得到的结果为:

{'res': "{'input_path': 'open_vocabulary_detection.jpg', 'boxes': [{'coordinate': [112.10542297363281, 117.93667602539062, 514.35693359375, 382.10150146484375], 'label': 'bus', 'score': 0.9348853230476379}, {'coordinate': [264.1828918457031, 162.6674346923828, 286.8844909667969, 201.86187744140625], 'label': 'rearview mirror', 'score': 0.6022508144378662}, {'coordinate': [606.1133422851562, 254.4973907470703, 622.56982421875, 293.7867126464844], 'label': 'walking man', 'score': 0.4384709894657135}, {'coordinate': [591.8192138671875, 260.2451171875, 607.3953247070312, 294.2210388183594], 'label': 'man', 'score': 0.3573091924190521}]}"}

运行结果参数含义如下:

  • input_path:表示输入待预测图像的路径
  • boxes:每个预测出的 object 的信息
    • label:类别名称
    • score:预测得分
    • coordinate:预测框的坐标,格式为 [xmin, ymin, xmax, ymax]

从示例输出可以看到:即使 prompt 中只写了 bus、walking man、rearview mirror 三类,模型还能输出 man 这一未显式指定的相关类别,这正是"开放词汇"能力的直观体现。

四、create_model 实例化参数详解

create_model 用于实例化开放词汇目标检测模型(此处以 GroundingDINO-T 为例),具体说明如下:

参数 参数说明 参数类型 可选项 默认值
model_name 模型名称 str 无 无
model_dir 模型存储路径 str 无 无
device 模型推理设备 str 支持指定GPU具体卡号,如 gpu:0,其他硬件具体卡号,如 npu:0,CPU 如 cpu gpu:0
use_hpip 是否启用高性能推理插件 bool 无 False
hpi_config 高性能推理配置 dict | None 无 None
thresholds 模型使用的过滤阈值 dict/None 无 None

其中:

  • model_name 必须指定。指定 model_name 后,默认使用 PaddleX 内置的模型参数;在此基础上再指定 model_dir 时,则使用用户自定义的模型。
  • thresholds 为模型使用的过滤阈值,默认为 None,表示沿用上一层设置。参数设置的优先级从高到低为:predict 参数传入 > create_model 初始化传入 > yaml 配置文件设置。
    • GroundingDINO 系列模型在推理时需要设置两个阈值:box_threshold(默认 0.3)与 text_threshold(默认 0.25),参数传入形式为 {"box_threshold": 0.3, "text_threshold": 0.25}。这两个默认值与 GroundingDINO-T.yaml 及后处理器 GroundingDINOPostProcessor 的初始化参数(groundingdino_processors.py)保持一致。

五、predict() 方法与 prompt 提示词用法

调用开放词汇目标检测模型的 predict() 方法进行推理预测,其参数有 input、batch_size、thresholds 和 prompt,具体说明如下:

参数 参数说明 参数类型 可选项 默认值
input 待预测数据,支持多种输入类型 Python Var/str/list - Python变量,如 numpy.ndarray 表示的图像数据
- 文件路径,如图像文件的本地路径:/root/data/img.jpg
- URL链接,如图像文件的网络 URL:示例
- 本地目录,该目录下需包含待预测数据文件,如本地路径:/root/data/
- 列表,列表元素需为上述类型数据,如 [numpy.ndarray, numpy.ndarray]、["/root/data/img1.jpg", "/root/data/img2.jpg"]、["/root/data1", "/root/data2"]
无
batch_size 批大小 int 任意整数 1
thresholds 模型使用的过滤阈值 dict/None - None,表示沿用上一层设置,参数设置优先级从高到低为:predict 参数传入 > create_model 初始化传入 > yaml 配置文件设置
- dict,如 {"box_threshold": 0.3, "text_threshold": 0.25},表示推理时 box_threshold 设置为 0.3,text_threshold 设置为 0.25
None
prompt 模型预测使用的提示词 str 任意字符串 无

5.1 prompt 的写法差异:点号分隔 vs 逗号分隔

prompt 的书写格式与所选模型强相关,两种模型的文本解析逻辑在源码中有明确差异:

  • GroundingDINO 系列:prompt 使用点号分隔类别短语,并以点号结尾,如 'bus . walking man . rearview mirror .'。从源码看,文本处理器 GroundingDinoTextProcessor.pre_caption 会对输入文本做 strip(),并在末尾缺少 . 时自动补上(groundingdino_processors.py);随后 BERT Tokenizer 以 <a href="https://link.gitcode.com/i/eb008b27f063677e2259926ccfbd7b3b" target="_blank">CLS]、[SEP]、.、? 作为特殊 token 切分短语并构造文本自注意力掩码([groundingdino_processors.py)。
  • YOLO-World 系列:prompt 使用逗号分隔类别,如 'bus, car, rearview mirror'(见 YOLO-Worldv2-L.yaml)。源码中的 YOLOWorldProcessor.process_text 会对文本做 strip().lower(),再按逗号切分得到词列表,交由 CLIP Tokenizer 编码(yoloworld_processors.py)。

5.2 阈值生效机制

predict 传入的 thresholds 与初始化时传入的 thresholds 通过 OVDetRunnerPredictor._parse_current_thresholds 合并:它先扫描后处理函数签名中所有含 threshold 的参数名,再依次用初始化阈值、本次推理阈值覆盖,因此**predict 级别的阈值优先级最高**(predictor.py)。

六、预测结果的处理与导出

对预测结果进行处理时,每个样本的预测结果均为对应的 Result 对象(开放词汇检测复用目标检测的 DetResult,定义见 paddlex/inference/models/object_detection/result.py),支持打印、保存为图片、保存为 json 文件:

方法 方法说明 参数 参数类型 参数说明 默认值
print() 打印结果到终端 format_json bool 是否对输出内容使用 JSON 缩进格式化 True
indent int 指定缩进级别,以美化输出的 JSON 数据,使其更具可读性,仅当 format_json 为 True 时有效 4
ensure_ascii bool 控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时所有非 ASCII 字符将被转义;False 则保留原始字符,仅当 format_json 为 True 时有效 False
save_to_json() 将结果保存为 json 格式的文件 save_path str 保存的文件路径,当为目录时,保存文件命名与输入文件类型命名一致 无
indent int 指定缩进级别,以美化输出的 JSON 数据,使其更具可读性,仅当 format_json 为 True 时有效 4
ensure_ascii bool 控制是否将非 ASCII 字符转义为 Unicode。设置为 True 时所有非 ASCII 字符将被转义;False 则保留原始字符,仅当 format_json 为 True 时有效 False
save_to_img() 将结果保存为图像格式的文件 save_path str 保存的文件路径,当为目录时,保存文件命名与输入文件类型命名一致 无

此外,也支持通过属性获取带结果的可视化图像和预测结果:

属性 属性说明
json 获取预测的 json 格式的结果
img 获取格式为 dict 的可视化图像

七、源码级原理:图像-文本跨模态推理管线

从源码结构看,OVDetRunnerPredictor 的推理链路(predictor.py)为:ReadImage → 图像预处理算子 → 模型专属 Processor(拼接文本)→ runner 推理 → 后处理。核心差异体现在两个 Processor 上:

GroundingDINO 预处理(groundingdino_processors.py)

  • 文本侧:加载模型目录 tokenizer/ 下的 BERT Tokenizer,对 prompt 分词并构造 input_ids、attention_mask、position_ids、text_self_attention_masks 等文本输入,最大词数 text_max_words 默认为 256;
  • 图像侧:保持宽高比缩放到 (800, 1333) 目标尺寸(短边 800、长边上限 1333),使用 ImageNet 统计的均值方差 [0.485, 0.456, 0.406] / [0.229, 0.224, 0.225] 归一化,并以 nested_tensor 形式处理 batch 内不同尺寸图像的 padding。

YOLO-World 预处理(yoloworld_processors.py)

  • 文本侧:加载 CLIP Tokenizer,prompt 按逗号切词;
  • 图像侧:通过 LetterResize 将图像统一缩放至 (640, 640)(同时记录 scale_factor 与 pad_param,用于后处理还原坐标),图像像素除以 255 后按均值 [0.0, 0.0, 0.0]、方差 [1.0, 1.0, 1.0] 归一化。

后处理差异

  • GroundingDINO 的后处理 GroundingDINOPostProcessor 对每个检测框先按 box_threshold 过滤低置信度框,再通过 text_threshold 判断该框命中了 prompt 中的哪些词,从而解码出类别标签(groundingdino_processors.py);
  • YOLO-World 的后处理 YOLOWorldPostProcessor 则按单一 threshold(默认 0.05)过滤,根据网络输出的类别索引映射回 prompt 词列表,并将坐标裁剪回原图尺寸(yoloworld_processors.py)。

八、Pipeline 方式与服务化部署

除了直接使用模型,PaddleX 还将开放词汇目标检测封装为 Pipeline。Pipeline 配置见 paddlex/configs/pipelines/open_vocabulary_detection.yaml,其中 SubModules.OpenVocabularyDetection 默认选用 GroundingDINO-T,batch_size 为 1,默认阈值 box_threshold: 0.3、text_threshold: 0.25。对应的 Pipeline 实现类 OpenVocabularyDetectionPipeline(pipeline.py)在其 predict() 中要求同时传入 input 与 prompt,并将阈值解析后透传给底层模型。

若需以 HTTP 服务方式对外提供能力,PaddleX 的 serving 层已注册了名为 /open-vocabulary-detection 的推理端点(serving/schemas/open_vocabulary_detection.py),请求体包含 image、prompt、thresholds 与 visualize 字段,响应中返回 detectedObjects(含边界框 bbox、类别 categoryName、置信度 score)以及可选的可视化图像 image。

九、二次开发现状

需要明确的是:当前模块暂时不支持微调训练,仅支持推理集成。关于该模块的微调训练,PaddleX 计划在未来版本中支持。因此当前适合的使用方式为:直接使用内置的 GroundingDINO-T / YOLO-Worldv2-L 预训练权重,通过 prompt 文本在推理阶段自由定义检测类别,并将其集成到自身业务系统中。

关于更多 PaddleX 单模型推理的 API 使用方法,可以参考 PaddleX单模型Python脚本使用说明。

登录后查看全文
PaddleX