Transformers documentation

DETR

Transformers

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

该模型于 2020-05-26 在 HF papers 上发布，并于 2021-06-09 贡献至 Hugging Face Transformers。

DETR

DETR 由一个卷积骨干网络和一个编码器-解码器 Transformer 组成，可以端到端地训练用于目标检测。它极大地简化了 Faster-R-CNN 和 Mask-R-CNN 等模型的许多复杂性，这些模型使用了区域提议、非极大值抑制流程和锚框生成等技术。此外，DETR 还可以通过在解码器输出之上简单地添加一个掩码头，自然地扩展到执行全景分割任务。

您可以在 AI at Meta 组织下找到所有原始的 DETR 检查点。

该模型由 nielsr 贡献。

点击右侧边栏中的 DETR 模型，以查看将 DETR 应用于不同目标检测和分割任务的更多示例。

在 from_pretrained() 中设置 use_kernels=True，即可用 Hub 上的优化内核替换受支持的层。有关详细信息，请参阅加载内核。

下面的示例演示了如何使用 Pipeline 或 AutoModel 类执行目标检测。

Pipeline

AutoModel

How DETR works

以下是 DetrForObjectDetection 工作原理的简要说明：

First, an image is sent through a pre-trained convolutional backbone (in the paper, the authors use ResNet-50/ResNet-101). Let’s assume we also add a batch dimension. This means that the input to the backbone is a tensor of shape (batch_size, 3, height, width), assuming the image has 3 color channels (RGB). The CNN backbone outputs a new lower-resolution feature map, typically of shape (batch_size, 2048, height/32, width/32). This is then projected to match the hidden dimension of the Transformer of DETR, which is 256 by default, using a nn.Conv2D layer. So now, we have a tensor of shape (batch_size, 256, height/32, width/32). Next, the feature map is flattened and transposed to obtain a tensor of shape (batch_size, seq_len, d_model) = (batch_size, width/32*height/32, 256). So a difference with NLP models is that the sequence length is actually longer than usual, but with a smaller d_model (which in NLP is typically 768 or higher).

接下来，该输入被送入编码器，输出形状相同的 encoder_hidden_states（可以将其视为图像特征）。然后，所谓的 object queries 被送入解码器。这是一个形状为 (batch_size, num_queries, d_model) 的张量，其中 num_queries 通常设置为 100，并初始化为零。这些输入嵌入是作者所称的 object queries 的学习型位置编码，与编码器类似，它们会被加到每个注意力层的输入中。每个 object query 都会寻找图像中的特定对象。解码器通过多个自注意力层和编码器-解码器注意力层更新这些嵌入，以输出形状相同的 decoder_hidden_states：(batch_size, num_queries, d_model)。接下来，在其上方添加两个用于目标检测的头部：一个线性层，用于将每个 object query 分类为某个对象或“无对象”；以及一个 MLP，用于预测每个 query 的边界框。

模型使用二部图匹配损失进行训练：具体来说，我们将 N = 100 个对象查询中每一个的预测类别和边界框与真实标注进行比较，并将标注填充至相同的长度 N（因此，如果一张图像仅包含 4 个对象，则其余 96 个标注的类别为“无对象”，边界框为“无边界框”）。使用匈牙利匹配算法来寻找 N 个查询与 N 个标注之间的最优一对一映射。随后，使用标准的交叉熵损失（针对类别）以及 L1 损失和广义 IoU 损失的线性组合（针对边界框）来优化模型参数。

DETR 可以自然地扩展以执行全景分割（它将语义分割和实例分割统一起来）。DetrForSegmentation 在 DetrForObjectDetection 之上添加了一个分割掩码头。该掩码头可以联合训练，也可以通过两步流程进行训练：首先训练一个 DetrForObjectDetection 模型，以检测围绕“事物”（实例）和“物质”（如树木、道路、天空等背景事物）的边界框，然后冻结所有权重，仅训练掩码头 25 个 epoch。实验表明，这两种方法的结果相似。请注意，预测边界框是训练所必需的，因为匈牙利匹配是基于边界框之间的距离计算的。

备注

DETR 使用所谓的对象查询来检测图像中的对象。查询的数量决定了单张图像中可检测到的最大对象数，默认设置为 100（参见DetrConfig中的参数num_queries）。请注意，保留一定的余量是有益的（在 COCO 数据集中，作者使用了 100 个查询，而 COCO 图像中对象的最大数量约为 70）。
DETR 的解码器并行更新查询嵌入。这与 GPT-2 等语言模型不同，后者使用的是自回归解码而非并行解码。因此，这里不使用因果注意力掩码。
DETR 在每个自注意力和交叉注意力层中，在将隐藏状态投影为查询和键之前，会为其添加位置嵌入。对于图像的位置嵌入，可以选择固定的正弦位置嵌入或可学习的绝对位置嵌入。默认情况下，DetrConfig 的参数 position_embedding_type 被设置为 "sine"。
在训练过程中，DETR 的作者发现使用解码器中的辅助损失很有帮助，尤其是帮助模型输出每类对象的正确数量。如果将 DetrConfig 的参数 auxiliary_loss 设置为 True，则会在每个解码器层之后添加预测前馈神经网络和匈牙利损失（这些 FFN 共享参数）。
如果要在跨多个节点的分布式环境中训练模型，则应更新 modeling_detr.py 中 DetrLoss 类的 num_boxes 变量。在多节点上训练时，该值应设置为所有节点上目标框数量的平均值，具体可参见原始实现中的此处。
DetrForObjectDetection 和 DetrForSegmentation 可以使用 timm library 中可用的任意卷积骨干网络进行初始化。例如，要使用 MobileNet 骨干网络进行初始化，只需将 DetrConfig 的 backbone 属性设置为 "tf_mobilenetv3_small_075"，然后使用该配置初始化模型即可。
DETR 会对输入图像进行缩放，使得最短边至少达到一定像素数，而最长边不超过 1333 像素。在训练阶段，使用尺度增强（scale augmentation），将最短边随机设置为至少 480 像素且至多 800 像素。在推理阶段，最短边被设置为 800 像素。可以使用 DetrImageProcessor 为模型准备图像（以及可选的 COCO 格式标注）。由于这种缩放操作，同一批次中的图像可能具有不同的尺寸。DETR 通过将图像填充（padding）至批次中的最大尺寸，并创建一个像素掩码（pixel mask）来指示哪些像素是真实像素、哪些是填充像素，从而解决了这一问题。或者，也可以自定义 collate_fn 来对图像进行批处理，使用 ~transformers.DetrImageProcessor.pad_and_create_pixel_mask。
图像的大小将决定所使用的内存量，进而决定 batch_size。建议每个 GPU 使用 2 的批大小。更多信息请参见此 GitHub 讨论。

还有另外三种实例化 DETR 模型的方法（取决于你的偏好）：

选项 1：使用预训练权重实例化整个 DETR 模型

from transformers import DetrForObjectDetection


model = DetrForObjectDetection.from_pretrained("facebook/detr-resnet-50", device_map="auto")

选项 2：使用随机初始化的权重实例化 Transformer 部分的 DETR，但使用预训练权重初始化 backbone

from transformers import DetrConfig, DetrForObjectDetection


config = DetrConfig()
model = DetrForObjectDetection(config)

选项 3：使用随机初始化的权重实例化 DETR 的骨干网络 + Transformer

config = DetrConfig()
model = DetrForObjectDetection(config)

作为总结，请参考下表：

任务	目标检测	实例分割	全景分割
描述	预测图像中物体周围的边界框和类别标签	预测图像中物体（即实例）周围的掩码	预测图像中两个物体（即实例）以及“stuff”（即背景物体，如树木和道路）周围的掩码
模型	DetrForObjectDetection	DetrForSegmentation	DetrForSegmentation
示例数据集	COCO 检测	COCO 检测，COCO 全景	COCO 全景
提供给 DetrImageProcessor 的标注格式	{‘image_id’: `int`, ‘annotations’: `list[Dict]`}，其中每个 Dict 均为一个 COCO 对象标注	{‘image_id’: `int`, ‘annotations’: `list[Dict]`}（COCO 检测情况）或 {‘file_name’: `str`, ‘image_id’: `int`, ‘segments_info’: `list[Dict]`}（COCO 全景分割情况）	{‘file_name’: `str`, ‘image_id’: `int`, ‘segments_info’: `list[Dict]`} 以及 masks_path（包含掩码 PNG 文件的目录路径）
后处理（即将模型输出转换为 Pascal VOC 格式）	`~transformers.DetrImageProcessor.post_process`	`~transformers.DetrImageProcessor.post_process_segmentation`	`~transformers.DetrImageProcessor.post_process_segmentation`, `~transformers.DetrImageProcessor.post_process_panoptic`
评估器	使用 `iou_types="bbox"` 的 `CocoEvaluator`	`CocoEvaluator` 搭配 `iou_types="bbox"` 或 `"segm"`	`CocoEvaluator` 搭配 `iou_types="bbox"` 或 `"segm"`，`PanopticEvaluator`

简而言之，数据应准备为 COCO 检测或 COCO 全景分割格式，然后使用 DetrImageProcessor 生成 pixel_values、pixel_mask 以及可选的 labels，随后即可用于训练（或微调）模型。
进行评估时，应首先使用 DetrImageProcessor 的其中一种后处理方法将模型的输出进行转换。这些结果可以传入 CocoEvaluator 或 PanopticEvaluator，从而计算平均精度均值（mAP）和全景质量（PQ）等指标。后两者在原始仓库中实现。有关评估的更多信息，请参阅示例笔记本。

资源

请参阅这些 notebooks，其中包含在自定义数据集上微调 DetrForObjectDetection 和 DetrForSegmentation 的示例。

Transformers

DETR

备注

资源

DetrConfig

class transformers.DetrConfig

DetrImageProcessor

class transformers.DetrImageProcessor

预处理

post_process_object_detection

post_process_semantic_segmentation

post_process_instance_segmentation

post_process_panoptic_segmentation

DetrImageProcessorPil

class transformers.DetrImageProcessorPil

预处理

post_process_object_detection

post_process_semantic_segmentation

post_process_instance_segmentation

post_process_panoptic_segmentation

DETR 特定输出

class transformers.models.detr.modeling_detr.DetrModelOutput

class transformers.models.detr.modeling_detr.DetrObjectDetectionOutput

class transformers.models.detr.modeling_detr.DetrSegmentationOutput

DetrModel

类 transformers.DetrModel

forward

DetrForObjectDetection

class transformers.DetrForObjectDetection

forward

DetrForSegmentation

class transformers.DetrForSegmentation

forward