# Transformeur d'attention de voisinage dilaté

## Aperçu

DiNAT a été proposé dans [Dilated Neighborhood Attention Transformer](https://huggingface.co/papers/2209.15001) par Ali Hassani et Humphrey Shi.

Il étend [NAT](https://huggingface.co/papers/2204.07143) en y ajoutant un motif de Dilated Neighborhood Attention afin de capturer le contexte global, et il présente des améliorations de performances significatives par rapport à ce dernier.

L'abstract de l'article est le suivant :

*Les Transformers s’imposent rapidement comme l’une des architectures d’apprentissage profond les plus largement déployées, quelle que soit la modalité, le domaine ou la tâche. En vision, au-delà des efforts en cours sur les Transformers « plain », les Transformers hiérarchiques ont également suscité un intérêt considérable, grâce à leurs performances et à leur intégration aisée dans les cadres existants. Ces modèles utilisent typiquement des mécanismes d’attention localisés, tels que l’attention de voisinage glissante (Neighborhood Attention, NA) ou l’auto-attention à fenêtre décalée du Swin Transformer. Bien qu’efficaces pour réduire la complexité quadratique de l’auto-attention, l’attention locale affaiblit deux des propriétés les plus souhaitables de l’auto-attention : la modélisation des dépendances à longue portée et le champ récepteur global. Dans cet article, nous présentons la Dilated Neighborhood Attention (DiNA), une extension naturelle, flexible et efficace de la NA, capable de capturer un contexte plus global et d’élargir exponentiellement les champs récepteurs sans coût supplémentaire. L’attention locale de la NA et l’attention globale creuse de la DiNA se complètent, c’est pourquoi nous introduisons le Dilated Neighborhood Attention Transformer (DiNAT), un nouveau Transformer de vision hiérarchique fondé sur les deux. Les variantes de DiNAT offrent des améliorations significatives par rapport à des références solides telles que NAT, Swin et ConvNeXt. Notre grand modèle est plus rapide et devance son équivalent Swin de 1,5 % de box AP en détection d’objets sur COCO, de 1,3 % de mask AP en segmentation d’instances sur COCO et de 1,1 % de mIoU en segmentation sémantique sur ADE20K. Associé à de nouveaux cadres, notre grande variante est le nouveau modèle de référence en segmentation panoptique sur COCO (58,2 PQ) et ADE20K (48,5 PQ), ainsi qu’en segmentation d’instances sur Cityscapes (44,5 AP) et ADE20K (35,4 AP) (sans données supplémentaires). Il égale également les modèles spécialisés de référence en segmentation sémantique sur ADE20K (58,2 mIoU) et se classe deuxième sur Cityscapes (84,5 mIoU) (sans données supplémentaires).*

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

 Neighborhood Attention avec différentes valeurs de dilatation. Tiré de l'article original.

Ce modèle a été contribué par [Ali Hassani](https://huggingface.co/alihassanijr). Le code d’origine est disponible [ici](https://github.com/SHI-Labs/Neighborhood-Attention-Transformer).

## Conseils d'utilisation

DiNAT peut être utilisé comme *backbone*. Lorsque `output_hidden_states = True`, il renvoie à la fois `hidden_states` et `reshaped_hidden_states`. Les `reshaped_hidden_states` ont une forme de `(batch, num_channels, height, width)` plutôt que `(batch_size, height, width, num_channels)`.

Remarques :

- DiNAT dépend de l’implémentation de Neighborhood Attention et Dilated Neighborhood Attention par [NATTEN](https://github.com/SHI-Labs/NATTEN/).
Vous pouvez l’installer à l’aide de paquets précompilés pour Linux en consultant [shi-labs.com/natten](https://shi-labs.com/natten), ou le compiler sur votre système en exécutant `pip install natten`. Notez que cette dernière option prendra probablement du temps à compiler. NATTEN ne prend pas encore en charge les appareils Windows.
- La taille de patch 4 est actuellement la seule prise en charge.

## Ressources

Une liste de ressources officielles Hugging Face et de la communauté (indiquées par 🌎) pour vous aider à démarrer avec DiNAT.

- [DinatForImageClassification](/docs/transformers/v5.23.0/fr/model_doc/dinat#transformers.DinatForImageClassification) est pris en charge par ce [notebook](https://colab.research.google.com/github/huggingface/notebooks/blob/main/examples/image_classification.ipynb).
- Voir aussi : [Guide de la tâche de classification d'images](../tasks/image_classification)

Si vous souhaitez soumettre une ressource pour qu'elle soit incluse ici, n'hésitez pas à ouvrir une Pull Request et nous la examinerons ! La ressource devrait idéalement démontrer quelque chose de nouveau plutôt que de dupliquer une ressource existante.

## 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)
```

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

**Paramètres :**

patch_size (`Union[int, list[int], tuple[int, int]]`, *facultatif*, valeur par défaut `4`) : La taille (résolution) de chaque patch.

num_channels (`int`, *facultatif*, par défaut `3`) : Le nombre de canaux d'entrée.

embed_dim (`int`, *facultatif*, par défaut `64`) : Dimension des embeddings et des états cachés.

depths (`Union[list[int], tuple[int, ...]]`, *facultatif*, valeur par défaut `(3, 4, 6, 5)`) : Profondeur de chaque couche du Transformer.

num_heads (`Union[list[int], tuple[int, ...]]`, *facultatif*, valeur par défaut `(2, 4, 8, 16)`) : Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.

kernel_size (`int`, *facultatif*, par défaut `7`) : La taille du noyau de convolution.

dilations (`list[list[int]]`, *facultatif*, par défaut `[[1, 8, 1], [1, 4, 1, 4], [1, 2, 1, 2, 1, 2], [1, 1, 1, 1, 1]]`) : Valeur de dilatation de chaque couche NA dans l'encodeur Transformer.

mlp_ratio (`float`, *facultatif*, valeur par défaut `3.0`) : Ratio de la dimension cachée du MLP par rapport à la dimension d'embedding.

qkv_bias (`bool`, *facultatif*, par défaut `True`) : Indique s'il faut ajouter un biais aux requêtes, clés et valeurs.

hidden_dropout_prob (`Union[float, int]`, *facultatif*, valeur par défaut `0.0`) : La probabilité de dropout pour toutes les couches entièrement connectées des embeddings, de l'encodeur et du pooler.

attention_probs_dropout_prob (`Union[float, int]`, *facultatif*, valeur par défaut `0.0`) : Le taux de dropout appliqué aux probabilités d'attention.

drop_path_rate (`Union[float, int]`, *facultatif*, valeur par défaut `0.1`) : Taux de drop path pour la fusion des patches.

hidden_act (`str`, *facultatif*, par défaut `gelu`) : La fonction d'activation non linéaire (fonction ou chaîne de caractères) dans le décodeur. Par exemple, `"gelu"`, `"relu"`, `"silu"`, etc.

initializer_range (`float`, *facultatif*, valeur par défaut `0.02`) : L'écart-type de la truncated_normal_initializer utilisé pour l'initialisation de toutes les matrices de poids.

layer_norm_eps (`float`, *facultatif*, valeur par défaut `1e-05`) : L'épsilon utilisé par les couches de normalisation de couche.

layer_scale_init_value (`float`, *facultatif*, valeur par défaut `0.0`) : Échelle à utiliser dans les couches d'auto-attention. 0.1 pour les modèles de base, 1e-6 pour les grands modèles. Définir 0 pour désactiver l'échelle de couche.

Ceci est la classe de configuration destinée à stocker la configuration d'un DinatModel. Elle est utilisée pour instancier un modèle Dinat en fonction des arguments spécifiés, en définissant l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de [shi-labs/dinat-mini-in1k-224](https://huggingface.co/shi-labs/dinat-mini-in1k-224)

Les objets de configuration héritent de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de [PreTrainedConfig](/docs/transformers/v5.23.0/fr/main_classes/configuration#transformers.PreTrainedConfig) pour plus d’informations.

Exemple :

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

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

**Paramètres :**

config ([DinatConfig](/docs/transformers/v5.23.0/fr/model_doc/dinat#transformers.DinatConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

add_pooling_layer (`bool`, *facultatif*, valeur par défaut `True`) : Indique s'il faut ajouter une couche de pooling

Le modèle Dinat brut, qui produit des états cachés bruts sans aucune tête spécifique au sommet.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

#### 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)
```

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

**Paramètres :**

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`, *facultatif*) : Les tenseurs correspondant aux images d'entrée. Les valeurs de pixels peuvent être obtenues à l'aide de [ViTImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/vit#transformers.ViTImageProcessor). Voir [ViTImageProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) pour plus de détails (`processor_class` utilise [ViTImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/vit#transformers.ViTImageProcessor) pour le traitement des images).

output_attentions (`bool`, *facultatif*) : Indique s'il faut ou non retourner les tenseurs d'attention de toutes les couches d'attention. Voir `attentions` sous les tenseurs retournés pour plus de détails.

output_hidden_states (`bool`, *facultatif*) : Indique s'il faut retourner les états cachés de toutes les couches. Voir `hidden_states` dans les tenseurs retournés pour plus de détails.

return_dict (`bool`, *facultatif*) : Indique s'il faut retourner un [ModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.utils.ModelOutput) plutôt qu'un simple tuple.

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

Un `DinatModelOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([DinatConfig](/docs/transformers/v5.23.0/fr/model_doc/dinat#transformers.DinatConfig)) et les entrées.

La méthode forward du [DinatModel](/docs/transformers/v5.23.0/fr/model_doc/dinat#transformers.DinatModel) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **last_hidden_state** (`torch.Tensor` de forme `(batch_size, sequence_length, hidden_size)`, *facultatif*) -- Séquence d'états cachés à la sortie de la dernière couche du modèle.
- **pooler_output** (`torch.Tensor` de forme `(batch_size, hidden_size)`, *facultatif*, renvoyé lorsque `add_pooling_layer=True` est passé) -- Pooling moyen de l'état caché de la dernière couche.
- **hidden_states** (`tuple[torch.Tensor, ...]`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d'embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.
- **attentions** (`tuple[torch.Tensor, ...]`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pondérations des attentions après le softmax d'attention, utilisées pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **reshaped_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings + un pour la sortie de chaque étape) de forme `(batch_size, hidden_size, height, width)`.

  États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d’incorporation initiales, redimensionnées pour inclure les dimensions spatiales.

Exemple :

```python
```

## DinatForImageClassification[[transformers.DinatForImageClassification]]

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

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

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

**Paramètres :**

config ([DinatConfig](/docs/transformers/v5.23.0/fr/model_doc/dinat#transformers.DinatConfig)) : Classe de configuration du modèle contenant tous les paramètres du modèle. L'initialisation à partir d'un fichier de configuration ne charge pas les poids associés au modèle, uniquement la configuration. Consultez la méthode [from_pretrained()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) pour charger les poids du modèle.

Transformeur de modèle Dinat avec une tête de classification d'images au sommet (une couche linéaire au-dessus de l'état caché final du jeton [CLS]), par exemple pour ImageNet.

Ce modèle hérite de [PreTrainedModel](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel). Consultez la documentation de la classe parente pour les méthodes génériques que la bibliothèque implémente pour tous ses modèles (tels que le téléchargement ou l'enregistrement, le redimensionnement des embeddings d'entrée, l'élagage des têtes, etc.).

Ce modèle est également une sous-classe de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) de PyTorch. Utilisez-le comme un module PyTorch standard et consultez la documentation de PyTorch pour tout ce qui concerne l’utilisation et le comportement généraux.

#### 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)
```

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

**Paramètres :**

pixel_values (`torch.Tensor` de forme `(batch_size, num_channels, image_size, image_size)`, *facultatif*) : Les tenseurs correspondant aux images d'entrée. Les valeurs de pixels peuvent être obtenues à l'aide de [ViTImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/vit#transformers.ViTImageProcessor). Voir [ViTImageProcessor.__call__()](/docs/transformers/v5.23.0/fr/model_doc/molmo2#transformers.Molmo2ImageProcessor.__call__) pour plus de détails (`processor_class` utilise [ViTImageProcessor](/docs/transformers/v5.23.0/fr/model_doc/vit#transformers.ViTImageProcessor) pour le traitement des images).

labels (`torch.LongTensor` de forme `(batch_size,)`, *facultatif*) : Étiquettes pour le calcul de la perte de classification/régression d'image. Les indices doivent être dans `[0, ..., config.num_labels - 1]`. Si `config.num_labels == 1`, une perte de régression est calculée (perte du carré moyen). Si `config.num_labels > 1`, une perte de classification est calculée (entropie croisée).

output_attentions (`bool`, *facultatif*) : Indique s'il faut ou non retourner les tenseurs d'attention de toutes les couches d'attention. Voir `attentions` sous les tenseurs retournés pour plus de détails.

output_hidden_states (`bool`, *facultatif*) : Indique s'il faut retourner les états cachés de toutes les couches. Voir `hidden_states` dans les tenseurs retournés pour plus de détails.

return_dict (`bool`, *facultatif*) : Indique s'il faut retourner un [ModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.utils.ModelOutput) plutôt qu'un simple tuple.

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

Un `DinatImageClassifierOutput` ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments selon la configuration ([DinatConfig](/docs/transformers/v5.23.0/fr/model_doc/dinat#transformers.DinatConfig)) et les entrées.

La méthode forward de [DinatForImageClassification](/docs/transformers/v5.23.0/fr/model_doc/dinat#transformers.DinatForImageClassification) redéfinit la méthode spéciale `__call__`.

Bien que la recette de la passe avant doive être définie dans cette fonction, il faut ensuite appeler l'instance `Module` plutôt que celle-ci, car la première gère l'exécution des étapes de prétraitement et de post-traitement, tandis que la seconde les ignore silencieusement.

- **loss** (`torch.Tensor` de forme `(1,)`, *facultatif*, renvoyé lorsque `labels` est fourni) -- Perte de classification (ou de régression si config.num_labels==1).
- **logits** (`torch.Tensor` de forme `(batch_size, config.num_labels)`) -- Scores de classification (ou de régression si config.num_labels==1) (avant SoftMax).
- **hidden_states** (`tuple[torch.Tensor, ...]`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings, si le modèle possède une couche d'embedding, + un pour la sortie de chaque couche) de forme `(batch_size, sequence_length, hidden_size)`.

  États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d'incorporation initiales facultatives.
- **attentions** (`tuple[torch.Tensor, ...]`, *facultatif*, renvoyé lorsque `output_attentions=True` est passé ou lorsque `config.output_attentions=True`) -- Tuple de `torch.Tensor` (un par couche) de forme `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pondérations des attentions après le softmax d'attention, utilisées pour calculer la moyenne pondérée dans les têtes d'auto-attention.
- **reshaped_hidden_states** (`tuple(torch.Tensor)`, *facultatif*, renvoyé lorsque `output_hidden_states=True` est passé ou lorsque `config.output_hidden_states=True`) -- Tuple de `torch.Tensor` (un pour la sortie des embeddings + un pour la sortie de chaque étape) de forme `(batch_size, hidden_size, height, width)`.

  États cachés du modèle à la sortie de chaque couche, ainsi que les sorties d’incorporation initiales, redimensionnées pour inclure les dimensions spatiales.

Exemple :

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

