# D-FINE

## Resumen

El modelo D-FINE fue propuesto en [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

El resumen del artículo es el siguiente:

*Presentamos D-FINE, un detector de objetos en tiempo real potente que logra una precisión de localización sobresaliente al redefinir la tarea de regresión de cajas delimitadoras en los modelos DETR. D-FINE comprende dos componentes clave: Fine-grained Distribution Refinement (FDR) y Global Optimal Localization Self-Distillation (GO-LSD). FDR transforma el proceso de regresión de predecir coordenadas fijas a refinar iterativamente distribuciones de probabilidad, proporcionando una representación intermedia de gran granularidad que mejora significativamente la precisión de localización. GO-LSD es una estrategia de optimización bidireccional que transfiere el conocimiento de localización desde las distribuciones refinadas a capas más superficiales mediante autodestilación, al mismo tiempo que simplifica las tareas de predicción residual para las capas más profundas. Además, D-FINE incorpora optimizaciones ligeras en módulos y operaciones computacionalmente intensivos, logrando un mejor equilibrio entre velocidad y precisión. Específicamente, D-FINE-L / X alcanza un AP del 54,0% / 55,8% en el conjunto de datos COCO a 124 / 78 FPS en una GPU NVIDIA T4. Cuando se preentrena en Objects365, D-FINE-L / X alcanza un AP del 57,1% / 59,3%, superando a todos los detectores en tiempo real existentes. Además, nuestro método mejora significativamente el rendimiento de una amplia gama de modelos DETR en hasta un 5,3% de AP, con parámetros y costos de entrenamiento adicionales insignificantes. Nuestro código y modelos preentrenados: this https URL.*

Este modelo fue aportado por [VladOS95-cyber](https://github.com/VladOS95-cyber). El código original se puede encontrar [aquí](https://github.com/Peterande/D-FINE).

## Consejos 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)
```

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

**Parámetros:**

is_encoder_decoder (`bool`, *opcional*, valor predeterminado `True`) : Indica si el modelo se utiliza como codificador/decodificador o no.

initializer_range (`float`, *opcional*, valor predeterminado `0.01`) : La desviación estándar de truncated_normal_initializer para inicializar todas las matrices de pesos.

initializer_bias_prior_prob (`float`, *opcional*) : La probabilidad a priori que utiliza el inicializador de sesgos para inicializar los sesgos de `enc_score_head` y `class_embed`. Si es `None`, `prior_prob` se calcula como `prior_prob = 1 / (num_labels + 1)` durante la inicialización de los pesos del modelo.

layer_norm_eps (`float`, *opcional*, valor predeterminado `1e-05`) : El epsilon utilizado por las capas de normalización de capas.

batch_norm_eps (`float`, *opcional*, valor predeterminado `1e-05`) : El epsilon utilizado por las capas de normalización por lote.

backbone_config (`Union[dict, ~configuration_utils.PreTrainedConfig]`, *opcional*) : La configuración del modelo de base.

freeze_backbone_batch_norms (`bool`, *opcional*, valor predeterminado `True`) : Indica si se deben congelar las capas de normalización por lote en el backbone.

encoder_hidden_dim (`int`, *opcional*, valor predeterminado `256`) : Dimensión de las representaciones ocultas.

encoder_in_channels (`list`, *opcional*, valor predeterminado `[512, 1024, 2048]`) : Entrada de características de múltiples niveles para el codificador.

feat_strides (`list[int]`, *opcional*, valor predeterminado `[8, 16, 32]`) : Pasos utilizados en cada mapa de características.

encoder_layers (`int`, *opcional*, valor predeterminado `1`) : Número de capas ocultas en el codificador Transformer. Usará el mismo valor que `num_layers` si no se establece.

encoder_ffn_dim (`int`, *opcional*, valor predeterminado `1024`) : Dimensionalidad de la capa "intermedia" (a menudo denominada feed-forward) en el codificador.

encoder_attention_heads (`int`, *opcional*, valor predeterminado `8`) : Número de cabezas de atención para cada capa de atención en el codificador Transformer.

dropout (`Union[float, int]`, *opcional*, valor predeterminado `0.0`) : La proporción para todas las capas de dropout.

activation_dropout (`Union[float, int]`, *opcional*, valor predeterminado `0.0`) : La proporción de dropout para las activaciones dentro de la capa totalmente conectada.

encode_proj_layers (`list[int]`, *opcional*, valor predeterminado `[2]`) : Índices de las capas proyectadas que se usarán en el codificador.

positional_encoding_temperature (`int`, *opcional*, valor predeterminado 10000) : El parámetro de temperatura utilizado para crear las codificaciones posicionales.

encoder_activation_function (`str`, *opcional*, valor predeterminado `"gelu"`) : La función de activación no lineal (función o cadena) en el codificador y el pooler. Si es una cadena, se admiten `"gelu"`, `"relu"`, `"silu"` y `"gelu_new"`.

activation_function (`str`, *opcional*, valor predeterminado `silu`) : La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

eval_size (`tuple[int, int]`, *opcional*) : Altura y ancho utilizados para calcular la altura y el ancho efectivos de las incrustaciones de posición, teniendo en cuenta el paso.

normalize_before (`bool`, *opcional*, valor predeterminado `False`) : Determina si se aplica la normalización de capas en la capa del codificador del transformer antes de los módulos de autoatención y de avance hacia adelante.

hidden_expansion (`float`, *opcional*, valor predeterminado 1.0) : Ratio de expansión para aumentar el tamaño de la dimensión de RepVGGBlock y CSPRepLayer.

d_model (`int`, *opcional*, valor predeterminado `256`) : Tamaño de las capas del codificador y de la capa pooler.

num_queries (`int`, *opcional*, valor predeterminado 300) : Número de consultas de objetos.

decoder_in_channels (`list`, *opcional*, valor predeterminado `[256, 256, 256]`) : Dimensión de las características de varios niveles para el decodificador

decoder_ffn_dim (`int`, *opcional*, valor predeterminado `1024`) : Dimensionalidad de la capa "intermedia" (a menudo denominada feed-forward) en el decodificador.

num_feature_levels (`int`, *opcional*, valor predeterminado 3) : El número de niveles de características de entrada.

decoder_n_points (`int`, *opcional*, valor predeterminado: 4) : El número de claves muestreadas en cada nivel de características para cada cabeza de atención en el decodificador.

decoder_layers (`int`, *opcional*, valor predeterminado `6`) : Número de capas ocultas en el decodificador Transformer. Usará el mismo valor que `num_layers` si no se establece.

decoder_attention_heads (`int`, *opcional*, valor predeterminado `8`) : Número de cabezas de atención para cada capa de atención en el decodificador del Transformer.

decoder_activation_function (`str`, *opcional*, valor predeterminado `"relu"`) : La función de activación no lineal (función o cadena) en el decodificador. Si es una cadena, se admiten `"gelu"`, `"relu"`, `"silu"` y `"gelu_new"`.

attention_dropout (`Union[float, int]`, *opcional*, valor predeterminado `0.0`) : La proporción de dropout para las probabilidades de atención.

num_denoising (`int`, *opcional*, valor predeterminado 100) : El número total de tareas o consultas de denoising que se usarán para el denoising contrastivo.

label_noise_ratio (`float`, *opcional*, valor predeterminado 0.5) : La fracción de etiquetas de desruido a las que se debe añadir ruido aleatorio.

box_noise_scale (`float`, *opcional*, valor predeterminado 1.0) : Escala o magnitud del ruido que se añadirá a las cajas delimitadoras.

learn_initial_query (`bool`, *opcional*, valor predeterminado `False`) : Indica si las incrustaciones de consulta iniciales del decodificador deben aprenderse durante el entrenamiento

anchor_image_size (`tuple[int, int]`, *opcional*) : Altura y ancho de la imagen de entrada utilizada durante la evaluación para generar las anclas de las cajas delimitadoras. Si es None, se aplica la generación automática de anclas.

with_box_refine (`bool`, *opcional*, valor predeterminado `True`) : Si se aplica el refinamiento iterativo de cajas delimitadoras, donde cada capa del decodificador refina las cajas delimitadoras en función de las predicciones de la capa anterior.

matcher_alpha (`float`, *opcional*, valor predeterminado 0.25) : Parámetro alpha utilizado por el Hungarian Matcher.

matcher_gamma (`float`, *opcional*, valor predeterminado 2.0) : Parámetro gamma utilizado por el Hungarian Matcher.

matcher_class_cost (`float`, *opcional*, valor predeterminado 2.0) : El peso relativo de la pérdida de clase utilizada por el Hungarian Matcher.

matcher_bbox_cost (`float`, *opcional*, valor predeterminado 5.0) : El peso relativo de la pérdida de la caja delimitadora utilizada por el Hungarian Matcher.

matcher_giou_cost (`float`, *opcional*, valor predeterminado 2.0) : El peso relativo de la pérdida giou utilizada por el Hungarian Matcher.

use_focal_loss (`bool`, *opcional*, valor predeterminado `True`) : Parámetro que indica si se debe utilizar la pérdida focal.

auxiliary_loss (`bool`, *opcional*, valor predeterminado `True`) : Si se deben utilizar las pérdidas auxiliares de decodificación (pérdidas en cada capa del decodificador).

focal_loss_alpha (`float`, *opcional*, valor predeterminado 0.75) : Parámetro alpha utilizado para calcular la focal loss.

focal_loss_gamma (`float`, *opcional*, valor predeterminado 2.0) : Parámetro gamma utilizado para calcular la focal loss.

weight_loss_vfl (`float`, *opcional*, valor predeterminado 1.0) : Peso relativo de la pérdida varifocal en la pérdida de detección de objetos.

weight_loss_bbox (`float`, *opcional*, valor predeterminado 5.0) : Peso relativo de la pérdida de caja delimitadora L1 en la pérdida de detección de objetos.

weight_loss_giou (`float`, *opcional*, valor predeterminado 2.0) : Peso relativo de la pérdida de IoU generalizada en la pérdida de detección de objetos.

weight_loss_fgl (`float`, *opcional*, valor predeterminado 0.15) : Peso relativo de la pérdida de localización de granularidad fina en la pérdida de detección de objetos.

weight_loss_ddf (`float`, *opcional*, valor predeterminado 1.5) : Peso relativo de la pérdida focal de destilación desacoplada en la pérdida de detección de objetos.

eos_coefficient (`float`, *opcional*, valor predeterminado `0.0001`) : Peso de clasificación relativo de la clase 'no-object' en la función de pérdida de detección de objetos.

eval_idx (`int`, *opcional*, valor predeterminado: -1) : Índice de la capa del decodificador que se utilizará para la evaluación. Si es negativo, se cuenta desde el final (p. ej., -1 significa usar la última capa). Esto permite realizar predicciones tempranas en la pila del decodificador mientras se siguen entrenando las capas posteriores.

layer_scale (`float`, *opcional*, valor predeterminado `1.0`) : Factor de escala para la dimensión oculta en las capas posteriores del decodificador. Se utiliza para ajustar la capacidad del modelo después de la capa de evaluación.

max_num_bins (`int`, *opcional*, valor predeterminado: 32) : Número máximo de intervalos para el refinamiento de la caja delimitadora guiado por la distribución. Valores más altos permiten una localización más detallada, pero aumentan la carga de cálculo.

reg_scale (`float`, *opcional*, valor predeterminado 4.0) : Factor de escala para la distribución de regresión. Controla el rango y la granularidad del proceso de refinamiento de las cajas delimitadoras.

depth_mult (`float`, *opcional*, valor predeterminado 1.0) : Multiplicador para el número de bloques en las capas RepNCSPELAN4. Se utiliza para escalar la profundidad del modelo manteniendo su arquitectura.

top_prob_values (`int`, *opcional*, valor predeterminado 4) : Número de valores de probabilidad superior a considerar de la distribución de cada esquina.

lqe_hidden_dim (`int`, *opcional*, valor predeterminado: 64) : Tamaño de la dimensión oculta para la red Location Quality Estimator (LQE).

lqe_layers (`int`, *opcional*, valor predeterminado 2) : Número de capas en la MLP del estimador de calidad de ubicación.

decoder_offset_scale (`float`, *opcional*, valor predeterminado 0.5) : Escala de desplazamiento utilizada en la atención deformable.

decoder_method (`str`, *opcional*, valor predeterminado `"default"`) : El método a utilizar para el decodificador: `"default"` o `"discrete"`.

up (`float`, *opcional*, valor predeterminado 0.5) : Controla los límites superiores de la Weighting Function.

tie_word_embeddings (`bool`, *opcional*, valor predeterminado `True`) : Indica si se deben vincular las incrustaciones de pesos según el mapeo `tied_weights_keys` del modelo.

Esta es la clase de configuración para almacenar la configuración de un DFineModel. Se utiliza para instanciar un modelo D Fine según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de [ustc-community/dfine-xlarge-coco](https://huggingface.co/ustc-community/dfine-xlarge-coco)

Los objetos de configuración heredan de [PreTrainedConfig](/docs/transformers/v5.23.0/es/main_classes/configuration#transformers.PreTrainedConfig) y se pueden utilizar para controlar las salidas del modelo. Consulte la documentación de [PreTrainedConfig](/docs/transformers/v5.23.0/es/main_classes/configuration#transformers.PreTrainedConfig) para obtener más información.

## DFineModel[[transformers.DFineModel]]

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

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

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

**Parámetros:**

config ([DFineConfig](/docs/transformers/v5.23.0/es/model_doc/d_fine#transformers.DFineConfig)) : Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método [from_pretrained()](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) para cargar los pesos del modelo.

Modelo RT-DETR (constituido por un backbone y un encoder-decoder) que genera estados ocultos sin procesar sin ninguna cabeza en la parte superior.

Este modelo hereda de [PreTrainedModel](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel). Consulte la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

#### 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'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/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)`) : Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener mediante `image_processor_class`. Consulte `image_processor_class.__call__` para más detalles (`processor_class` utiliza `image_processor_class` para procesar las imágenes).

pixel_mask (`torch.LongTensor` de forma `(batch_size, height, width)`, *opcional*) : Máscara para evitar realizar atención sobre los valores de píxeles de relleno. Valores de la máscara seleccionados en `[0, 1]`:  - 1 para píxeles reales (es decir, **no enmascarados**), - 0 para píxeles de relleno (es decir, **enmascarados**).  [¿Qué son las máscaras de atención?](../glossary#attention-mask)

encoder_outputs (`torch.Tensor`, *opcional*) : Tupla compuesta por (`last_hidden_state`, *opcional*: `hidden_states`, *opcional*: `attentions`) `last_hidden_state` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) es una secuencia de estados ocultos en la salida de la última capa del codificador. Se utiliza en la atención cruzada del decodificador.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, en lugar de pasar el mapa de características aplanado (salida del backbone + capa de proyección), puede elegir pasar directamente una representación aplanada de una imagen.

labels (`list[Dict]` de longitud `(batch_size,)`, *opcional*) : Etiquetas para calcular la pérdida de bipartite matching. Lista de diccionarios, donde cada diccionario contiene al menos las siguientes 2 claves: 'class_labels' y 'boxes' (las etiquetas de clase y las cajas delimitadoras de una imagen en el lote, respectivamente). Las propias etiquetas de clase deben ser un `torch.LongTensor` de longitud `(number of bounding boxes in the image,)` y las cajas un `torch.Tensor` de forma `(number of bounding boxes in the image, 4)`.

**Devuelve:** `DFineModelOutput` o `tuple(torch.Tensor)`

Un `DFineModelOutput` o una tupla de `torch.Tensor` (si se pasa `return_dict=False` o cuando `config.return_dict=False`) que comprende varios elementos según la configuración (`None`) y las entradas.

El método forward de [DFineModel](/docs/transformers/v5.23.0/es/model_doc/d_fine#transformers.DFineModel) sobrescribe el método especial `__call__`.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de `Module` después, en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de preprocesamiento y posprocesamiento, mientras que la segunda los ignora silenciosamente.

- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, num_queries, hidden_size)`) -- Secuencia de estados ocultos en la salida de la última capa del decodificador del modelo.
- **intermediate_hidden_states** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, hidden_size)`) -- Estados ocultos intermedios apilados (salida de cada capa del decodificador).
- **intermediate_logits** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, sequence_length, config.num_labels)`) -- Logits intermedios apilados (logits de cada capa del decodificador).
- **intermediate_reference_points** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, 4)`) -- Puntos de referencia intermedios apilados (puntos de referencia de cada capa del decodificador).
- **intermediate_predicted_corners** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, 4)`) -- Esquinas intermedias predichas apiladas (esquinas predichas de cada capa del decodificador).
- **initial_reference_points** (`torch.Tensor` de forma `(batch_size, num_queries, 4)`) -- Puntos de referencia iniciales utilizados para la primera capa del decodificador.
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *opcional*, se devuelve cuando se pasa `output_hidden_states=True` o cuando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (una para la salida de los embeddings, si el modelo tiene una capa de embedding, + una para la salida de cada capa) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos del decodificador en la salida de cada capa más las salidas de la incrustación inicial.
- **decoder_attentions** (`tuple[torch.Tensor]`, *opcional*, se devuelve cuando se pasa `output_attentions=True` o cuando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (una por cada capa) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atención del decodificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
- **cross_attentions** (`tuple[torch.Tensor]`, *opcional*, se devuelve cuando se pasa `output_attentions=True` o cuando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (una por cada capa) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atención de la capa de atención cruzada del decodificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de atención cruzada.
- **encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Secuencia de estados ocultos en la salida de la última capa del codificador del modelo.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *opcional*, se devuelve cuando se pasa `output_hidden_states=True` o cuando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos del codificador en la salida de cada capa más las salidas de la incrustación inicial.
- **encoder_attentions** (`tuple[torch.Tensor]`, *opcional*, se devuelve cuando se pasa `output_attentions=True` o cuando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (una por cada capa) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atención del codificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
- **init_reference_points** (`torch.Tensor` de forma `(batch_size, num_queries, 4)`) -- Puntos de referencia iniciales enviados a través del decodificador Transformer.
- **enc_topk_logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.num_labels)`) -- Puntuaciones de las cajas delimitadoras predichas, donde las cajas delimitadoras con las `config.two_stage_num_proposals` puntuaciones más altas se seleccionan como propuestas de región en la etapa del codificador. Salida de la clasificación binaria de cajas delimitadoras (es decir, primer plano y fondo).
- **enc_topk_bboxes** (`torch.Tensor` de forma `(batch_size, sequence_length, 4)`) -- Logits de las coordenadas de las cajas delimitadoras predichas en la etapa del codificador.
- **enc_outputs_class** (`torch.Tensor` de forma `(batch_size, sequence_length, config.num_labels)`, *opcional*, devuelto cuando `config.with_box_refine=True` y `config.two_stage=True`) -- Puntuaciones de las cajas delimitadoras predichas, donde las `config.two_stage_num_proposals` cajas delimitadoras con mayor puntuación se seleccionan como propuestas de región en la primera etapa. Salida de la clasificación binaria de cajas delimitadoras (es decir, primer plano y fondo).
- **enc_outputs_coord_logits** (`torch.Tensor` de forma `(batch_size, sequence_length, 4)`, *opcional*, se devuelve cuando `config.with_box_refine=True` y `config.two_stage=True`) -- Logits de las coordenadas de las cajas delimitadoras predichas en la primera etapa.
- **denoising_meta_values** (`dict`, *opcional*) -- Diccionario adicional para los valores relacionados con el denoising.

Ejemplos:

```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)
```

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

**Parámetros:**

config ([DFineConfig](/docs/transformers/v5.23.0/es/model_doc/d_fine#transformers.DFineConfig)) : Clase de configuración del modelo con todos los parámetros del modelo. Inicializar con un archivo de configuración no carga los pesos asociados con el modelo, solo la configuración. Consulte el método [from_pretrained()](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) para cargar los pesos del modelo.

Modelo RT-DETR (constituido por un backbone y un encoder-decoder) que genera bounding boxes y logits para ser decodificados posteriormente en scores y clases.

Este modelo hereda de [PreTrainedModel](/docs/transformers/v5.23.0/es/main_classes/model#transformers.PreTrainedModel). Consulte la documentación de la clase superior para los métodos genéricos que la biblioteca implementa para todos sus modelos (como la descarga o el guardado, el redimensionamiento de las incrustaciones de entrada, la poda de cabezas, etc.).

Este modelo también es una subclase de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Úsalo como un módulo de PyTorch regular y consulta la documentación de PyTorch para todo lo relacionado con el uso y el comportamiento generales.

#### 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'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/v5.23.0/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)`) : Los tensores correspondientes a las imágenes de entrada. Los valores de píxeles se pueden obtener mediante `image_processor_class`. Consulte `image_processor_class.__call__` para más detalles (`processor_class` utiliza `image_processor_class` para procesar las imágenes).

pixel_mask (`torch.LongTensor` de forma `(batch_size, height, width)`, *opcional*) : Máscara para evitar realizar atención sobre los valores de píxeles de relleno. Valores de la máscara seleccionados en `[0, 1]`:  - 1 para píxeles reales (es decir, **no enmascarados**), - 0 para píxeles de relleno (es decir, **enmascarados**).  [¿Qué son las máscaras de atención?](../glossary#attention-mask)

encoder_outputs (`torch.Tensor`, *opcional*) : Tupla compuesta por (`last_hidden_state`, *opcional*: `hidden_states`, *opcional*: `attentions`) `last_hidden_state` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) es una secuencia de estados ocultos en la salida de la última capa del codificador. Se utiliza en la atención cruzada del decodificador.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, en lugar de pasar `input_ids`, puedes elegir pasar directamente una representación incrustada. Esto es útil si deseas tener más control sobre cómo convertir los índices de `input_ids` en los vectores asociados que en la matriz de búsqueda de incrustaciones interna del modelo.

labels (`list[Dict]` de longitud `(batch_size,)`, *opcional*) : Etiquetas para calcular la pérdida de bipartite matching. Lista de diccionarios, donde cada diccionario contiene al menos las siguientes 2 claves: 'class_labels' y 'boxes' (las etiquetas de clase y las cajas delimitadoras de una imagen en el lote, respectivamente). Las propias etiquetas de clase deben ser un `torch.LongTensor` de longitud `(number of bounding boxes in the image,)` y las cajas un `torch.Tensor` de forma `(number of bounding boxes in the image, 4)`.

**Devuelve:** `DFineObjectDetectionOutput` o `tuple(torch.Tensor)`

Un `DFineObjectDetectionOutput` o una tupla de `torch.Tensor` (si se pasa `return_dict=False` o cuando `config.return_dict=False`) que comprende varios elementos según la configuración (`None`) y las entradas.

El método forward de [DFineForObjectDetection](/docs/transformers/v5.23.0/es/model_doc/d_fine#transformers.DFineForObjectDetection) sobrescribe el método especial `__call__`.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de `Module` después, en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de preprocesamiento y posprocesamiento, mientras que la segunda los ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, devuelta cuando se proporcionan `labels`) -- Pérdida total como combinación lineal de una log-verosimilitud negativa (entropía cruzada) para la predicción de clases y una pérdida de caja delimitadora. Esta última se define como una combinación lineal de la pérdida L1 y la pérdida de IoU generalizada e invariante a la escala.
- **loss_dict** (`Dict`, *opcional*) -- Un diccionario que contiene las pérdidas individuales. Útil para el registro.
- **logits** (`torch.Tensor` de forma `(batch_size, num_queries, num_classes + 1)`) -- Logits de clasificación (incluyendo no-objeto) para todas las consultas.
- **pred_boxes** (`torch.Tensor` de forma `(batch_size, num_queries, 4)`) -- Coordenadas de cajas normalizadas para todas las consultas, representadas como (center_x, center_y, width, height). Estos valores están normalizados en [0, 1], relativos al tamaño de cada imagen individual del lote (ignorando el posible relleno). Puede usar `~DFineImageProcessor.post_process_object_detection` para obtener las cajas delimitadoras no normalizadas (absolutas).
- **auxiliary_outputs** (`list[Dict]`, *opcional*) -- Opcional, solo se devuelve cuando se activan las pérdidas auxiliares (es decir, `config.auxiliary_loss` está establecido en `True`) y se proporcionan etiquetas. Es una lista de diccionarios que contienen las dos claves anteriores (`logits` y `pred_boxes`) para cada capa del decodificador.
- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, num_queries, hidden_size)`) -- Secuencia de estados ocultos en la salida de la última capa del decodificador del modelo.
- **intermediate_hidden_states** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, hidden_size)`) -- Estados ocultos intermedios apilados (salida de cada capa del decodificador).
- **intermediate_logits** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, config.num_labels)`) -- Logits intermedios apilados (logits de cada capa del decodificador).
- **intermediate_reference_points** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, 4)`) -- Puntos de referencia intermedios apilados (puntos de referencia de cada capa del decodificador).
- **intermediate_predicted_corners** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, 4)`) -- Esquinas intermedias predichas apiladas (esquinas predichas de cada capa del decodificador).
- **initial_reference_points** (`torch.Tensor` de forma `(batch_size, config.decoder_layers, num_queries, 4)`) -- Puntos de referencia iniciales apilados (puntos de referencia iniciales de cada capa del decodificador).
- **decoder_hidden_states** (`tuple[torch.Tensor]`, *opcional*, se devuelve cuando se pasa `output_hidden_states=True` o cuando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (una para la salida de los embeddings, si el modelo tiene una capa de embedding, + una para la salida de cada capa) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos del decodificador en la salida de cada capa más las salidas de la incrustación inicial.
- **decoder_attentions** (`tuple[torch.Tensor]`, *opcional*, se devuelve cuando se pasa `output_attentions=True` o cuando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (una por cada capa) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atención del decodificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
- **cross_attentions** (`tuple[torch.Tensor]`, *opcional*, se devuelve cuando se pasa `output_attentions=True` o cuando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (una por cada capa) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atención de la capa de atención cruzada del decodificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de atención cruzada.
- **encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Secuencia de estados ocultos en la salida de la última capa del codificador del modelo.
- **encoder_hidden_states** (`tuple[torch.Tensor]`, *opcional*, se devuelve cuando se pasa `output_hidden_states=True` o cuando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos del codificador en la salida de cada capa más las salidas de la incrustación inicial.
- **encoder_attentions** (`tuple[torch.Tensor]`, *opcional*, se devuelve cuando se pasa `output_attentions=True` o cuando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (una por cada capa) de forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atención del codificador, después del softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.
- **init_reference_points** (`torch.Tensor` de forma  `(batch_size, num_queries, 4)`) -- Puntos de referencia iniciales enviados a través del decodificador Transformer.
- **enc_topk_logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.num_labels)`, *opcional*, se devuelve cuando `config.with_box_refine=True` y `config.two_stage=True`) -- Logits de las coordenadas de las cajas delimitadoras predichas en el codificador.
- **enc_topk_bboxes** (`torch.Tensor` de forma `(batch_size, sequence_length, 4)`, *opcional*, devuelto cuando `config.with_box_refine=True` y `config.two_stage=True`) -- Logits de las coordenadas de las cajas delimitadoras predichas en el codificador.
- **enc_outputs_class** (`torch.Tensor` de forma `(batch_size, sequence_length, config.num_labels)`, *opcional*, devuelto cuando `config.with_box_refine=True` y `config.two_stage=True`) -- Puntuaciones de las cajas delimitadoras predichas, donde las `config.two_stage_num_proposals` cajas delimitadoras con mayor puntuación se seleccionan como propuestas de región en la primera etapa. Salida de la clasificación binaria de cajas delimitadoras (es decir, primer plano y fondo).
- **enc_outputs_coord_logits** (`torch.Tensor` de forma `(batch_size, sequence_length, 4)`, *opcional*, se devuelve cuando `config.with_box_refine=True` y `config.two_stage=True`) -- Logits de las coordenadas de las cajas delimitadoras predichas en la primera etapa.
- **denoising_meta_values** (`dict`, *opcional*) -- Diccionario adicional para los valores relacionados con el desruido

Ejemplo:

```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]
```

