# EoMT-DINOv3

  

## Visão geral

A família **EoMT-DINOv3** estende a arquitetura [Encoder-only Mask Transformer](eomt) com Vision Transformers pré-treinados usando [DINOv3](dinov3). A atualização oferece uma qualidade de segmentação superior nos benchmarks ADE20K e COCO, preservando o design encoder-only que tornou o EoMT atrativo para aplicações em tempo real.

Em comparação com os modelos baseados em DINOv2, as variantes do DINOv3 utilizam embeddings de posição rotativos, blocos MLP com gate opcional e as receitas de pré-treino mais recentes da Meta AI. Essas mudanças resultam em ganhos de desempenho mensuráveis em tarefas de segmentação semântica, de instância e panóptica, conforme destacado no [DINOv3 model zoo](https://github.com/tue-mps/eomt/blob/master/model_zoo/dinov3.md).

A arquitetura original do EoMT foi introduzida no paper Highlight da 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 e Daan de Geus. A atualização para DINOv3 mantém a mesma head de segmentação leve e a estratégia de inferência baseada em queries, substituindo o encoder por checkpoints ViT do DINOv3.

Dicas:

* A configuração expõe parâmetros específicos do DINOv3, como `rope_theta` e `use_gated_mlp`. Backbones grandes do DINOv3, como `dinov3-vitg14`, esperam `use_gated_mlp=True`.
* Os modelos DINOv3 podem operar em uma faixa mais ampla de resoluções graças aos embeddings de posição rotativos. O processador de imagem ainda usa recortes quadrados por padrão, mas tamanhos personalizados podem ser fornecidos por meio de `AutoImageProcessor`.
* Os checkpoints pré-treinados hospedados pelo TU/e Mobile Perception Systems Lab fornecem pesos delta que devem ser combinados com os backbones upstream do DINOv3. As utilitários de conversão no [repositório oficial](https://github.com/tue-mps/eomt) descrevem esse fluxo de trabalho em detalhes.

Este modelo foi contribuído por [nielsr](https://huggingface.co/nielsr). O código original pode ser encontrado [aqui](https://github.com/tue-mps/eomt).

## Exemplos de uso

Abaixo, há um exemplo mínimo mostrando como executar segmentação panótica com um modelo EoMT baseado em DINOv3. O mesmo processador de imagem pode ser reutilizado para segmentação semântica ou de instâncias, basta trocar o checkpoint.

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

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

**Parâmetros:**

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

num_hidden_layers (`int`, *opcional*, padrão `24`) : Número de camadas ocultas no decodificador do Transformer.

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

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

hidden_dropout_prob (`Union[float, int]`, *opcional*, padrão `0.0`) : A probabilidade de dropout para todas as camadas totalmente conectadas nos embeddings, no encoder e no pooler.

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

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

image_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, padrão `640`) : O tamanho (resolução) de cada imagem.

patch_size (`Union[int, list[int], tuple[int, int]]`, *opcional*, padrão `16`) : O tamanho (resolução) de cada patch.

num_channels (`int`, *opcional*, padrão `3`) : O número de canais de entrada.

layerscale_value (`float`, *opcional*, padrão 1.0) : Valor inicial para o parâmetro LayerScale.

drop_path_rate (`Union[float, int]`, *opcional*, padrão `0.0`) : Taxa de drop path para a fusão de patches.

num_upscale_blocks (`int`, *opcional*, padrão 2) : Número de blocos de amostragem ascendente usados no decodificador ou na cabeça de segmentação.

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

num_blocks (`int`, *opcional*, padrão 4) : Número de blocos de recursos ou estágios na arquitetura.

no_object_weight (`float`, *opcional*, padrão 0.1) : Peso da perda para a classe "sem objeto" em segmentação panótica/por instância.

class_weight (`float`, *opcional*, padrão `2.0`) : Peso relativo do erro de classificação no custo de correspondência húngara.

mask_weight (`float`, *opcional*, padrão `5.0`) : Peso relativo da focal loss na perda de segmentação panótica.

dice_weight (`float`, *opcional*, padrão `5.0`) : Peso relativo da perda dice na perda de segmentação panótica.

train_num_points (`int`, *opcional*, padrão 12544) : Número de pontos a amostrar para o cálculo da perda de máscara durante o treinamento.

oversample_ratio (`float`, *opcional*, padrão 3.0) : Razão de oversampling usada na amostragem de pontos para o treinamento de máscaras.

importance_sample_ratio (`float`, *opcional*, padrão 0.75) : Proporção de pontos a amostrar com base na importância durante o treinamento.

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

num_register_tokens (`int`, *opcional*, padrão 4) : Número de tokens de registro aprendíveis adicionados à entrada do transformer.

intermediate_size (`int`, *opcional*, padrão `4096`) : Dimensão das representações do MLP.

rope_parameters (`Union[~modeling_rope_utils.RopeParameters, dict]`, *opcional*) : Dicionário contendo os parâmetros de configuração para os embeddings RoPE. O dicionário deve conter um valor para `rope_theta` e, opcionalmente, parâmetros usados para escalonamento, caso você queira usar RoPE com `max_position_embeddings` maiores.

query_bias (`bool`, *opcional*, padrão `True`) : Se deve usar viés na projeção de consulta.

key_bias (`bool`, *opcional*, padrão `False`) : Se deve usar viés na projeção de chave.

value_bias (`bool`, *opcional*, padrão `True`) : Se deve usar viés na projeção de valor.

proj_bias (`bool`, *opcional*, padrão `True`) : Se deve usar viés na projeção de saída.

mlp_bias (`bool`, *opcional*, padrão `True`) : Se deve usar um viés nas camadas up_proj, down_proj e gate_proj das camadas MLP.

use_gated_mlp (`bool`, *opcional*, padrão `False`) : Se deve usar camadas de MLP com gate.

pos_embed_shift (`float`, *opcional*) : Valor de deslocamento para embeddings de posição.

pos_embed_jitter (`float`, *opcional*) : Valor de jitter para embeddings de posição.

pos_embed_rescale (`float`, *opcional*, padrão 2.0) : Valor de reescala para embeddings de posição.

Esta é a classe de configuração para armazenar a configuração de um Eomt Dinov3Model. Ela é usada para instanciar um modelo Eomt Dinov3 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 [tue-mps/coco_panoptic_eomt_large_640_dinov3](https://huggingface.co/tue-mps/coco_panoptic_eomt_large_640_dinov3)

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.

## EomtDinov3PreTrainedModel[[transformers.EomtDinov3PreTrainedModel]]

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

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

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

**Parâmetros:**

config ([PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig)) : 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.

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.EomtDinov3PreTrainedModel.forward]]

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

Um valor simulado para um caminho pontilhado (por exemplo, `torch.float32`): as cadeias de acesso a atributos e as chamadas se comportam como decoradores de passagem, o `repr` é o caminho pontilhado, e o uso como classe base substitui uma base de `type` simples (PEP 560 `__mro_entries__`), de modo que as subclasses reais mantêm um metaclass normal e o `inspect.signature` lê o `__init__` real delas, em vez do de um mock.

## EomtDinov3ForUniversalSegmentation[[transformers.EomtDinov3ForUniversalSegmentation]]

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

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

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

**Parâmetros:**

config ([EomtDinov3Config](/docs/transformers/main/pt/model_doc/eomt_dinov3#transformers.EomtDinov3Config)) : 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.

O modelo EoMT-DINOv3 com head no topo para segmentação de instância/semântica/panóptica.

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

[Origem](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)`) : Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando [EomtImageProcessor](/docs/transformers/main/pt/model_doc/eomt#transformers.EomtImageProcessor). Consulte [EomtImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para obter detalhes (`processor_class` usa [EomtImageProcessor](/docs/transformers/main/pt/model_doc/eomt#transformers.EomtImageProcessor) para processar imagens).

mask_labels (`list[torch.Tensor]`, *opcional*) : lista de rótulos de máscara com forma `(num_labels, height, width)` para ser fornecida a um modelo

class_labels (`list[torch.LongTensor]`, *opcional*) : lista de rótulos de classes alvo com formato `(num_labels, height, width)` para ser fornecida a um modelo. Eles identificam os rótulos de `mask_labels`, por exemplo, o rótulo de `mask_labels[i][j]` se `class_labels[i][j]`.

patch_offsets (`list[torch.Tensor]`, *opcional*) : lista de tuplas indicando o índice da imagem e as posições de início e fim dos patches para segmentação semântica.

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

Um `EomtDinov3ForUniversalSegmentationOutput` 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 ([EomtDinov3Config](/docs/transformers/main/pt/model_doc/eomt_dinov3#transformers.EomtDinov3Config)) e das entradas.

O método forward de [EomtDinov3ForUniversalSegmentation](/docs/transformers/main/pt/model_doc/eomt_dinov3#transformers.EomtDinov3ForUniversalSegmentation) 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`, *opcional*) -- A perda calculada, retornada quando os rótulos estão presentes.
- **class_queries_logits** (`torch.Tensor`, *opcional*) -- Um tensor de forma `(batch_size, num_queries, num_labels + 1)` representando as classes propostas para cada query. Observe que o `+ 1` é necessário porque incorporamos a classe nula.
- **masks_queries_logits** (`torch.Tensor`, *opcional*) -- Um tensor de forma `(batch_size, num_queries, height, width)` representando as máscaras propostas para cada consulta.
- **last_hidden_state** (`torch.Tensor` de forma `(batch_size, num_channels, height, width)`) -- Últimos estados ocultos (mapa de recursos final) da última camada.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings + um para a saída de cada estágio) com forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos de todas as camadas do modelo.
- **attentions** (`tuple(tuple(torch.Tensor))`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `tuple(torch.Tensor)` (uma para cada camada) com forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de Self e Cross Attentions do decodificador do transformer.
- **patch_offsets** (`list[torch.Tensor]`, *opcional*) -- lista de tuplas indicando o índice da imagem e as posições de início e fim dos patches para segmentação semântica.