Hugging Face's logo

Transformers documentation

EoMT-DINOv3

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo foi publicado no HF papers em 2025-03-24 e contribuído para o Hugging Face Transformers em 2026-02-02.

EoMT-DINOv3

SDPA

Visão geral

A família EoMT-DINOv3 estende a arquitetura Encoder-only Mask Transformer com Vision Transformers pré-treinados usando 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 opcionais 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ótica, conforme destacado no DINOv3 model zoo.

A arquitetura original do EoMT foi introduzida no paper Highlight da CVPR 2025 Your ViT is Secretly an Image Segmentation Model, 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 o mesmo segmentation head 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 é possível fornecer tamanhos personalizados 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 descrevem esse fluxo de trabalho em detalhes.

Este modelo foi contribuído por nielsr. O código original pode ser encontrado aqui.

Exemplos de uso

Abaixo está 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.

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

classe transformers.EomtDinov3Config

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonehidden_size: int = 1024num_hidden_layers: int = 24num_attention_heads: int = 16hidden_act: str = 'gelu'hidden_dropout_prob: float | int = 0.0initializer_range: float = 0.02layer_norm_eps: float = 1e-06image_size: int | list[int] | tuple[int, int] = 640patch_size: int | list[int] | tuple[int, int] = 16num_channels: int = 3layerscale_value: float = 1.0drop_path_rate: float | int = 0.0num_upscale_blocks: int = 2attention_dropout: float | int = 0.0num_blocks: int = 4no_object_weight: float = 0.1class_weight: float = 2.0mask_weight: float = 5.0dice_weight: float = 5.0train_num_points: int = 12544oversample_ratio: float = 3.0importance_sample_ratio: float = 0.75num_queries: int = 200num_register_tokens: int = 4intermediate_size: int = 4096rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Nonequery_bias: bool = Truekey_bias: bool = Falsevalue_bias: bool = Trueproj_bias: bool = Truemlp_bias: bool = Trueuse_gated_mlp: bool = Falsepos_embed_shift: float | None = Nonepos_embed_jitter: float | None = Nonepos_embed_rescale: float | None = 2.0 )

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 ampliação 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 “no object” em segmentação panotópica/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 sobreamostragem 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 serem amostrados com base na importância durante o treinamento.
  • num_queries (int, opcional, padrão 200) — Número de consultas de objetos 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 da query.
  • key_bias (bool, opcional, padrão False) — Indica se deve ser usado viés na projeção da chave.
  • value_bias (bool, opcional, padrão True) — Indica se deve ser usado viés na projeção de valor.
  • proj_bias (bool, opcional, padrão True) — Indica se deve ser usado 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 os 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

Os objetos de configuração herdam de PreTrainedConfig e podem ser usados para controlar as saídas do modelo. Consulte a documentação de PreTrainedConfig para mais informações.

EomtDinov3PreTrainedModel

classe transformers.EomtDinov3PreTrainedModel

< >

( config: PreTrainedConfig*inputs**kwargs )

Parâmetros

  • config (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() para carregar os pesos do modelo.

Este modelo herda de 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 do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

( *args**kwargs )

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

EomtDinov3ForUniversalSegmentation

classe transformers.EomtDinov3ForUniversalSegmentation

< >

( config: EomtDinov3Config )

Parâmetros

  • config (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() 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. 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 do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso geral e ao comportamento.

forward

< >

( pixel_values: Tensormask_labels: list[torch.Tensor] | None = Noneclass_labels: list[torch.Tensor] | None = Nonepatch_offsets: list[torch.Tensor] | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → EomtDinov3ForUniversalSegmentationOutput or tuple(torch.Tensor)

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. Consulte EomtImageProcessor.call() para mais detalhes (processor_class usa EomtImageProcessor para processar as 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 classe 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) e das entradas.

O método forward de 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) de forma (batch_size, sequence_length, hidden_size). Hidden-states 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.
Update on GitHub

←EoMT FocalNet→