# DINOv2 com Registros
## Visão geral
O modelo DINOv2 with Registers foi proposto em [Vision Transformers Need Registers](https://huggingface.co/papers/2309.16588) por Timothée Darcet, Maxime Oquab, Julien Mairal, Piotr Bojanowski.
O [Vision Transformer](vit) (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](dinov2) e [MAE](vit_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.*
Visualização dos mapas de atenção de vários modelos treinados com e sem registros. Retirado do artigo original.
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](https://huggingface.co/nielsr). O código original pode ser encontrado [aqui](https://github.com/facebookresearch/dinov2).
## Dinov2WithRegistersConfig[[transformers.Dinov2WithRegistersConfig]]
#### transformers.Dinov2WithRegistersConfig[[transformers.Dinov2WithRegistersConfig]]
```python
transformers.Dinov2WithRegistersConfig(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 = 768, num_hidden_layers: int = 12, num_attention_heads: int = 12, mlp_ratio: int = 4, hidden_act: str = 'gelu', hidden_dropout_prob: float | int = 0.0, attention_probs_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] = 224, patch_size: int | list[int] | tuple[int, int] = 16, num_channels: int = 3, qkv_bias: bool = True, layerscale_value: float = 1.0, drop_path_rate: float | int = 0.0, use_swiglu_ffn: bool = False, num_register_tokens: int = 4, _out_features: list[str] | None = None, _out_indices: list[int] | None = None, apply_layernorm: bool = True, reshape_hidden_states: bool = True)
```
[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinov2_with_registers/configuration_dinov2_with_registers.py#L32)
**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`) : Razã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 deve aplicar normalização de camada 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](https://huggingface.co/facebook/dinov2-with-registers-base)
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.
Exemplo:
```python
>>> 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[[transformers.Dinov2WithRegistersModel]]
#### transformers.Dinov2WithRegistersModel[[transformers.Dinov2WithRegistersModel]]
```python
transformers.Dinov2WithRegistersModel(config: Dinov2WithRegistersConfig)
```
[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinov2_with_registers/modeling_dinov2_with_registers.py#L393)
**Parâmetros:**
config ([Dinov2WithRegistersConfig](/docs/transformers/main/pt/model_doc/dinov2_with_registers#transformers.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()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.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](/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.Dinov2WithRegistersModel.forward]]
```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, bool_masked_pos: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *)
```
[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinov2_with_registers/modeling_dinov2_with_registers.py#L402)
**Parâmetros:**
pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`, *opcional*) : Os tensors 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é-treinamento.
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?](../glossary#attention-mask)
**Retorna:** [BaseModelOutputWithPooling](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPooling) ou `tuple(torch.Tensor)`
Um [BaseModelOutputWithPooling](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.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](/docs/transformers/main/pt/model_doc/dinov2_with_registers#transformers.Dinov2WithRegistersConfig)) e das entradas.
O método forward do [Dinov2WithRegistersModel](/docs/transformers/main/pt/model_doc/dinov2_with_registers#transformers.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 pelas camadas usadas para a tarefa de pré-treinamento auxiliar. Por exemplo, para modelos da família BERT, isso retorna o token de classificação após o processamento por 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) com a 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 a 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 nas cabeças de autoatenção.
Exemplo:
```python
```
## Dinov2WithRegistersForImageClassification[[transformers.Dinov2WithRegistersForImageClassification]]
#### transformers.Dinov2WithRegistersForImageClassification[[transformers.Dinov2WithRegistersForImageClassification]]
```python
transformers.Dinov2WithRegistersForImageClassification(config: Dinov2WithRegistersConfig)
```
[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinov2_with_registers/modeling_dinov2_with_registers.py#L439)
**Parâmetros:**
config ([Dinov2WithRegistersConfig](/docs/transformers/main/pt/model_doc/dinov2_with_registers#transformers.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()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.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 o ImageNet.
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.Dinov2WithRegistersForImageClassification.forward]]
```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *)
```
[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinov2_with_registers/modeling_dinov2_with_registers.py#L452)
**Parâmetros:**
pixel_values (`torch.Tensor` de forma `(batch_size, num_channels, image_size, image_size)`, *opcional*) : Os tensors 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?](../glossary#attention-mask)
**Retorna:** [ImageClassifierOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput) ou `tuple(torch.Tensor)`
Um [ImageClassifierOutput](/docs/transformers/main/pt/main_classes/output#transformers.modeling_outputs.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](/docs/transformers/main/pt/model_doc/dinov2_with_registers#transformers.Dinov2WithRegistersConfig)) e das entradas.
O método forward de [Dinov2WithRegistersForImageClassification](/docs/transformers/main/pt/model_doc/dinov2_with_registers#transformers.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 de 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` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma 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` (uma para cada camada) de 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 nas cabeças de autoatenção.
Exemplo:
```python
>>> 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])
...
```