# Dilated Neighborhood Attention Transformer

## Visão geral

O DiNAT foi proposto em [Dilated Neighborhood Attention Transformer](https://huggingface.co/papers/2209.15001) por Ali Hassani e Humphrey Shi.

Ele estende o [NAT](https://huggingface.co/papers/2204.07143) ao adicionar um padrão de Dilated Neighborhood Attention para capturar o contexto global, e apresenta melhorias significativas de desempenho em relação a ele.

O resumo do artigo é o seguinte:

*Os Transformers estão se tornando rapidamente uma das arquiteturas de deep learning mais amplamente aplicadas entre modalidades, domínios e tarefas. Na visão computacional, além dos esforços contínuos em transformers puros, os transformers hierárquicos também ganharam atenção significativa, graças ao seu desempenho e à fácil integração em frameworks existentes. Esses modelos geralmente empregam mecanismos de atenção localizados, como a Neighborhood Attention (NA) de janela deslizante ou a Shifted Window Self Attention do Swin Transformer. Embora sejam eficazes na redução da complexidade quadrática da self attention, a atenção local enfraquece duas das propriedades mais desejáveis da self attention: a modelagem de interdependências de longo alcance e o campo receptivo global. Neste artigo, apresentamos a Dilated Neighborhood Attention (DiNA), uma extensão natural, flexível e eficiente da NA que pode capturar mais contexto global e expandir os campos receptivos exponencialmente sem custo adicional. A atenção local da NA e a atenção global esparsa da DiNA se complementam, e, portanto, apresentamos o Dilated Neighborhood Attention Transformer (DiNAT), um novo transformer de visão hierárquico construído sobre ambos. As variantes do DiNAT apresentam melhorias significativas em relação a baselines fortes, como NAT, Swin e ConvNeXt. Nosso modelo grande é mais rápido e supera seu equivalente Swin em 1,5% de box AP na detecção de objetos COCO, 1,3% de mask AP na segmentação de instâncias COCO e 1,1% de mIoU na segmentação semântica ADE20K. Combinado com novos frameworks, nossa variante grande é o novo estado da arte em modelos de segmentação panóptica no COCO (58,2 PQ) e ADE20K (48,5 PQ), e em modelos de segmentação de instâncias no Cityscapes (44,5 AP) e ADE20K (35,4 AP) (sem dados extras). Ele também iguala os modelos especializados de segmentação semântica estado da arte no ADE20K (58,2 mIoU) e ocupa a segunda posição no Cityscapes (84,5 mIoU) (sem dados extras).*

<img
src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/dilated-neighborhood-attention-pattern.jpg"
alt="drawing" width="600"/>

 Atenção de vizinhança com diferentes valores de dilatação. Retirado do artigo original.

Este modelo foi contribuído por [Ali Hassani](https://huggingface.co/alihassanijr). O código original pode ser encontrado [aqui](https://github.com/SHI-Labs/Neighborhood-Attention-Transformer).

## Dicas de uso

O DiNAT pode ser usado como *backbone*. Quando `output_hidden_states = True`, ele exibirá tanto `hidden_states` quanto `reshaped_hidden_states`. O `reshaped_hidden_states` tem a forma `(batch, num_channels, height, width)` em vez de `(batch_size, height, width, num_channels)`.

Observações:

- O DiNAT depende da implementação do Neighborhood Attention e do Dilated Neighborhood Attention do [NATTEN](https://github.com/SHI-Labs/NATTEN/).
Você pode instalá-lo com wheels pré-compilados para Linux consultando [shi-labs.com/natten](https://shi-labs.com/natten), ou compilá-lo no seu sistema executando `pip install natten`. Observe que a segunda opção provavelmente levará tempo para compilar. O NATTEN ainda não suporta dispositivos Windows.
- No momento, apenas o tamanho de patch 4 é suportado.

## Recursos

Uma lista de recursos oficiais da Hugging Face e da comunidade (indicados por 🌎) para ajudar você a começar com o DiNAT.

- [DinatForImageClassification](/docs/transformers/main/pt/model_doc/dinat#transformers.DinatForImageClassification) é suportado por este [notebook](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/image_classification.ipynb).
- Veja também: [Guia da tarefa de classificação de imagens](../tasks/image_classification)

Se você tiver interesse em enviar um recurso para ser incluído aqui, sinta-se à vontade para abrir um Pull Request e faremos a revisão! O recurso deve, idealmente, demonstrar algo novo, em vez de duplicar um recurso existente.

## DinatConfig[[transformers.DinatConfig]]

#### transformers.DinatConfig[[transformers.DinatConfig]]

```python
transformers.DinatConfig(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, patch_size: int | list[int] | tuple[int, int] = 4, num_channels: int = 3, embed_dim: int = 64, depths: list[int] | tuple[int, ...] = (3, 4, 6, 5), num_heads: list[int] | tuple[int, ...] = (2, 4, 8, 16), kernel_size: int = 7, dilations: list | tuple | None = None, mlp_ratio: float = 3.0, qkv_bias: bool = True, hidden_dropout_prob: float | int = 0.0, attention_probs_dropout_prob: float | int = 0.0, drop_path_rate: float | int = 0.1, hidden_act: str = 'gelu', initializer_range: float = 0.02, layer_norm_eps: float = 1e-05, layer_scale_init_value: float = 0.0, _out_features: list[str] | None = None, _out_indices: list[int] | None = None)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinat/configuration_dinat.py#L25)

**Parâmetros:**

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

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

embed_dim (`int`, *opcional*, padrão `64`) : Dimensionalidade dos embeddings e dos estados ocultos.

depths (`Union[list[int], tuple[int, ...]]`, *opcional*, padrão `(3, 4, 6, 5)`) : Profundidade de cada camada no Transformer.

num_heads (`Union[list[int], tuple[int, ...]]`, *opcional*, padrão `(2, 4, 8, 16)`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

kernel_size (`int`, *opcional*, padrão `7`) : O tamanho do kernel de convolução.

dilations (`list[list[int]]`, *opcional*, padrão `[[1, 8, 1], [1, 4, 1, 4], [1, 2, 1, 2, 1, 2], [1, 1, 1, 1, 1]]`) : Valor de dilatação de cada camada NA no codificador Transformer.

mlp_ratio (`float`, *opcional*, padrão `3.0`) : Razão entre a dimensão oculta do MLP e a dimensão de incorporação.

qkv_bias (`bool`, *opcional*, padrão `True`) : Se deve adicionar um viés às queries, keys e values.

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.

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

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.

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-05`) : O epsilon usado pelas camadas de normalização de camada.

layer_scale_init_value (`float`, *opcional*, padrão `0.0`) : Escala a ser usada nas camadas de autoatenção. 0.1 para base, 1e-6 para grande. Defina 0 para desativar a escala da camada.

Esta é a classe de configuração para armazenar a configuração de um DinatModel. Ela é usada para instanciar um modelo Dinat 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 [shi-labs/dinat-mini-in1k-224](https://huggingface.co/shi-labs/dinat-mini-in1k-224)

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 DinatConfig, DinatModel

>>> # Initializing a Dinat shi-labs/dinat-mini-in1k-224 style configuration
>>> configuration = DinatConfig()

>>> # Initializing a model (with random weights) from the shi-labs/dinat-mini-in1k-224 style configuration
>>> model = DinatModel(configuration)

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

## DinatModel[[transformers.DinatModel]]

#### transformers.DinatModel[[transformers.DinatModel]]

```python
transformers.DinatModel(config: DinatConfig, add_pooling_layer = True)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinat/modeling_dinat.py#L541)

**Parâmetros:**

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

add_pooling_layer (`bool`, *opcional*, padrão `True`) : Se deve adicionar uma camada de pooling

O modelo Dinat básico, 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.DinatModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinat/modeling_dinat.py#L567)

**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 [ViTImageProcessor](/docs/transformers/main/pt/model_doc/vit#transformers.ViTImageProcessor). Consulte [ViTImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para obter detalhes (`processor_class` usa [ViTImageProcessor](/docs/transformers/main/pt/model_doc/vit#transformers.ViTImageProcessor) para processar imagens).

output_attentions (`bool`, *opcional*) : Indica se os tensores de atenção de todas as camadas de atenção devem ser retornados. Consulte `attentions` nos tensores retornados para mais detalhes.

output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes.

return_dict (`bool`, *opcional*) : Se deve ou não retornar um [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput) em vez de uma tupla simples.

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

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

O método forward do [DinatModel](/docs/transformers/main/pt/model_doc/dinat#transformers.DinatModel) 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)`, *opcional*) -- Sequência de hidden-states na saída da última camada do modelo.
- **pooler_output** (`torch.Tensor` de forma `(batch_size, hidden_size)`, *opcional*, retornado quando `add_pooling_layer=True` é passado) -- Pooling médio do estado oculto 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` (uma para a saída dos embeddings, se o modelo tiver uma camada de embedding, + uma 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` (uma para cada camada) de 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.
- **reshaped_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, hidden_size, height, width)`.

  Estados ocultos do modelo na saída de cada camada, mais as saídas do embedding inicial, redimensionados para incluir as dimensões espaciais.

Exemplo:

```python
```

## DinatForImageClassification[[transformers.DinatForImageClassification]]

#### transformers.DinatForImageClassification[[transformers.DinatForImageClassification]]

```python
transformers.DinatForImageClassification(config: DinatConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinat/modeling_dinat.py#L622)

**Parâmetros:**

config ([DinatConfig](/docs/transformers/main/pt/model_doc/dinat#transformers.DinatConfig)) : 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 Dinat transformer com uma cabeça de classificação de imagem no topo (uma camada linear sobre o 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.DinatForImageClassification.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, return_dict: bool | None = None, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/dinat/modeling_dinat.py#L639)

**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 [ViTImageProcessor](/docs/transformers/main/pt/model_doc/vit#transformers.ViTImageProcessor). Consulte [ViTImageProcessor.__call__()](/docs/transformers/main/pt/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) para obter detalhes (`processor_class` usa [ViTImageProcessor](/docs/transformers/main/pt/model_doc/vit#transformers.ViTImageProcessor) para processar 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).

output_attentions (`bool`, *opcional*) : Indica se os tensores de atenção de todas as camadas de atenção devem ser retornados. Consulte `attentions` nos tensores retornados para mais detalhes.

output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes.

return_dict (`bool`, *opcional*) : Se deve ou não retornar um [ModelOutput](/docs/transformers/main/pt/main_classes/output#transformers.utils.ModelOutput) em vez de uma tupla simples.

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

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

O método forward de [DinatForImageClassification](/docs/transformers/main/pt/model_doc/dinat#transformers.DinatForImageClassification) 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 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` (uma para cada camada) de 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.
- **reshaped_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, hidden_size, height, width)`.

  Estados ocultos do modelo na saída de cada camada, mais as saídas do embedding inicial, redimensionados para incluir as dimensões espaciais.

Exemplo:

```python
>>> from transformers import AutoImageProcessor, DinatForImageClassification
>>> import torch
>>> from datasets import load_dataset

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

>>> image_processor = AutoImageProcessor.from_pretrained("shi-labs/dinat-mini-in1k-224")
>>> model = DinatForImageClassification.from_pretrained("shi-labs/dinat-mini-in1k-224")

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