Transformers 中的 OWL-ViT 开放词汇目标检测：原理、源码解析与零样本/单样本实战

Transformers 中的 OWL-ViT 开放词汇目标检测原理、源码解析与零样本/单样本实战【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersOWL-ViTVision Transformer for Open-World Localization是 Transformers 中实现的开集开放词汇目标检测模型它不再受固定类别标签集的约束而是能够接收任意一段文字描述如 a photo of a cat作为查询在图像中定位并框出与文本语义匹配的目标同时支持用一张示例图去找相似物体的单样本image-guided检测。本文以 docs/source/en/model_doc/owlvit.md 为主线结合本仓库的模型源码、配置与处理类实现系统讲解 OWL-ViT 的架构原理、OwlViTProcessor的预处理/后处理流程、三大实战用法零样本文本条件检测、单样本图像条件检测、pipeline 快捷调用并给出所有关键类与方法在仓库中的对应位置供读者按需查阅和直接复现。OWL-ViT 是什么从固定类别到开放词汇的目标检测传统目标检测模型如 Faster R-CNN、DETR的分类头只包含训练时见过的一组固定类别遇到长尾类别或新类别时无法泛化。OWL-ViT 由 Matthias Minderer 等人在论文Simple Open-Vocabulary Object Detection with Vision Transformers中提出2022-05-12 发表于 HF Papers2022-07-22 由 adirik 贡献到 Transformers目标是解决开放词汇目标检测问题用任意自然语言查询目标物体。论文摘要的核心观点是将简单的架构 大规模预训练从图像分类迁移到目标检测。具体配方为三阶段对比式图文预训练contrastive image-text pre-training——在大量 (image, text) 对上训练图文对齐模型检测微调——以最小的结构改动将图文模型迁移为检测模型进行端到端检测微调end-to-end detection fine-tuning两种推理范式——零样本文本条件检测zero-shot text-conditioned与单样本图像条件检测one-shot image-conditioned。论文同时指出图像级预训练规模与模型尺寸的扩大能带来下游检测任务的一致提升。架构与工作原理从源码看 OWL-ViT 如何做检测以 CLIP 为多模态骨干OWL-ViT 以 CLIP 作为多模态骨干视觉侧类 ViT 的 Transformer从图像中提取视觉特征文本侧因果语言模型风格的 Transformer从文本查询中提取文本特征。在 configuration_owlvit.py 中可以看到三个配置类它们分别描述文本编码器、视觉编码器与完整模型。完整模型OwlViTConfig第 101 行起通过sub_configs组合文本与视觉子配置同时定义了projection_dim 512与logit_scale_init_value 2.6592两个跨模态参数。从图像级对比学习到逐 token 检测改造的关键把 CLIP 用于检测核心改动发生在 modeling_owlvit.py普通 CLIP 会在视觉 Transformer 末端做 token pooling把整张图压成一个向量用于图文匹配OWL-ViT去掉最终的 token pooling 层改为给每一个 Transformer 输出 token对应图像 patch挂上轻量的分类头与框回归头普通分类器通常使用固定权重的分类层fixed classification layer weightsOWL-ViT 的开放词汇分类通过把分类层权重替换为类别名称文本经文本模型得到的 embedding来实现因此理论上任意文本短语都可作为检测类别。完整模型OwlViTModelmodeling_owlvit.py内部组合了OwlViTTextTransformer、OwlViTVisionTransformer、无偏置的visual_projection/text_projection把各自 hidden size 投影到projection_dim以及可学习的logit_scale参数。它的forwardmodeling_owlvit.py遵循标准的 CLIP 式对比学习流程编码文本与图像 → L2 归一化 → 余弦相似度乘logit_scale.exp()得到logits_per_image/logits_per_text当return_lossTrue时还会调用image_text_contrastive_loss计算对称对比损失。这一部分是 OWL-ViT 训练时 CLIP 阶段的主体对应论文中作者先从头训练 CLIP再端到端微调的描述。分类头与框预测头如何从 patch token 得到框 类别检测能力由OwlViTForObjectDetectionmodeling_owlvit.py实现它把一个OwlViTModel与两个轻量检测头组合在一起OwlViTBoxPredictionHeadmodeling_owlvit.py一个Linear → GELU → Linear → GELU → Linear(4)的 MLP对每个 patch token 输出 4 个值(cx, cy, w, h)相对图像归一化到 [0,1]。OwlViTClassPredictionHeadmodeling_owlvit.py先把图像 patch 特征线性投影到文本维度再与文本 query embedding 做点积torch.einsum(...pd,...qd-...pq)得到类别 logits此外通过logit_shift与logit_scale两个线性层给 logits 施加可学习的平移与缩放elu 1以改善零样本 logits 的校准。前向路径中的两个关键细节值得留意图像表示成 patch 网格在image_text_embeddermodeling_owlvit.py中视觉模型输出的 token 序列被拆成class token patch tokenOWL-ViT 将 class token 广播并逐元素乘到所有 patch token上再经 LayerNorm 后 reshape 为(batch, num_patches_height, num_patches_width, hidden)的特征图——即OwlViTObjectDetectionOutput.image_embeds。这种class 语义注入每个 patch的操作是 OWL-ViT 区别于普通 ViT 的重要设计。框中心带网格偏置box biascompute_box_biasmodeling_owlvit.py根据每个 patch 在特征网格上的归一化坐标生成中心偏置并把框尺寸偏置到 patch 尺寸附近。这样box_predictor输出的初始框已经落在各自 patch 附近再经 sigmoid 得到最终归一化框显著降低了回归难度。一个前向过程发生了什么零样本推理调用OwlViTForObjectDetection(**inputs)时modeling_owlvit.py依次发生image_text_embedder同时编码图像与全部文本 query得到query_embeds与 patch 特征图把(batch * max_queries, hidden)的文本 embedding reshape 回(batch, max_queries, hidden)依据每个 query 的首个 token 是否为 0 构造query_maskinput_ids[..., 0] 0——这是处理器内部用空串把每条样本的 query 数量补齐到 batch 最大值后模型据此屏蔽 padding 文本的手段class_predictor逐 patch 计算每个文本 query 的类别 logitsbox_predictor输出逐 patch 的归一化框。最终返回OwlViTObjectDetectionOutput其核心字段包括logits(batch, num_patches, num_queries)分类 logitspred_boxes(batch, num_patches, 4)格式为(center_x, center_y, width, height)且归一化到 [0,1]text_embeds、image_embeds、class_embeds等中间表征。该输出类的完整字段说明见 modeling_owlvit.py。需要强调pred_boxes是归一化的中心点坐标格式后处理时必须交给处理器的post_process_*方法换算回原图尺寸的(xmin, ymin, xmax, ymax)格式。单样本图像引导检测image_guided_detectionOWL-ViT 还支持用示例图代替文字作为查询即 one-shot image-conditioned detection。OwlViTForObjectDetection.image_guided_detectionmodeling_owlvit.py的实现思路是分别对目标图与 query 图提取特征图image_embedder在embed_image_querymodeling_owlvit.py中对 query 图上每个 patch 预测框并计算其与整图框[0,0,1,1]的 IoU选取与最佳 IoU 差距在 80% 以内的 patch用与全局平均 embedding 余弦相似度最小的那个 patch 的 class embedding 作为该 query 图的视觉查询特征用该视觉 query embedding 走与零样本相同的class_predictorbox_predictor在目标图中找出所有相似的物体。由于整个过程不依赖文本query 图可以是从任意目标图里裁剪出的一小块区域这与文字查询互为补充也正因如此代码中OwlViTImagesKwargs.query_images的注释明确写着query images override any text prompts。输出类型为OwlViTImageGuidedObjectDetectionOutput见 modeling_owlvit.py。模型配置与可用检查点三个配置类都支持直接实例化后构建随机模型也可以随 checkpoint 一起从 Hub 加载示例中模型基类 docstring 锚定google/owlvit-base-patch16风格配置。核心默认值如下OwlViTTextConfigconfiguration_owlvit.py参数默认值说明vocab_size49408词表大小CLIP BPEhidden_size512隐藏维度intermediate_size2048FFN 中间维度num_hidden_layers12层数num_attention_heads8注意力头数max_position_embeddings16文本最大长度CLIP 风格短语编码hidden_actquick_gelu激活函数layer_norm_eps1e-5LayerNorm epsilonpad/bos/eos_token_id0 / 49406 / 49407特殊 tokenOwlViTVisionConfigconfiguration_owlvit.py参数默认值说明hidden_size768隐藏维度intermediate_size3072FFN 中间维度num_hidden_layers12层数num_attention_heads12注意力头数image_size768训练用输入分辨率正方形patch_size32patch 尺寸num_channels3输入通道hidden_actquick_gelu激活函数OwlViTConfigconfiguration_owlvit.py聚合两个子配置并额外定义projection_dim 512、logit_scale_init_value 2.6592__post_init__中若text_config/vision_config传了 dict 会自动转成对应的PreTrainedConfig。文末 API 一览中OwlViTModel的get_text_features/get_image_features也直接构建在这些配置之上。官方文档与源码示例中反复出现的可直接加载检查点为google/owlvit-base-patch32与google/owlvit-base-patch16patch32 的视觉分支将 768×768 输入切成 32×32 的 patchpatch16 版本 patch 更细、特征图更密。数据预处理OwlViTImageProcessor、OwlViTImageProcessorPil与OwlViTProcessorOWL-ViT 的输入侧同时涉及图像与文本官方推荐使用OwlViTProcessor一站式完成两者。它内部组合了图像处理器resize/rescale/normalize 图像文档中对应OwlViTImageProcessor与OwlViTImageProcessorPil两个类CLIPTokenizer用于把文本 query 编码成 token。图像处理器OwlViTImageProcessorimage_processing_owlvit.py在类属性上直接声明了默认预处理参数resample BICUBIC、do_resize Truesize {height: 768, width: 768}、crop_size同为 768default_to_square True图像会被统一到 768×768 的正方形输入均值/方差沿用 CLIP 的OPENAI_CLIP_MEAN/OPENAI_CLIP_STD并默认do_rescale True、do_normalize True、do_convert_rgb True。它基于仓库的 Torchvision 后端TorchvisionBackend实现另一个等价类OwlViTImageProcessorPilimage_processing_pil_owlvit.py基于PilBackend实现并承载了文档中列出的两个后处理方法post_process_object_detection与post_process_image_guided_detection即把模型输出的归一化(cx, cy, w, h)框换算到target_sizes指定尺寸下的(xmin, ymin, xmax, ymax)角点格式。OwlViTProcessor.__call__的输入编排OwlViTProcessor的__call__processing_owlvit.py支持同时传入images、text可叠加嵌套列表与可选的query_images并自动完成三项编排文本text必须是字符串 / 字符串列表 / 嵌套字符串列表。嵌套列表的语义是[batch 内的每张图, 该图的多条 query]多条 query 时处理器会先统计 batch 内最大 query 数用空字符串 把每条样本补齐到一致长度再统一 tokenize默认paddingmax_length输出input_ids与attention_mask。查询图传了query_images时输出query_pixel_values并优先于文本代码中会以 query 图像结果直接覆盖数据。图像图像经处理器得到pixel_values。OwlViTProcessorKwargs的默认行为是文本paddingmax_length、return_tensorspt见 processing_owlvit.py因此不传return_tensors时默认返回 PyTorch 张量。实战一零样本文本条件目标检测官方文档owlvit.md给出的标准用法如下——加载处理器与检测模型给出一张 COCO 图与多条文本查询让模型找出图中的猫和狗import requests from PIL import Image import torch from transformers import OwlViTProcessor, OwlViTForObjectDetection processor OwlViTProcessor.from_pretrained(google/owlvit-base-patch32) model OwlViTForObjectDetection.from_pretrained(google/owlvit-base-patch32, device_mapauto) url http://images.cocodataset.org/val2017/000000039769.jpg image Image.open(requests.get(url, streamTrue).raw) text_labels [[a photo of a cat, a photo of a dog]] inputs processor(texttext_labels, imagesimage, return_tensorspt).to(model.device) outputs model(**inputs) # Target image sizes (height, width) to rescale box predictions [batch_size, 2] target_sizes torch.tensor([(image.height, image.width)]) # Convert outputs (bounding boxes and class logits) to Pascal VOC format (xmin, ymin, xmax, ymax) results processor.post_process_grounded_object_detection( outputsoutputs, target_sizestarget_sizes, threshold0.1, text_labelstext_labels ) # Retrieve predictions for the first image for the corresponding text queries result results[0] boxes, scores, text_labels result[boxes], result[scores], result[text_labels] for box, score, text_label in zip(boxes, scores, text_labels): box [round(i, 2) for i in box.tolist()] print(fDetected {text_label} with confidence {round(score.item(), 3)} at location {box}) Detected a photo of a cat with confidence 0.707 at location [324.97, 20.44, 640.58, 373.29] Detected a photo of a cat with confidence 0.717 at location [1.46, 55.26, 315.55, 472.17]对这段流程做几点拆解post_process_grounded_object_detectionprocessing_owlvit.py内部先调用图像处理器的post_process_object_detection完成按threshold默认 0.1过滤低置信度预测、把模型输出的 logits 转成每个 patch 的分数并做必要的 NMS 处理、用target_sizes把归一化框缩放到原始图像尺寸随后它把labels预测命中的 query 下标映射回你传入的text_labels从而在返回结果中直接给出命中的文本短语。返回字典含scores、labels、boxes(xmin, ymin, xmax, ymax)格式与text_labels四类键。query 语义这里文本写的是 a photo of a cat 这样的完整短语而不是裸类别名这是 CLIP 系文本编码的常见范式——OWL-ViT 的类别 logits 本质是图像 patch 与 query 短语 embedding 的余弦相似度查询短语措辞会直接影响结果。target_sizes必须给出因为模型输出是相对 768×768 输入的归一化框只有配合(height, width)才能得到原图坐标系下的真实框坐标。阈值经验开放词汇场景下 logits 在不同措辞间天然缺乏可比性官方默认threshold0.1实践中常需按场景调低/调高。实战二单样本图像条件检测把 query 从文字换成示例图需要用到image_guided_detection与post_process_image_guided_detection。下面这个完整示例改编自 modeling_owlvit.py 中image_guided_detection的 docstring也是文档所述单样本能力最直接的验证import httpx from io import BytesIO from PIL import Image import torch from transformers import AutoProcessor, OwlViTForObjectDetection processor AutoProcessor.from_pretrained(google/owlvit-base-patch16) model OwlViTForObjectDetection.from_pretrained(google/owlvit-base-patch16) url http://images.cocodataset.org/val2017/000000039769.jpg with httpx.stream(GET, url) as response: image Image.open(BytesIO(response.read())) query_url http://images.cocodataset.org/val2017/000000001675.jpg with httpx.stream(GET, query_url) as response: query_image Image.open(BytesIO(response.read())) inputs processor(imagesimage, query_imagesquery_image, return_tensorspt) with torch.no_grad(): outputs model.image_guided_detection(**inputs) # Target image sizes (height, width) to rescale box predictions [batch_size, 2] target_sizes torch.Tensor([image.size[::-1]]) # Convert outputs (bounding boxes and class logits) to Pascal VOC format (xmin, ymin, xmax, ymax) results processor.post_process_image_guided_detection( outputsoutputs, threshold0.6, nms_threshold0.3, target_sizestarget_sizes ) i 0 # Retrieve predictions for the first image boxes, scores results[i][boxes], results[i][scores] for box, score in zip(boxes, scores): box [round(i, 2) for i in box.tolist()] print(fDetected similar object with confidence {round(score.item(), 3)} at location {box}) Detected similar object with confidence 0.856 at location [10.94, 50.4, 315.8, 471.39] Detected similar object with confidence 1.0 at location [334.84, 25.33, 636.16, 374.71]与文本条件版本相比这里有两处显著差异模型侧调用model.image_guided_detection(**inputs)而非直接model(**inputs)因为单样本模式必须让 query 图先经过embed_image_query提取视觉查询特征后处理换用post_process_image_guided_detectionprocessing_owlvit.py其签名额外提供threshold默认 0.0与nms_threshold默认 0.3视觉相似度模式下冗余框更多需要靠 NMS 阈值压制互相重叠的重复检测此输出中labels字段恒为None因为没有类别语义。实战三pipeline 一键零样本检测如果不关心底层 API仓库为 OWL-ViT 提供了开箱即用的zero-shot-object-detectionpipelinezero_shot_object_detection.py把图像加载 → 预处理 → 推理 → 画框结果整理全部封装好from transformers import pipeline detector pipeline(modelgoogle/owlvit-base-patch32, taskzero-shot-object-detection) detector( http://images.cocodataset.org/val2017/000000039769.jpg, candidate_labels[cat, couch], ) [{score: 0.287, label: cat, box: {xmin: 324, ymin: 20, xmax: 640, ymax: 373}}, {score: 0.254, label: cat, box: {xmin: 1, ymin: 55, xmax: 315, ymax: 472}}, {score: 0.121, label: couch, box: {xmin: 4, ymin: 0, xmax: 642, ymax: 476}}]ZeroShotObjectDetectionPipeline由OwlViTForObjectDetection驱动接受的关键参数candidate_labels字符串或字符串列表对应文本 query、threshold默认 0.1、top_k默认返回全部、timeout抓取网络图片的超时秒数。输出是每张图一个字典列表每个字典含label、score、boxxmin/xmax/ymin/ymax。它也支持一次传入多个 dict各自带image与candidate_labels批量处理。注意候选类别最好也采用与图文预训练一致的自然语言措辞以便得到合理分数。仓库中的实现文件与测试若需深入源码或在源码上做二次开发OWL-ViT 的实现集中在以下文件关注点仓库路径完整 PyTorch 模型Text/Vision/联合/检测头/单样本检测src/transformers/models/owlvit/modeling_owlvit.py三个配置类及全部默认超参src/transformers/models/owlvit/configuration_owlvit.pyProcessor文本图像编排、后处理转发src/transformers/models/owlvit/processing_owlvit.py图像预处理与后处理src/transformers/models/owlvit/image_processing_owlvit.py 与 src/transformers/models/owlvit/image_processing_pil_owlvit.py原版Google Scenic/Flax权重转 HF 脚本src/transformers/models/owlvit/convert_owlvit_original_flax_to_hf.py零样本检测 pipelinesrc/transformers/pipelines/zero_shot_object_detection.py模型/处理器/图像处理测试tests/models/owlvit/test_modeling_owlvit.py、tests/models/owlvit/test_processing_owlvit.py、tests/models/owlvit/test_image_processing_owlvit.py这些测试是对本文所述用法最直接的机器验证例如test_modeling_owlvit.py中既覆盖了文本条件检测的前向/后处理也覆盖了image_guided_detection的单样本路径与输出结构一致性test_processing_owlvit.py则覆盖了文本列表 padding、query_images覆盖文本等边界行为。API 速查下表汇总了模型文档owlvit.md中列出并通过 autodoc 生成的全部公开类及其核心方法方便按需查阅类核心方法职责OwlViTConfig—顶层配置聚合 text/vision 子配置OwlViTTextConfig—文本编码器配置OwlViTVisionConfig—视觉编码器配置OwlViTImageProcessorpreprocess图像 resize/rescale/normalizeOwlViTImageProcessorPilpreprocess、post_process_object_detection、post_process_image_guided_detectionPIL 后端的预处理与检测结果后处理OwlViTProcessor__call__、post_process_grounded_object_detection、post_process_image_guided_detection一站式图文预处理与后处理OwlViTModelforward、get_text_features、get_image_featuresCLIP 式图文联合模型用于对比特征/作为检测骨干OwlViTTextModelforward文本编码OwlViTVisionModelforward视觉编码逐 patch 特征保留位置信息OwlViTForObjectDetectionforward、image_guided_detection开放词汇检测模型文本条件 单样本图像条件常见疑问与注意事项为什么文本查询要用嵌套列表OWL-ViT 支持一张图多条 query因此text用[image1 的 queries, image2 的 queries, ...]表达每条样本的 query 数量可以不同处理器会自动用空串补到 batch 内最大长度模型侧再通过首 token 是否为 0 的query_mask屏蔽填充项modeling_owlvit.py。pred_boxes是哪种格式模型的原始输出是归一化的(center_x, center_y, width, height)cxcywh相对 768×768 的输入分辨率必须经post_process_grounded_object_detection传target_sizes才会换算成原图像素坐标的 Pascal VOC 角点格式(xmin, ymin, xmax, ymax)。文本条件与图像条件检测的输出差异文本条件结果含labels与text_labels图像条件结果image_guided_detection不含类别语义labels为None且默认threshold0.0、nms_threshold0.3需要靠 NMS 清理相似物体带来的重复框。分辨率与位置编码插值视觉分支的image_size默认 768。若输入不同分辨率interpolate_pos_encodingTrue会对预训练位置编码插值同时box_predictor/image_embedder会按实际 patch 数量动态重算网格偏置modeling_owlvit.py因此 OWL-ViT 对输入尺寸并不严格限定。模型是否可做特征提取可以。OwlViTModel的get_text_features/get_image_featuresmodeling_owlvit.py直接返回投影后的文本/图像特征可用于图文检索或作为下游任务的 embedding 来源。后续模型若需要更强或分辨率更高的开放词汇检测能力可在仓库中继续查看同思路演进的 docs/source/en/model_doc/owlv2.md 与src/transformers/models/owlv2/目录与 OWL-ViT 同源但架构与训练细节不同不过本文所有 API 均以 OWL-ViTowlvit为准。综上OWL-ViT 的价值在于把图像级图文对齐的能力低成本地迁移到逐区域开放词汇定位上。从OwlViTProcessor的图文编排到OwlViTForObjectDetection的逐 patch 分类/回归头再到image_guided_detection的单样本视觉查询你可以用不到 20 行代码完成对任意自然语言短语的图像目标搜索——这正是开放世界目标检测从论文走向工程实用的最小闭环。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考