# D-FINE

## Visão geral

O modelo D-FINE foi proposto em [D-FINE: Redefine Regression Task in DETRs as Fine-grained Distribution Refinement](https://huggingface.co/papers/2410.13842) por Yansong Peng, Hebei Li, Peixi Wu, Yueyi Zhang, Xiaoyan Sun, Feng Wu

O resumo do artigo é o seguinte:

*Apresentamos o D-FINE, um detector de objetos em tempo real de alto desempenho que atinge uma precisão de localização excepcional ao redefinir a tarefa de regressão de bounding boxes em modelos DETR. O D-FINE compreende dois componentes-chave: Fine-grained Distribution Refinement (FDR) e Global Optimal Localization Self-Distillation (GO-LSD). O FDR transforma o processo de regressão de prever coordenadas fixas para refinar distribuições de probabilidade de forma iterativa, fornecendo uma representação intermediária de granularidade fina que melhora significativamente a precisão da localização. O GO-LSD é uma estratégia de otimização bidirecional que transfere o conhecimento de localização das distribuições refinadas para camadas mais rasas por meio de auto-destilação, ao mesmo tempo em que simplifica as tarefas de predição residual para camadas mais profundas. Além disso, o D-FINE incorpora otimizações leves em módulos e operações computacionalmente intensivos, alcançando um melhor equilíbrio entre velocidade e precisão. Especificamente, o D-FINE-L / X atinge 54,0% / 55,8% de AP no conjunto de dados COCO a 124 / 78 FPS em uma GPU NVIDIA T4. Quando pré-treinado no Objects365, o D-FINE-L / X atinge 57,1% / 59,3% de AP, superando todos os detectores em tempo real existentes. Além disso, nosso método melhora significativamente o desempenho de uma ampla variedade de modelos DETR em até 5,3% de AP, com parâmetros e custos de treinamento adicionais insignificantes. Nosso código e modelos pré-treinados: this https URL.*

Este modelo foi contribuído por [VladOS95-cyber](https://github.com/VladOS95-cyber). O código original pode ser encontrado [aqui](https://github.com/Peterande/D-FINE).

## Dicas de uso

```python
import torch

from transformers import AutoImageProcessor, DFineForObjectDetection
from transformers.image_utils import load_image

url = 'http://images.cocodataset.org/val2017/000000039769.jpg'
image = load_image(url)

image_processor = AutoImageProcessor.from_pretrained("ustc-community/dfine_x_coco")
model = DFineForObjectDetection.from_pretrained("ustc-community/dfine_x_coco", device_map="auto")

inputs = image_processor(images=image, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model(**inputs)

results = image_processor.post_process_object_detection(outputs, target_sizes=[(image.height, image.width)], threshold=0.5)

for result in results:
    for score, label_id, box in zip(result["scores"], result["labels"], result["boxes"]):
        score, label = score.item(), label_id.item()
        box = [round(i, 2) for i in box.tolist()]
        print(f"{model.config.id2label[label]}: {score:.2f} {box}")
cat: 0.96 [344.49, 23.4, 639.84, 374.27]
cat: 0.96 [11.71, 53.52, 316.64, 472.33]
remote: 0.95 [40.46, 73.7, 175.62, 117.57]
sofa: 0.92 [0.59, 1.88, 640.25, 474.74]
remote: 0.89 [333.48, 77.04, 370.77, 187.3]
```

## DFineConfig[[transformers.DFineConfig]]

#### transformers.DFineConfig[[transformers.DFineConfig]]

```python
transformers.DFineConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, is_encoder_decoder: bool = True, initializer_range: float = 0.01, initializer_bias_prior_prob: float | None = None, layer_norm_eps: float = 1e-05, batch_norm_eps: float = 1e-05, backbone_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None, freeze_backbone_batch_norms: bool = True, encoder_hidden_dim: int = 256, encoder_in_channels: list[int] | tuple[int, ...] = (512, 1024, 2048), feat_strides: list[int] | tuple[int, ...] = (8, 16, 32), encoder_layers: int = 1, encoder_ffn_dim: int = 1024, encoder_attention_heads: int = 8, dropout: float | int = 0.0, activation_dropout: float | int = 0.0, encode_proj_layers: list[int] | tuple[int, ...] = (2,), positional_encoding_temperature: int = 10000, encoder_activation_function: str = 'gelu', activation_function: str = 'silu', eval_size: int | None = None, normalize_before: bool = False, hidden_expansion: float = 1.0, d_model: int = 256, num_queries: int = 300, decoder_in_channels: list[int] | tuple[int, ...] = (256, 256, 256), decoder_ffn_dim: int = 1024, num_feature_levels: int = 3, decoder_n_points: int | list[int] = 4, decoder_layers: int = 6, decoder_attention_heads: int = 8, decoder_activation_function: str = 'relu', attention_dropout: float | int = 0.0, num_denoising: int = 100, label_noise_ratio: float = 0.5, box_noise_scale: float = 1.0, learn_initial_query: bool = False, anchor_image_size: int | list[int] | None = None, with_box_refine: bool = True, matcher_alpha: float = 0.25, matcher_gamma: float = 2.0, matcher_class_cost: float = 2.0, matcher_bbox_cost: float = 5.0, matcher_giou_cost: float = 2.0, use_focal_loss: bool = True, auxiliary_loss: bool = True, focal_loss_alpha: float = 0.75, focal_loss_gamma: float = 2.0, weight_loss_vfl: float = 1.0, weight_loss_bbox: float = 5.0, weight_loss_giou: float = 2.0, weight_loss_fgl: float = 0.15, weight_loss_ddf: float = 1.5, eos_coefficient: float = 0.0001, eval_idx: int = -1, layer_scale: int | float = 1.0, max_num_bins: int = 32, reg_scale: float = 4.0, depth_mult: float = 1.0, top_prob_values: int = 4, lqe_hidden_dim: int = 64, lqe_layers: int = 2, decoder_offset_scale: float = 0.5, decoder_method: str = 'default', up: float = 0.5, tie_word_embeddings: bool = True)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/d_fine/configuration_d_fine.py#L31)

**Parâmetros:**

is_encoder_decoder (`bool`, *opcional*, padrão `True`) : Indica se o modelo é usado como codificador/decodificador ou não.

initializer_range (`float`, *opcional*, padrão `0.01`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

initializer_bias_prior_prob (`float`, *opcional*) : A probabilidade a priori usada pelo inicializador de viés para inicializar os vieses de `enc_score_head` e `class_embed`. Se `None`, `prior_prob` é calculado como `prior_prob = 1 / (num_labels + 1)` durante a inicialização dos pesos do modelo.

layer_norm_eps (`float`, *opcional*, padrão `1e-05`) : O epsilon usado pelas camadas de normalização de camada.

batch_norm_eps (`float`, *opcional*, padrão `1e-05`) : O epsilon usado pelas camadas de normalização de lote.

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : A configuração do modelo backbone.

freeze_backbone_batch_norms (`bool`, *opcional*, padrão `True`) : Se as camadas de normalização de lote no backbone devem ser congeladas.

encoder_hidden_dim (`int`, *opcional*, padrão `256`) : Dimensão das representações ocultas.

encoder_in_channels (`list`, *opcional*, padrão `[512, 1024, 2048]`) : Entrada de recursos em múltiplos níveis para o encoder.

feat_strides (`list[int]`, *opcional*, padrão `[8, 16, 32]`) : Passos usados em cada mapa de características.

encoder_layers (`int`, *opcional*, padrão `1`) : Número de camadas ocultas no codificador do Transformer. Usará o mesmo valor de `num_layers` se não for definido.

encoder_ffn_dim (`int`, *opcional*, padrão `1024`) : Dimensionalidade da camada "intermediária" (frequentemente chamada de feed-forward) no codificador.

encoder_attention_heads (`int`, *opcional*, padrão `8`) : Número de cabeças de atenção para cada camada de atenção no codificador do Transformer.

dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A proporção para todas as camadas de dropout.

activation_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A taxa de dropout para as ativações dentro da camada totalmente conectada.

encode_proj_layers (`list[int]`, *opcional*, padrão `[2]`) : Índices das camadas projetadas a serem usadas no codificador.

positional_encoding_temperature (`int`, *opcional*, padrão 10000) : O parâmetro de temperatura usado para criar as codificações posicionais.

encoder_activation_function (`str`, *opcional*, padrão `"gelu"`) : A função de ativação não linear (função ou string) no encoder e no pooler. Se for string, `"gelu"`, `"relu"`, `"silu"` e `"gelu_new"` são suportadas.

activation_function (`str`, *opcional*, padrão `silu`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

eval_size (`tuple[int, int]`, *opcional*) : Altura e largura usadas para calcular a altura e a largura efetivas dos embeddings de posição, considerando o stride.

normalize_before (`bool`, *opcional*, padrão `False`) : Determina se a normalização de camada deve ser aplicada na camada do codificador do transformer antes dos módulos de autoatenção e de avanço.

hidden_expansion (`float`, *opcional*, padrão 1.0) : Razão de expansão para aumentar o tamanho da dimensão de RepVGGBlock e CSPRepLayer.

d_model (`int`, *opcional*, padrão `256`) : Tamanho das camadas do codificador e da camada pooler.

num_queries (`int`, *opcional*, padrão 300) : Número de consultas de objeto.

decoder_in_channels (`list`, *opcional*, padrão `[256, 256, 256]`) : Dimensão dos recursos em múltiplos níveis para o decoder

decoder_ffn_dim (`int`, *opcional*, padrão `1024`) : Dimensionalidade da camada "intermediária" (frequentemente chamada de feed-forward) no decodificador.

num_feature_levels (`int`, *opcional*, padrão 3) : O número de níveis de recursos de entrada.

decoder_n_points (`int`, *opcional*, padrão 4) : O número de chaves amostradas em cada nível de recurso para cada cabeça de atenção no decodificador.

decoder_layers (`int`, *opcional*, padrão `6`) : Número de camadas ocultas no decodificador do Transformer. Usará o mesmo valor de `num_layers` se não for definido.

decoder_attention_heads (`int`, *opcional*, padrão `8`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

decoder_activation_function (`str`, *opcional*, padrão `"relu"`) : A função de ativação não linear (função ou string) no decodificador. Se for string, `"gelu"`, `"relu"`, `"silu"` e `"gelu_new"` são suportadas.

attention_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A taxa de dropout para as probabilidades de atenção.

num_denoising (`int`, *opcional*, padrão 100) : O número total de tarefas ou consultas de desruido a serem usadas para o desruido contrastivo.

label_noise_ratio (`float`, *opcional*, padrão 0.5) : A fração de rótulos de desruidamento à qual o ruído aleatório deve ser adicionado.

box_noise_scale (`float`, *opcional*, padrão 1.0) : Escala ou magnitude do ruído a ser adicionado às bounding boxes.

learn_initial_query (`bool`, *opcional*, padrão `False`) : Indica se os embeddings de consulta iniciais do decodificador devem ser aprendidos durante o treinamento

anchor_image_size (`tuple[int, int]`, *opcional*) : Altura e largura da imagem de entrada usada durante a avaliação para gerar as âncoras de bounding box. Se for None, a geração automática de âncoras é aplicada.

with_box_refine (`bool`, *opcional*, padrão `True`) : Se deve aplicar refinamento iterativo de caixas delimitadoras, em que cada camada do decodificador refina as caixas delimitadoras com base nas previsões da camada anterior.

matcher_alpha (`float`, *opcional*, padrão 0.25) : Parâmetro alpha usado pelo Hungarian Matcher.

matcher_gamma (`float`, *opcional*, padrão 2.0) : Parâmetro gamma usado pelo Hungarian Matcher.

matcher_class_cost (`float`, *opcional*, padrão 2.0) : O peso relativo da perda de classe usado pelo Hungarian Matcher.

matcher_bbox_cost (`float`, *opcional*, padrão 5.0) : O peso relativo da perda da caixa delimitadora usado pelo Hungarian Matcher.

matcher_giou_cost (`float`, *opcional*, padrão 2.0) : O peso relativo da perda giou usada pelo Hungarian Matcher.

use_focal_loss (`bool`, *opcional*, padrão `True`) : Parâmetro que informa se a focal loss deve ser usada.

auxiliary_loss (`bool`, *opcional*, padrão `True`) : Se as perdas de decodificação auxiliares (perdas em cada camada do decodificador) devem ser usadas.

focal_loss_alpha (`float`, *opcional*, padrão 0.75) : Parâmetro alpha usado para calcular a focal loss.

focal_loss_gamma (`float`, *opcional*, padrão 2.0) : Parâmetro gamma usado para calcular a focal loss.

weight_loss_vfl (`float`, *opcional*, padrão 1.0) : Peso relativo da perda varifocal na perda de detecção de objetos.

weight_loss_bbox (`float`, *opcional*, padrão 5.0) : Peso relativo da perda de caixa delimitadora L1 na perda de detecção de objetos.

weight_loss_giou (`float`, *opcional*, padrão 2.0) : Peso relativo da perda de IoU generalizada na perda de detecção de objetos.

weight_loss_fgl (`float`, *opcional*, padrão 0.15) : Peso relativo da perda de localização de granularidade fina na perda de detecção de objetos.

weight_loss_ddf (`float`, *opcional*, padrão 1.5) : Peso relativo da perda focal de destilação desacoplada na perda de detecção de objetos.

eos_coefficient (`float`, *opcional*, padrão `0.0001`) : Peso relativo de classificação da classe 'no-object' na perda de detecção de objetos.

eval_idx (`int`, *opcional*, padrão -1) : Índice da camada do decodificador a ser usada para avaliação. Se negativo, conta a partir do final (por exemplo, -1 significa usar a última camada). Isso permite a previsão antecipada na pilha do decodificador, enquanto as camadas posteriores continuam sendo treinadas.

layer_scale (`float`, *opcional*, padrão `1.0`) : Fator de escala para a dimensão oculta nas camadas posteriores do decodificador. Usado para ajustar a capacidade do modelo após a camada de avaliação.

max_num_bins (`int`, *opcional*, padrão 32) : Número máximo de bins para o refinamento de bounding boxes guiado por distribuição. Valores maiores permitem uma localização mais detalhada, mas aumentam a computação.

reg_scale (`float`, *opcional*, padrão 4.0) : Fator de escala para a distribuição de regressão. Controla a amplitude e a granularidade do processo de refinamento da caixa delimitadora.

depth_mult (`float`, *opcional*, padrão 1.0) : Multiplicador para o número de blocos nas camadas RepNCSPELAN4. Usado para escalar a profundidade do modelo mantendo sua arquitetura.

top_prob_values (`int`, *opcional*, padrão 4) : Número de valores de probabilidade mais altos a considerar da distribuição de cada canto.

lqe_hidden_dim (`int`, *opcional*, padrão 64) : Tamanho da dimensão oculta para a rede Location Quality Estimator (LQE).

lqe_layers (`int`, *opcional*, padrão 2) : Número de camadas no MLP do Location Quality Estimator.

decoder_offset_scale (`float`, *opcional*, padrão 0.5) : Escala de deslocamento usada na atenção deformável.

decoder_method (`str`, *opcional*, padrão `"default"`) : O método a ser usado para o decodificador: `"default"` ou `"discrete"`.

up (`float`, *opcional*, padrão 0.5) : Controla os limites superiores da Função de Ponderação.

tie_word_embeddings (`bool`, *opcional*, padrão `True`) : Se deve vincular as embeddings de pesos de acordo com o mapeamento `tied_weights_keys` do modelo.

Esta é a classe de configuração para armazenar a configuração de um DFineModel. Ela é usada para instanciar um modelo D Fine de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [ustc-community/dfine-xlarge-coco](https://huggingface.co/ustc-community/dfine-xlarge-coco)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

## DFineModel[[transformers.DFineModel]]

#### transformers.DFineModel[[transformers.DFineModel]]

```python
transformers.DFineModel(config: DFineConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/d_fine/modeling_d_fine.py#L1540)

**Parâmetros:**

config ([DFineConfig](/docs/transformers/main/pt/model_doc/d_fine#transformers.DFineConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

Modelo RT-DETR (composto por um backbone e um encoder-decoder) que produz estados ocultos brutos, sem nenhum head no topo.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

#### forward[[transformers.DFineModel.forward]]

```python
forward(pixel_values: Tensor, pixel_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: list[dict] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/d_fine/modeling_d_fine.py#L1666)

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando `image_processor_class`. Consulte `image_processor_class.__call__` para obter detalhes (`processor_class` usa `image_processor_class` para processar imagens).

pixel_mask (`torch.LongTensor` de forma `(batch_size, height, width)`, *opcional*) : Máscara para evitar a execução de atenção em valores de pixels de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para pixels reais (ou seja, **não mascarados**), - 0 para pixels de preenchimento (ou seja, **mascarados**).  [O que são máscaras de atenção?](../glossary#attention-mask)

encoder_outputs (`torch.Tensor`, *opcional*) : Tupla consiste em (`last_hidden_state`, *opcional*: `hidden_states`, *opcional*: `attentions`) `last_hidden_state` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) é uma sequência de hidden-states na saída da última camada do codificador. Usado na cross-attention do decodificador.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar o mapa de recursos achatado (saída do backbone + camada de projeção), você pode escolher passar diretamente uma representação achatada de uma imagem.

labels (`list[Dict]` of len `(batch_size,)`, *optional*) : Labels for computing the bipartite matching loss. List of dicts, each dictionary containing at least the following 2 keys: 'class_labels' and 'boxes' (the class labels and bounding boxes of an image in the batch respectively). The class labels themselves should be a `torch.LongTensor` of len `(number of bounding boxes in the image,)` and the boxes a `torch.Tensor` of shape `(number of bounding boxes in the image, 4)`.

**Retorna:** `DFineModelOutput` ou `tuple(torch.Tensor)`

Um `DFineModelOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos dependendo da configuração (`None`) e das entradas.

O método forward do [DFineModel](/docs/transformers/main/pt/model_doc/d_fine#transformers.DFineModel) sobrescreve o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, num_queries, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do decodificador do modelo.
- **intermediate_hidden_states** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, hidden_size)`) -- Estados ocultos intermediários empilhados (saída de cada camada do decodificador).
- **intermediate_logits** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, sequence_length, config.num_labels)`) -- Logits intermediários empilhados (logits de cada camada do decodificador).
- **intermediate_reference_points** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, 4)`) -- Pontos de referência intermediários empilhados (pontos de referência de cada camada do decodificador).
- **intermediate_predicted_corners** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, 4)`) -- Cantos intermediários previstos empilhados (cantos previstos de cada camada do decodificador).
- **initial_reference_points** (`torch.Tensor` de forma `(batch_size, num_queries, 4)`) -- Pontos de referência iniciais usados para a primeira camada do decodificador.
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do decodificador na saída de cada camada, além das saídas do embedding inicial.
- **decoder_attentions** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) com forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **cross_attentions** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção da camada de atenção cruzada do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de atenção cruzada.
- **encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do encoder do modelo.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do codificador na saída de cada camada, além das saídas do embedding inicial.
- **encoder_attentions** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção do codificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **init_reference_points** (`torch.Tensor` de forma `(batch_size, num_queries, 4)`) -- Pontos de referência iniciais enviados através do decodificador do Transformer.
- **enc_topk_logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.num_labels)`) -- Pontuações das caixas delimitadoras previstas, nas quais as caixas delimitadoras com as `config.two_stage_num_proposals` maiores pontuações são selecionadas como propostas de região na etapa do codificador. Saída da classificação binária de caixas delimitadoras (ou seja, primeiro plano e segundo plano).
- **enc_topk_bboxes** (`torch.Tensor` de forma `(batch_size, sequence_length, 4)`) -- Logits das coordenadas das caixas delimitadoras previstas na etapa do codificador.
- **enc_outputs_class** (`torch.Tensor` de forma `(batch_size, sequence_length, config.num_labels)`, *opcional*, retornado quando `config.with_box_refine=True` e `config.two_stage=True`) -- Pontuações das caixas delimitadoras previstas, nas quais as `config.two_stage_num_proposals` caixas delimitadoras com as maiores pontuações são selecionadas como propostas de região na primeira etapa. Saída da classificação binária de caixas delimitadoras (ou seja, primeiro plano e segundo plano).
- **enc_outputs_coord_logits** (`torch.Tensor` de forma `(batch_size, sequence_length, 4)`, *opcional*, retornado quando `config.with_box_refine=True` e `config.two_stage=True`) -- Logits das coordenadas das caixas delimitadoras previstas na primeira etapa.
- **denoising_meta_values** (`dict`, *opcional*) -- Dicionário extra para os valores relacionados ao denoising.

Exemplos:

```python
>>> from transformers import AutoImageProcessor, DFineModel
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> image_processor = AutoImageProcessor.from_pretrained("PekingU/DFine_r50vd")
>>> model = DFineModel.from_pretrained("PekingU/DFine_r50vd")

>>> inputs = image_processor(images=image, return_tensors="pt")

>>> outputs = model(**inputs)

>>> last_hidden_states = outputs.last_hidden_state
>>> list(last_hidden_states.shape)
[1, 300, 256]
```

## DFineForObjectDetection[[transformers.DFineForObjectDetection]]

#### transformers.DFineForObjectDetection[[transformers.DFineForObjectDetection]]

```python
transformers.DFineForObjectDetection(config: DFineConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/d_fine/modeling_d_fine.py#L1950)

**Parâmetros:**

config ([DFineConfig](/docs/transformers/main/pt/model_doc/d_fine#transformers.DFineConfig)) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo.

Modelo RT-DETR (composto por um backbone e um encoder-decoder) que gera bounding boxes e logits para serem decodificados em seguida em scores e classes.

Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.).

Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais.

#### forward[[transformers.DFineForObjectDetection.forward]]

```python
forward(pixel_values: Tensor, pixel_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: list[dict] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/d_fine/modeling_d_fine.py#L1989)

**Parâmetros:**

pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando `image_processor_class`. Consulte `image_processor_class.__call__` para obter detalhes (`processor_class` usa `image_processor_class` para processar imagens).

pixel_mask (`torch.LongTensor` de forma `(batch_size, height, width)`, *opcional*) : Máscara para evitar a execução de atenção em valores de pixels de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para pixels reais (ou seja, **não mascarados**), - 0 para pixels de preenchimento (ou seja, **mascarados**).  [O que são máscaras de atenção?](../glossary#attention-mask)

encoder_outputs (`torch.Tensor`, *opcional*) : Tupla consiste em (`last_hidden_state`, *opcional*: `hidden_states`, *opcional*: `attentions`) `last_hidden_state` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) é uma sequência de hidden-states na saída da última camada do codificador. Usado na cross-attention do decodificador.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

labels (`list[Dict]` of len `(batch_size,)`, *optional*) : Labels for computing the bipartite matching loss. List of dicts, each dictionary containing at least the following 2 keys: 'class_labels' and 'boxes' (the class labels and bounding boxes of an image in the batch respectively). The class labels themselves should be a `torch.LongTensor` of len `(number of bounding boxes in the image,)` and the boxes a `torch.Tensor` of shape `(number of bounding boxes in the image, 4)`.

**Retorna:** `DFineObjectDetectionOutput` ou `tuple(torch.Tensor)`

Um `DFineObjectDetectionOutput` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração (`None`) e das entradas.

O método forward de [DFineForObjectDetection](/docs/transformers/main/pt/model_doc/d_fine#transformers.DFineForObjectDetection) sobrescreve o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` são fornecidas)) -- Perda total como uma combinação linear de uma log-verossimilhança negativa (entropia cruzada) para a previsão de classe e uma perda de caixa delimitadora. Esta última é definida como uma combinação linear da perda L1 e da perda de IoU generalizada e invariante à escala.
- **loss_dict** (`Dict`, *opcional*) -- Um dicionário contendo as perdas individuais. Útil para registro de logs.
- **logits** (`torch.Tensor` de forma `(batch_size, num_queries, num_classes + 1)`) -- Logits de classificação (incluindo no-object) para todas as queries.
- **pred_boxes** (`torch.Tensor` de forma `(batch_size, num_queries, 4)`) -- Coordenadas normalizadas das caixas para todas as queries, representadas como (center_x, center_y, width, height). Esses valores são normalizados em [0, 1], relativos ao tamanho de cada imagem individual no lote (ignorando possível padding). Você pode usar `~DFineImageProcessor.post_process_object_detection` para recuperar as caixas delimitadoras não normalizadas (absolutas).
- **auxiliary_outputs** (`list[Dict]`, *opcional*) -- Opcional, retornado apenas quando as perdas auxiliares são ativadas (ou seja, `config.auxiliary_loss` está definido como `True`) e os rótulos são fornecidos. É uma lista de dicionários contendo as duas chaves acima (`logits` e `pred_boxes`) para cada camada do decodificador.
- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, num_queries, hidden_size)`) -- Sequência de estados ocultos na saída da última camada do decodificador do modelo.
- **intermediate_hidden_states** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, hidden_size)`) -- Estados ocultos intermediários empilhados (saída de cada camada do decodificador).
- **intermediate_logits** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, config.num_labels)`) -- Logits intermediários empilhados (logits de cada camada do decodificador).
- **intermediate_reference_points** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, 4)`) -- Pontos de referência intermediários empilhados (pontos de referência de cada camada do decodificador).
- **intermediate_predicted_corners** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, 4)`) -- Cantos intermediários previstos empilhados (cantos previstos de cada camada do decodificador).
- **initial_reference_points** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, 4)`) -- Pontos de referência iniciais empilhados (pontos de referência iniciais de cada camada do decoder).
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do decodificador na saída de cada camada, além das saídas do embedding inicial.
- **decoder_attentions** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) com forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **cross_attentions** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção da camada de atenção cruzada do decodificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de atenção cruzada.
- **encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do encoder do modelo.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do codificador na saída de cada camada, além das saídas do embedding inicial.
- **encoder_attentions** (`tuple[torch.Tensor]`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (uma para cada camada) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção do codificador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.
- **init_reference_points** (`torch.Tensor` de forma  `(batch_size, num_queries, 4)`) -- Pontos de referência iniciais enviados através do decodificador do Transformer.
- **enc_topk_logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.num_labels)`, *opcional*, retornado quando `config.with_box_refine=True` e `config.two_stage=True`) -- Logits das coordenadas das caixas delimitadoras previstas no codificador.
- **enc_topk_bboxes** (`torch.Tensor` de forma `(batch_size, sequence_length, 4)`, *opcional*, retornado quando `config.with_box_refine=True` e `config.two_stage=True`) -- Logits das coordenadas das caixas delimitadoras previstas no codificador.
- **enc_outputs_class** (`torch.Tensor` de forma `(batch_size, sequence_length, config.num_labels)`, *opcional*, retornado quando `config.with_box_refine=True` e `config.two_stage=True`) -- Pontuações das caixas delimitadoras previstas, nas quais as `config.two_stage_num_proposals` caixas delimitadoras com as maiores pontuações são selecionadas como propostas de região na primeira etapa. Saída da classificação binária de caixas delimitadoras (ou seja, primeiro plano e segundo plano).
- **enc_outputs_coord_logits** (`torch.Tensor` de forma `(batch_size, sequence_length, 4)`, *opcional*, retornado quando `config.with_box_refine=True` e `config.two_stage=True`) -- Logits das coordenadas das caixas delimitadoras previstas na primeira etapa.
- **denoising_meta_values** (`dict`, *opcional*) -- Dicionário extra para os valores relacionados ao denoising

Exemplo:

```python
>>> import torch
>>> from transformers.image_utils import load_image
>>> from transformers import AutoImageProcessor, DFineForObjectDetection

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> image = load_image(url)

>>> image_processor = AutoImageProcessor.from_pretrained("ustc-community/dfine-xlarge-coco")
>>> model = DFineForObjectDetection.from_pretrained("ustc-community/dfine-xlarge-coco")

>>> # prepare image for the model
>>> inputs = image_processor(images=image, return_tensors="pt")

>>> # forward pass
>>> outputs = model(**inputs)

>>> logits = outputs.logits
>>> list(logits.shape)
[1, 300, 80]

>>> boxes = outputs.pred_boxes
>>> list(boxes.shape)
[1, 300, 4]

>>> # convert outputs (bounding boxes and class logits) to Pascal VOC format (xmin, ymin, xmax, ymax)
>>> target_sizes = torch.tensor([image.size[::-1]])
>>> results = image_processor.post_process_object_detection(outputs, threshold=0.9, target_sizes=target_sizes)
>>> result = results[0]  # first image in batch

>>> for score, label, box in zip(result["scores"], result["labels"], result["boxes"]):
...     box = [round(i, 2) for i in box.tolist()]
...     print(
...         f"Detected {model.config.id2label[label.item()]} with confidence "
...         f"{round(score.item(), 3)} at location {box}"
...     )
Detected cat with confidence 0.958 at location [344.49, 23.4, 639.84, 374.27]
Detected cat with confidence 0.956 at location [11.71, 53.52, 316.64, 472.33]
Detected remote with confidence 0.947 at location [40.46, 73.7, 175.62, 117.57]
Detected sofa with confidence 0.918 at location [0.59, 1.88, 640.25, 474.74]
```