Transformers documentation

DINOv2 com Registros

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 2023-09-28 e contribuído para o Hugging Face Transformers em 2024-12-24.

DINOv2 com Registros

FlashAttention SDPA

Visão geral

O modelo DINOv2 with Registers foi proposto em Vision Transformers Need Registers por Timothée Darcet, Maxime Oquab, Julien Mairal, Piotr Bojanowski.

O Vision Transformer (ViT) é um modelo de codificador transformer (estilo BERT) originalmente introduzido para realizar classificação de imagem supervisionada no ImageNet.

Em seguida, as pessoas descobriram maneiras de fazer o ViT funcionar muito bem na extração de recursos de imagem auto-supervisionada (ou seja, o aprendizado de recursos significativos, também chamados de embeddings) em imagens sem exigir nenhum rótulo. Alguns exemplos de artigos incluem DINOv2 e MAE.

Os autores do DINOv2 notaram que os ViTs apresentam artefatos nos mapas de atenção. Isso ocorre porque o modelo utiliza alguns patches de imagem como “registros”. Os autores propõem uma correção: basta adicionar alguns tokens novos (chamados de tokens de “registro”), que são usados apenas durante o pré-treino (e descartados em seguida). Isso resulta em:

  • sem artefatos
  • mapas de atenção interpretáveis
  • e desempenho aprimorado.

O resumo do artigo é o seguinte:

Os Transformers emergiram recentemente como uma ferramenta poderosa para o aprendizado de representações visuais. Neste artigo, identificamos e caracterizamos artefatos nos mapas de características de redes ViT supervisionadas e auto-supervisionadas. Os artefatos correspondem a tokens de alta norma que surgem durante a inferência, principalmente em áreas de fundo de baixa informação nas imagens, que são reaproveitadas para cálculos internos. Propomos uma solução simples, porém eficaz, baseada no fornecimento de tokens adicionais à sequência de entrada do Vision Transformer para preencher esse papel. Demonstramos que essa solução corrige completamente o problema para modelos supervisionados e auto-supervisionados, estabelece um novo estado da arte para modelos visuais auto-supervisionados em tarefas de predição visual densa, viabiliza métodos de descoberta de objetos com modelos maiores e, mais importante, resulta em mapas de características e de atenção mais suaves para o processamento visual subsequente.

drawing Visualization of attention maps of various models trained with vs. without registers. Taken from the original paper.

Dicas:

  • O uso do DINOv2 com Registers é idêntico ao do DINOv2 sem eles; você apenas obterá um desempenho melhor.

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

Dinov2WithRegistersConfig

classe transformers.Dinov2WithRegistersConfig

< >

( 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 = 768num_hidden_layers: int = 12num_attention_heads: int = 12mlp_ratio: int = 4hidden_act: str = 'gelu'hidden_dropout_prob: float | int = 0.0attention_probs_dropout_prob: float | int = 0.0initializer_range: float = 0.02layer_norm_eps: float = 1e-06image_size: int | list[int] | tuple[int, int] = 224patch_size: int | list[int] | tuple[int, int] = 16num_channels: int = 3qkv_bias: bool = Truelayerscale_value: float = 1.0drop_path_rate: float | int = 0.0use_swiglu_ffn: bool = Falsenum_register_tokens: int = 4_out_features: list[str] | None = None_out_indices: list[int] | None = Noneapply_layernorm: bool = Truereshape_hidden_states: bool = True )

Parâmetros

  • hidden_size (int, opcional, padrão 768) — Dimensão das representações ocultas.
  • num_hidden_layers (int, opcional, padrão 12) — Número de camadas ocultas no decodificador do Transformer.
  • num_attention_heads (int, opcional, padrão 12) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.
  • mlp_ratio (int, opcional, padrão 4) — Proporção entre a dimensão oculta do MLP e a dimensão de incorporação.
  • 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.
  • attention_probs_dropout_prob (Union[float, int], opcional, padrão 0.0) — A taxa de dropout para as probabilidades de atenção.
  • 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 224) — 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.
  • qkv_bias (bool, opcional, padrão True) — Se deve adicionar um viés às queries, keys e values.
  • layerscale_value (float, opcional, padrão 1.0) — Valor inicial a ser usado para a escala da camada.
  • drop_path_rate (Union[float, int], opcional, padrão 0.0) — Taxa de drop path para a fusão de patches.
  • use_swiglu_ffn (bool, opcional, padrão False) — Se deve usar a rede neural feedforward SwiGLU.
  • num_register_tokens (int, opcional, padrão 4) — Número de tokens de registro a serem usados.
  • apply_layernorm (bool, opcional, padrão True) — Se a normalização de camada deve ser aplicada aos mapas de características caso o modelo seja usado como backbone.
  • reshape_hidden_states (bool, opcional, padrão True) — Indica se os mapas de características devem ser redimensionados para tensores 4D de forma (batch_size, hidden_size, height, width) caso o modelo seja usado como backbone. Se False, os mapas de características serão tensores 3D de forma (batch_size, seq_len, hidden_size).

Esta é a classe de configuração para armazenar a configuração de um Dinov2WithRegistersModel. Ela é usada para instanciar um modelo Dinov2 With Registers 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 facebook/dinov2-with-registers-base

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.

Exemplo:

>>> from transformers import Dinov2WithRegistersConfig, Dinov2WithRegistersModel

>>> # Initializing a Dinov2WithRegisters base style configuration
>>> configuration = Dinov2WithRegistersConfig()

>>> # Initializing a model (with random weights) from the base style configuration
>>> model = Dinov2WithRegistersModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

Dinov2WithRegistersModel

classe transformers.Dinov2WithRegistersModel

< >

( config: Dinov2WithRegistersConfig )

Parâmetros

  • config (Dinov2WithRegistersConfig) — 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 Dinov2 With Registers puro, que produz estados ocultos brutos sem nenhum cabeçalho específico no topo.

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: typing.Optional[torch.Tensor] = Nonebool_masked_pos: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPooling or tuple(torch.Tensor)

Parâmetros

  • pixel_values (torch.Tensor de forma (batch_size, num_channels, image_size, image_size), opcional) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando image_processor_class. Consulte image_processor_class.__call__ para mais detalhes (processor_class usa image_processor_class para processar as imagens).
  • bool_masked_pos (torch.BoolTensor de forma (batch_size, sequence_length)) — Posições mascaradas booleanas. Indica quais patches estão mascarados (1) e quais não estão (0). Relevante apenas para pré-treino.
  • attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
    • 1 para tokens que não estão mascarados,
    • 0 para tokens que estão mascarados.

    O que são máscaras de atenção?

Retorna

BaseModelOutputWithPooling ou tuple(torch.Tensor)

Um BaseModelOutputWithPooling 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 (Dinov2WithRegistersConfig) e das entradas.

O método forward do Dinov2WithRegistersModel sobrescreve o método especial __call__.

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

  • last_hidden_state (torch.Tensor de forma (batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.

  • pooler_output (torch.Tensor de forma (batch_size, hidden_size)) — Estado oculto da última camada do primeiro token da sequência (token de classificação) após processamento adicional através das camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para a família de modelos BERT, isso retorna o token de classificação após o processamento através de uma camada linear e uma função de ativação tanh. Os pesos da camada linear são treinados a partir do objetivo de previsão da próxima frase (classificação) durante o pré-treinamento.

  • 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, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.

  • attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

Exemplo:

Dinov2WithRegistersForImageClassification

classe transformers.Dinov2WithRegistersForImageClassification

< >

( config: Dinov2WithRegistersConfig )

Parâmetros

  • config (Dinov2WithRegistersConfig) — 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.

Modelo Dinov2WithRegisters transformer com uma cabeça de classificação de imagem no topo (uma camada linear no topo do estado oculto final do token [CLS]), por exemplo, para ImageNet.

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: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.Tensor] = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → ImageClassifierOutput or tuple(torch.Tensor)

Parâmetros

  • pixel_values (torch.Tensor de forma (batch_size, num_channels, image_size, image_size), opcional) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usando image_processor_class. Consulte image_processor_class.__call__ para mais detalhes (processor_class usa image_processor_class para processar as imagens).
  • labels (torch.LongTensor de forma (batch_size,), opcional) — Rótulos para o cálculo da perda de classificação/regressão de imagem. Os índices devem estar em [0, ..., config.num_labels - 1]. Se config.num_labels == 1, uma perda de regressão é calculada (perda de erro quadrático médio); se config.num_labels > 1, uma perda de classificação é calculada (entropia cruzada).
  • attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em [0, 1]:
    • 1 para tokens que não estão mascarados,
    • 0 para tokens que estão mascarados.

    O que são máscaras de atenção?

Retorna

ImageClassifierOutput ou tuple(torch.Tensor)

Um ImageClassifierOutput 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 (Dinov2WithRegistersConfig) e das entradas.

O método forward de Dinov2WithRegistersForImageClassification sobrescreve o método especial __call__.

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

  • loss (torch.Tensor de forma (1,), opcional, retornado quando labels é fornecido) — Perda de classificação (ou regressão se config.num_labels==1).

  • logits (torch.Tensor de forma (batch_size, config.num_labels)) — Pontuações de classificação (ou regressão, se config.num_labels==1) (antes do SoftMax).

  • 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, se o modelo tiver uma camada de embedding, + um para a saída de cada estágio) de forma (batch_size, sequence_length, hidden_size). Hidden-states (também chamados de feature maps) do modelo na saída de cada estágio.

  • attentions (tuple(torch.Tensor), opcional, retornado quando output_attentions=True é passado ou quando config.output_attentions=True) — Tupla de torch.Tensor (um para cada camada) com forma (batch_size, num_heads, patch_size, sequence_length).

    Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção.

Exemplo:

>>> from transformers import AutoImageProcessor, Dinov2WithRegistersForImageClassification
>>> import torch
>>> from datasets import load_dataset

>>> dataset = load_dataset("huggingface/cats-image")
>>> image = dataset["test"]["image"][0]

>>> image_processor = AutoImageProcessor.from_pretrained("facebook/dinov2-with-registers-base")
>>> model = Dinov2WithRegistersForImageClassification.from_pretrained("facebook/dinov2-with-registers-base")

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

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> # model predicts one of the 1000 ImageNet classes
>>> predicted_label = logits.argmax(-1).item()
>>> print(model.config.id2label[predicted_label])
...
Update on GitHub