该模型于 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