Transformers documentation

DETR

Transformers

Comece agora

Transformers Instalação Início rápido

Classes base

Modelos

Pré-processadores

Inferência

Pipeline API

API de geração

Otimização

Conversar com modelos

Serving

Treinamento

Comece agora

Personalização

Ajuste fino de parâmetros eficientes

Desempenho

Treinamento distribuído

Hardware

Quantização

Integrações com o ecossistema

Recursos

API

Principais classes

Modelos

Modelos de texto

Modelos de visão

Modelos de áudio

Modelos de vídeo

Modelos multimodais

Modelos de aprendizado por reforço

Modelos de séries temporais

Helpers internos

Referência

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

Este modelo foi publicado no HF papers em 2020-05-26 e contribuído para o Hugging Face Transformers em 2021-06-09.

DETR

DETR consiste em um backbone convolucional seguido por um Transformer encoder-decoder que pode ser treinado de ponta a ponta para detecção de objetos. Ele simplifica significativamente grande parte da complexidade de modelos como Faster-R-CNN e Mask-R-CNN, que utilizam elementos como propostas de região, procedimento de supressão de máximos não máximos e geração de âncoras. Além disso, o DETR também pode ser estendido naturalmente para realizar segmentação panótica, simplesmente adicionando uma cabeça de máscara sobre as saídas do decoder.

Você pode encontrar todos os checkpoints originais do DETR na organização AI at Meta.

Este modelo foi contribuído por nielsr.

Clique nos modelos DETR na barra lateral à direita para ver mais exemplos de como aplicar o DETR a diferentes tarefas de detecção de objetos e segmentação.

Defina use_kernels=True em from_pretrained() para substituir camadas compatíveis por kernels otimizados do Hub. Consulte Carregando kernels para saber mais.

O exemplo abaixo demonstra como realizar detecção de objetos com a classe Pipeline ou a classe AutoModel.

Pipeline

AutoModel

How DETR works

Aqui está um resumo explicando como o DetrForObjectDetection funciona:

Primeiro, uma imagem é enviada por meio de um backbone convolucional pré-treinado (no artigo, os autores utilizam ResNet-50/ResNet-101). Vamos supor que também adicionamos uma dimensão de lote. Isso significa que a entrada para o backbone é um tensor de forma (batch_size, 3, height, width), assumindo que a imagem possui 3 canais de cor (RGB). O backbone da CNN produz um novo mapa de características de menor resolução, tipicamente de forma (batch_size, 2048, height/32, width/32). Em seguida, esse mapa é projetado para corresponder à dimensão oculta do Transformer do DETR, que é 256 por padrão, usando uma camada nn.Conv2D. Assim, agora temos um tensor de forma (batch_size, 256, height/32, width/32). A seguir, o mapa de características é achatado e transposto para obter um tensor de forma (batch_size, seq_len, d_model) = (batch_size, width/32*height/32, 256). Portanto, uma diferença em relação aos modelos de NLP é que o comprimento da sequência é, na verdade, mais longo do que o habitual, mas com um d_model menor (que em NLP é tipicamente 768 ou superior).

Em seguida, isso é enviado pelo encoder, produzindo encoder_hidden_states da mesma forma (você pode considerar esses como recursos da imagem). A seguir, os chamados object queries são enviados pelo decoder. Trata-se de um tensor de forma (batch_size, num_queries, d_model), com num_queries tipicamente definido como 100 e inicializado com zeros. Esses embeddings de entrada são codificações posicionais aprendidas, às quais os autores se referem como object queries, e, de forma semelhante ao encoder, são somados à entrada de cada camada de atenção. Cada object query buscará um objeto específico na imagem. O decoder atualiza esses embeddings por meio de múltiplas camadas de autoatenção e de atenção encoder-decoder para produzir decoder_hidden_states da mesma forma: (batch_size, num_queries, d_model). A seguir, dois heads são adicionados no topo para detecção de objetos: uma camada linear para classificar cada object query em um dos objetos ou “no object”, e um MLP para prever caixas delimitadoras para cada query.

O modelo é treinado usando uma perda de correspondência bipartida: portanto, o que realmente fazemos é comparar as classes e caixas delimitadoras previstas de cada uma das N = 100 consultas de objeto com as anotações de referência, preenchidas até o mesmo comprimento N (ou seja, se uma imagem contém apenas 4 objetos, 96 anotações terão apenas “sem objeto” como classe e “sem caixa delimitadora” como caixa delimitadora). O algoritmo de correspondência húngara é usado para encontrar um mapeamento ótimo um-para-um de cada uma das N consultas para cada uma das N anotações. Em seguida, a entropia cruzada padrão (para as classes) e uma combinação linear da L1 e da perda de IoU generalizada (para as caixas delimitadoras) são usadas para otimizar os parâmetros do modelo.

O DETR pode ser estendido de forma natural para realizar segmentação panótica (que unifica a segmentação semântica e a segmentação de instâncias). DetrForSegmentation adiciona uma cabeça de máscara de segmentação sobre o DetrForObjectDetection. A cabeça de máscara pode ser treinada de forma conjunta ou em um processo de duas etapas, no qual primeiro se treina um modelo DetrForObjectDetection para detectar caixas delimitadoras ao redor tanto de "things" (instâncias) quanto de "stuff" (elementos de fundo, como árvores, estradas e céu), e então se congelam todos os pesos e treina-se apenas a cabeça de máscara por 25 épocas. Experimentalmente, essas duas abordagens produzem resultados semelhantes. Observe que a previsão de caixas é necessária para que o treinamento seja possível, pois o pareamento húngaro é calculado usando distâncias entre caixas.

Observações

O DETR utiliza os chamados object queries para detectar objetos em uma imagem. O número de queries determina o número máximo de objetos que podem ser detectados em uma única imagem e é definido como 100 por padrão (veja o parâmetro num_queries de DetrConfig). Observe que é bom ter alguma folga (no COCO, os autores usaram 100, enquanto o número máximo de objetos em uma imagem do COCO é ~70).
O decodificador do DETR atualiza os embeddings de consulta em paralelo. Isso difere de modelos de linguagem como o GPT-2, que utilizam decodificação autoregressiva em vez de paralela. Portanto, nenhuma máscara de atenção causal é utilizada.
O DETR adiciona embeddings de posição aos estados ocultos em cada camada de autoatenção e atenção cruzada antes de projetá-los em consultas e chaves. Para os embeddings de posição da imagem, é possível escolher entre embeddings de posição absolutos fixos sinusoidais ou aprendidos. Por padrão, o parâmetro position_embedding_type de DetrConfig é definido como "sine".
Durante o treinamento, os autores do DETR constataram que era útil usar perdas auxiliares no decodificador, especialmente para ajudar o modelo a produzir o número correto de objetos de cada classe. Se você definir o parâmetro auxiliary_loss de DetrConfig como True, redes neurais feedforward de previsão e perdas húngaras são adicionadas após cada camada do decodificador (com os FFNs compartilhando parâmetros).
Se você deseja treinar o modelo em um ambiente distribuído entre vários nós, é necessário atualizar a variável num_boxes na classe DetrLoss do arquivo modeling_detr.py. Ao treinar em vários nós, esse valor deve ser definido como o número médio de caixas de alvo entre todos os nós, conforme pode ser visto na implementação original aqui.
DetrForObjectDetection e DetrForSegmentation podem ser inicializados com qualquer backbone convolucional disponível na biblioteca timm. Por exemplo, para inicializar com um backbone MobileNet, basta definir o atributo backbone de DetrConfig como "tf_mobilenetv3_small_075" e, em seguida, inicializar o modelo com essa configuração.
O DETR redimensiona as imagens de entrada de modo que o lado mais curto tenha pelo menos uma certa quantidade de pixels, enquanto o lado mais longo tenha no máximo 1333 pixels. Durante o treinamento, é usada a escala de aumento (scale augmentation), de modo que o lado mais curto é definido aleatoriamente para ter pelo menos 480 e no máximo 800 pixels. Durante a inferência, o lado mais curto é definido como 800. É possível usar DetrImageProcessor para preparar as imagens (e anotações opcionais no formato COCO) para o modelo. Devido a esse redimensionamento, as imagens em um lote podem ter tamanhos diferentes. O DETR resolve isso preenchendo as imagens até o maior tamanho do lote e criando uma máscara de pixels que indica quais pixels são reais e quais são preenchimento. Alternativamente, também é possível definir uma collate_fn personalizada para agrupar as imagens em lotes, usando ~transformers.DetrImageProcessor.pad_and_create_pixel_mask.
O tamanho das imagens determinará a quantidade de memória utilizada e, portanto, o batch_size. Recomenda-se usar um tamanho de lote de 2 por GPU. Consulte este thread no Github para mais informações.

Existem outras três maneiras de instanciar um modelo DETR (dependendo da sua preferência):

Opção 1: Instanciar o DETR com pesos pré-treinados para o modelo inteiro

from transformers import DetrForObjectDetection


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

Opção 2: Instanciar o DETR com pesos inicializados aleatoriamente para o Transformer, mas com pesos pré-treinados para o backbone

from transformers import DetrConfig, DetrForObjectDetection


config = DetrConfig()
model = DetrForObjectDetection(config)

Opção 3: Instanciar o DETR com pesos inicializados aleatoriamente para o backbone + Transformer

config = DetrConfig()
model = DetrForObjectDetection(config)

Como resumo, considere a seguinte tabela:

Tarefa	Detecção de objetos	Segmentação de instâncias	Segmentação panótica
Descrição	Previsão de caixas delimitadoras e rótulos de classes ao redor de objetos em uma imagem	Prever máscaras ao redor de objetos (ou seja, instâncias) em uma imagem	Prever máscaras em torno de ambos os objetos (ou seja, instâncias) e também de "stuff" (ou seja, elementos de fundo, como árvores e estradas) em uma imagem
Modelo	DetrForObjectDetection	DetrForSegmentation	DetrForSegmentation
Conjunto de dados de exemplo	Detecção COCO	Detecção COCO, panóptico COCO	COCO panótico
Formato das anotações a serem fornecidas para DetrImageProcessor	{‘image_id’: `int`, ‘annotations’: `list[Dict]`} em que cada Dict é uma anotação de objeto COCO	{‘image_id’: `int`, ‘annotations’: `list[Dict]`} (no caso de detecção COCO) ou {‘file_name’: `str`, ‘image_id’: `int`, ‘segments_info’: `list[Dict]`} (no caso de panóptico COCO)	{‘file_name’: `str`, ‘image_id’: `int`, ‘segments_info’: `list[Dict]`} e masks_path (caminho para o diretório contendo os arquivos PNG das máscaras)
Processamento pós (ou seja, converter a saída do modelo para o formato Pascal VOC)	`~transformers.DetrImageProcessor.post_process`	`~transformers.DetrImageProcessor.post_process_segmentation`	`~transformers.DetrImageProcessor.post_process_segmentation`, `~transformers.DetrImageProcessor.post_process_panoptic`
avaliadores	`CocoEvaluator` com `iou_types="bbox"`	`CocoEvaluator` com `iou_types="bbox"` ou `"segm"`	`CocoEvaluator` com `iou_types="bbox"` ou `"segm"`, `PanopticEvaluator`

Em resumo, os dados devem ser preparados no formato de detecção COCO ou no formato panótico COCO. Em seguida, utilize DetrImageProcessor para criar pixel_values, pixel_mask e, opcionalmente, labels, que podem ser usados para treinar (ou ajustar finamente) um modelo.
Para a avaliação, primeiro é necessário converter as saídas do modelo usando um dos métodos de pós-processamento de DetrImageProcessor. Esses resultados podem ser fornecidos para CocoEvaluator ou PanopticEvaluator, que permitem calcular métricas como mean Average Precision (mAP) e Panoptic Quality (PQ). Os últimos objetos são implementados no repositório original. Consulte os notebooks de exemplo para mais informações sobre a avaliação.

Recursos

Consulte estes notebooks para exemplos de ajuste fino de DetrForObjectDetection e DetrForSegmentation em um conjunto de dados personalizado.

Transformers

DETR

Observações

Recursos

DetrConfig

classe transformers.DetrConfig

DetrImageProcessor

classe transformers.DetrImageProcessor

pré-processamento

post_process_object_detection

post_process_semantic_segmentation

post_process_instance_segmentation

post_process_panoptic_segmentation

DetrImageProcessorPil

classe transformers.DetrImageProcessorPil

pré-processamento

post_process_object_detection

post_process_semantic_segmentation

post_process_instance_segmentation

post_process_panoptic_segmentation

Saídas específicas do DETR

classe transformers.models.detr.modeling_detr.DetrModelOutput

classe transformers.models.detr.modeling_detr.DetrObjectDetectionOutput

classe transformers.models.detr.modeling_detr.DetrSegmentationOutput

DetrModel

classe transformers.DetrModel

forward

DetrForObjectDetection

classe transformers.DetrForObjectDetection

forward

DetrForSegmentation

classe transformers.DetrForSegmentation

forward