# EoMT-DINOv3

  

## Resumen

La familia **EoMT-DINOv3** extiende la arquitectura [Encoder-only Mask Transformer](eomt) con Vision Transformers preentrenados mediante [DINOv3](dinov3). Esta actualización ofrece una mayor calidad de segmentación en los benchmarks ADE20K y COCO, al tiempo que conserva el diseño solo de codificador que hizo que EoMT fuera atractivo para aplicaciones en tiempo real.

En comparación con los modelos basados en DINOv2, las variantes de DINOv3 aprovechan los embeddings de posición rotatorios, los bloques MLP con compuerta opcionales y las últimas recetas de preentrenamiento de Meta AI. Estos cambios generan mejoras de rendimiento medibles en tareas de segmentación semántica, de instancias y panóptica, como se destaca en el [DINOv3 model zoo](https://github.com/tue-mps/eomt/blob/master/model_zoo/dinov3.md).

La arquitectura original de EoMT se presentó en el artículo destacado de CVPR 2025 *[Your ViT is Secretly an Image Segmentation Model](https://huggingface.co/papers/2503.19108)*, de Tommie Kerssies, Niccolò Cavagnero, Alexander Hermans, Narges Norouzi, Giuseppe Averta, Bastian Leibe, Gijs Dubbelman y Daan de Geus. La actualización a DINOv3 mantiene la misma cabeza de segmentación ligera y la estrategia de inferencia basada en consultas, pero reemplaza el codificador por puntos de control de ViT de DINOv3.

Consejos:

* La configuración expone parámetros específicos de DINOv3, como `rope_theta` y `use_gated_mlp`. Los backbones grandes de DINOv3, como `dinov3-vitg14`, esperan `use_gated_mlp=True`.
* Los modelos DINOv3 pueden funcionar con un rango más amplio de resoluciones gracias a los embeddings de posición rotatorios. El procesador de imágenes sigue usando recortes cuadrados por defecto, pero se pueden especificar tamaños personalizados a través de `AutoImageProcessor`.
* Los puntos de control preentrenados alojados por el TU/e Mobile Perception Systems Lab proporcionan pesos delta que deben combinarse con los backbones de DINOv3 de origen. Las utilidades de conversión del [repositorio oficial](https://github.com/tue-mps/eomt) describen este flujo de trabajo en detalle.

Este modelo fue aportado por [nielsr](https://huggingface.co/nielsr). El código original se puede encontrar [aquí](https://github.com/tue-mps/eomt).

## Ejemplos de uso

A continuación se muestra un ejemplo mínimo que ilustra cómo ejecutar la segmentación panóptica con un modelo EoMT basado en DINOv3. El mismo procesador de imágenes se puede reutilizar para la segmentación semántica o de instancias simplemente cambiando el punto de control.

```python
import requests
import torch
from PIL import Image

from transformers import AutoImageProcessor, AutoModelForUniversalSegmentation

model_id = "tue-mps/eomt-dinov3-coco-panoptic-base-640"
processor = AutoImageProcessor.from_pretrained(model_id)
model = AutoModelForUniversalSegmentation.from_pretrained(model_id, device_map="auto")

image = Image.open(requests.get("http://images.cocodataset.org/val2017/000000039769.jpg", stream=True).raw)

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

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

segmentation = processor.post_process_panoptic_segmentation(outputs, target_sizes=[image.size[::-1]])[0]
list(segmentation.keys())
['segmentation', 'segments_info']
```

## EomtDinov3Config[[transformers.EomtDinov3Config]]

#### transformers.EomtDinov3Config[[transformers.EomtDinov3Config]]

```python
transformers.EomtDinov3Config(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, is_encoder_decoder: bool = False, 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, hidden_size: int = 1024, num_hidden_layers: int = 24, num_attention_heads: int = 16, hidden_act: str = 'gelu', hidden_dropout_prob: float | int = 0.0, initializer_range: float = 0.02, layer_norm_eps: float = 1e-06, image_size: int | list[int] | tuple[int, int] = 640, patch_size: int | list[int] | tuple[int, int] = 16, num_channels: int = 3, layerscale_value: float = 1.0, drop_path_rate: float | int = 0.0, num_upscale_blocks: int = 2, attention_dropout: float | int = 0.0, num_blocks: int = 4, no_object_weight: float = 0.1, class_weight: float = 2.0, mask_weight: float = 5.0, dice_weight: float = 5.0, train_num_points: int = 12544, oversample_ratio: float = 3.0, importance_sample_ratio: float = 0.75, num_queries: int = 200, num_register_tokens: int = 4, intermediate_size: int = 4096, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, query_bias: bool = True, key_bias: bool = False, value_bias: bool = True, proj_bias: bool = True, mlp_bias: bool = True, use_gated_mlp: bool = False, pos_embed_shift: float | None = None, pos_embed_jitter: float | None = None, pos_embed_rescale: float | None = 2.0)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/eomt_dinov3/configuration_eomt_dinov3.py#L29)

**Parámetros:**

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

num_hidden_layers (`int`, *opcional*, valor predeterminado `24`) : Número de capas ocultas en el decodificador del Transformer.

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

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

hidden_dropout_prob (`Union[float, int]`, *opcional*, valor predeterminado `0.0`) : La probabilidad de dropout para todas las capas completamente conectadas en los embeddings, el codificador y el pooler.

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

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

image_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, valor predeterminado `640`) : El tamaño (resolución) de cada imagen.

patch_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, valor predeterminado `16`) : El tamaño (resolución) de cada parche.

num_channels (`int`, *opcional*, valor predeterminado `3`) : El número de canales de entrada.

layerscale_value (`float`, *opcional*, valor predeterminado 1.0) : Valor inicial para el parámetro LayerScale.

drop_path_rate (`Union[float, int]`, *opcional*, valor predeterminado `0.0`) : Tasa de drop path para la fusión de parches.

num_upscale_blocks (`int`, *opcional*, valor predeterminado 2) : Número de bloques de remuestreo ascendente utilizados en el decodificador o la cabeza de segmentación.

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

num_blocks (`int`, *opcional*, valor predeterminado 4) : Número de bloques de características o etapas en la arquitectura.

no_object_weight (`float`, *opcional*, valor predeterminado 0.1) : Peso de la pérdida para la clase "no object" en la segmentación panoptica/por instancia.

class_weight (`float`, *opcional*, valor predeterminado `2.0`) : Peso relativo del error de clasificación en el coste de correspondencia húngara.

mask_weight (`float`, *opcional*, valor predeterminado `5.0`) : Peso relativo de la focal loss en la pérdida de segmentación panóptica.

dice_weight (`float`, *opcional*, valor predeterminado `5.0`) : Peso relativo de la pérdida dice en la pérdida de segmentación panóptica.

train_num_points (`int`, *opcional*, valor predeterminado 12544) : Número de puntos a muestrear para el cálculo de la pérdida de máscara durante el entrenamiento.

oversample_ratio (`float`, *opcional*, valor predeterminado 3.0) : Relación de sobremuestreo utilizada en el muestreo de puntos para el entrenamiento de máscaras.

importance_sample_ratio (`float`, *opcional*, valor predeterminado 0.75) : Proporción de puntos a muestrear en función de la importancia durante el entrenamiento.

num_queries (`int`, *opcional*, valor predeterminado 200) : Número de consultas de objetos en el Transformer.

num_register_tokens (`int`, *opcional*, valor predeterminado: 4) : Número de tokens de registro aprendibles añadidos a la entrada del transformer.

intermediate_size (`int`, *opcional*, valor predeterminado `4096`) : Dimensión de las representaciones MLP.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *opcional*) : Diccionario que contiene los parámetros de configuración para las incrustaciones RoPE. El diccionario debe contener un valor para `rope_theta` y, opcionalmente, parámetros utilizados para el escalado en caso de que desee usar RoPE con `max_position_embeddings` más largas.

query_bias (`bool`, *opcional*, valor predeterminado `True`) : Si se usa sesgo en la proyección de consulta.

key_bias (`bool`, *opcional*, valor predeterminado `False`) : Si se usa sesgo en la proyección de claves.

value_bias (`bool`, *opcional*, valor predeterminado `True`) : Si se usa sesgo en la proyección de valor.

proj_bias (`bool`, *opcional*, valor predeterminado `True`) : Si se usa sesgo en la proyección de salida.

mlp_bias (`bool`, *opcional*, valor predeterminado `True`) : Indica si se debe usar un sesgo en las capas up_proj, down_proj y gate_proj de las capas MLP.

use_gated_mlp (`bool`, *opcional*, valor predeterminado `False`) : Si se deben usar capas MLP con compuerta.

pos_embed_shift (`float`, *opcional*) : Valor de desplazamiento para las incrustaciones de posición.

pos_embed_jitter (`float`, *opcional*) : Valor de jitter para los embeddings de posición.

pos_embed_rescale (`float`, *opcional*, valor predeterminado 2.0) : Valor de reescalado para los embeddings de posición.

Esta es la clase de configuración para almacenar la configuración de un Eomt Dinov3Model. Se utiliza para instanciar un modelo Eomt Dinov3 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 [tue-mps/coco_panoptic_eomt_large_640_dinov3](https://huggingface.co/tue-mps/coco_panoptic_eomt_large_640_dinov3)

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

## EomtDinov3PreTrainedModel[[transformers.EomtDinov3PreTrainedModel]]

#### transformers.EomtDinov3PreTrainedModel[[transformers.EomtDinov3PreTrainedModel]]

```python
transformers.EomtDinov3PreTrainedModel(config: PreTrainedConfig, *inputs, **kwargs)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/eomt_dinov3/modeling_eomt_dinov3.py#L1061)

**Parámetros:**

config ([PreTrainedConfig](/docs/transformers/main/es/main_classes/configuration#transformers.PreTrainedConfig)) : 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/main/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) para cargar los pesos del modelo.

Este modelo hereda de [PreTrainedModel](/docs/transformers/main/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.EomtDinov3PreTrainedModel.forward]]

```python
forward(*args, **kwargs)
```

Un valor simulado para una ruta con puntos (p. ej., `torch.float32`): las cadenas de acceso a atributos y las llamadas se comportan como decoradores de paso, `repr` es la ruta con puntos, y su uso como clase base sustituye una base de `type` simple (PEP 560 `__mro_entries__`), de modo que las subclases reales conservan un metaclass normal y `inspect.signature` lee su `__init__` real en lugar del de un simulacro.

## EomtDinov3ForUniversalSegmentation[[transformers.EomtDinov3ForUniversalSegmentation]]

#### transformers.EomtDinov3ForUniversalSegmentation[[transformers.EomtDinov3ForUniversalSegmentation]]

```python
transformers.EomtDinov3ForUniversalSegmentation(config: EomtDinov3Config)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/eomt_dinov3/modeling_eomt_dinov3.py#L1167)

**Parámetros:**

config ([EomtDinov3Config](/docs/transformers/main/es/model_doc/eomt_dinov3#transformers.EomtDinov3Config)) : 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/main/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) para cargar los pesos del modelo.

El modelo EoMT-DINOv3 con cabeza superior para segmentación de instancias/semántica/panóptica.

Este modelo hereda de [PreTrainedModel](/docs/transformers/main/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.EomtDinov3ForUniversalSegmentation.forward]]

```python
forward(pixel_values: Tensor, mask_labels: list[torch.Tensor] | None = None, class_labels: list[torch.Tensor] | None = None, patch_offsets: list[torch.Tensor] | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/models/eomt_dinov3/modeling_eomt_dinov3.py#L1231)

**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 [EomtImageProcessor](/docs/transformers/main/es/model_doc/eomt#transformers.EomtImageProcessor). Consulte [EomtImageProcessor.__call__()](/docs/transformers/main/es/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para obtener más detalles (`processor_class` utiliza [EomtImageProcessor](/docs/transformers/main/es/model_doc/eomt#transformers.EomtImageProcessor) para procesar las imágenes).

mask_labels (`list[torch.Tensor]`, *opcional*) : lista de etiquetas de máscara de forma `(num_labels, height, width)` para alimentar a un modelo

class_labels (`list[torch.LongTensor]`, *opcional*) : lista de etiquetas de clase objetivo de forma `(num_labels, height, width)` para alimentar a un modelo. Identifican las etiquetas de `mask_labels`, p. ej., la etiqueta de `mask_labels[i][j]` si `class_labels[i][j]`.

patch_offsets (`list[torch.Tensor]`, *opcional*) : lista de tuplas que indican el índice de la imagen y las posiciones de inicio y fin de los parches para la segmentación semántica.

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

Un `EomtDinov3ForUniversalSegmentationOutput` 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 ([EomtDinov3Config](/docs/transformers/main/es/model_doc/eomt_dinov3#transformers.EomtDinov3Config)) y las entradas.

El método forward de [EomtDinov3ForUniversalSegmentation](/docs/transformers/main/es/model_doc/eomt_dinov3#transformers.EomtDinov3ForUniversalSegmentation) reemplaza 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`, *opcional*) -- La pérdida calculada, devuelta cuando hay etiquetas presentes.
- **class_queries_logits** (`torch.Tensor`, *opcional*) -- Un tensor de forma `(batch_size, num_queries, num_labels + 1)` que representa las clases propuestas para cada consulta. Tenga en cuenta que el `+ 1` es necesario porque incorporamos la clase nula.
- **masks_queries_logits** (`torch.Tensor`, *opcional*) -- Un tensor de forma `(batch_size, num_queries, height, width)` que representa las máscaras propuestas para cada consulta.
- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, num_channels, height, width)`) -- Últimos estados ocultos (mapa de características final) de la última capa.
- **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 + una para la salida de cada etapa) de forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos de todas las capas del modelo.
- **attentions** (`tuple(tuple(torch.Tensor))`, *opcional*, se devuelve cuando se pasa `output_attentions=True` o cuando `config.output_attentions=True`) -- Tupla de `tuple(torch.Tensor)` (una por cada capa) de forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de Self y Cross Attentions del decodificador del transformer.
- **patch_offsets** (`list[torch.Tensor]`, *opcional*) -- lista de tuplas que indican el índice de la imagen y las posiciones de inicio y fin de los parches para la segmentación semántica.