Transformers documentation
DINOv2 com Registros
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
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.
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
< source >( 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ão768) — Dimensão das representações ocultas. - num_hidden_layers (
int, opcional, padrão12) — Número de camadas ocultas no decodificador do Transformer. - num_attention_heads (
int, opcional, padrão12) — Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer. - mlp_ratio (
int, opcional, padrão4) — Proporção entre a dimensão oculta do MLP e a dimensão de incorporação. - hidden_act (
str, opcional, padrãogelu) — 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ão0.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ão0.0) — A taxa de dropout para as probabilidades de atenção. - initializer_range (
float, opcional, padrão0.02) — O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos. - layer_norm_eps (
float, opcional, padrão1e-06) — O epsilon usado pelas camadas de normalização de camada. - image_size (
Union[int, list[int], tuple[int, int]], opcional, padrão224) — O tamanho (resolução) de cada imagem. - patch_size (
Union[int, list[int], tuple[int, int]], opcional, padrão16) — O tamanho (resolução) de cada patch. - num_channels (
int, opcional, padrão3) — O número de canais de entrada. - qkv_bias (
bool, opcional, padrãoTrue) — 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ão0.0) — Taxa de drop path para a fusão de patches. - use_swiglu_ffn (
bool, opcional, padrãoFalse) — 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ãoTrue) — 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ãoTrue) — 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. SeFalse, 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.configDinov2WithRegistersModel
classe transformers.Dinov2WithRegistersModel
< source >( 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
< source >( 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.Tensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usandoimage_processor_class. Consulteimage_processor_class.__call__para mais detalhes (processor_classusaimage_processor_classpara processar as imagens). - bool_masked_pos (
torch.BoolTensorde 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.Tensorde 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.
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
Moduleem 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.Tensorde forma(batch_size, sequence_length, hidden_size)) — Sequência de estados ocultos na saída da última camada do modelo.pooler_output (
torch.Tensorde 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 quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.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 quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.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.
Dinov2WithRegistersForImageClassification
classe transformers.Dinov2WithRegistersForImageClassification
< source >( 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
< source >( 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.Tensorde forma(batch_size, num_channels, image_size, image_size), opcional) — Os tensores correspondentes às imagens de entrada. Os valores de pixels podem ser obtidos usandoimage_processor_class. Consulteimage_processor_class.__call__para mais detalhes (processor_classusaimage_processor_classpara processar as imagens). - labels (
torch.LongTensorde 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]. Seconfig.num_labels == 1, uma perda de regressão é calculada (perda de erro quadrático médio); seconfig.num_labels > 1, uma perda de classificação é calculada (entropia cruzada). - attention_mask (
torch.Tensorde 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.
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
Moduleem 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.Tensorde forma(1,), opcional, retornado quandolabelsé fornecido) — Perda de classificação (ou regressão se config.num_labels==1).logits (
torch.Tensorde 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 quandooutput_hidden_states=Trueé passado ou quandoconfig.output_hidden_states=True) — Tupla detorch.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 quandooutput_attentions=Trueé passado ou quandoconfig.output_attentions=True) — Tupla detorch.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])
...