# ViTMSN

## Aperçu

Le modèle ViTMSN a été proposé dans [Masked Siamese Networks for Label-Efficient Learning](https://huggingface.co/papers/2204.07141) par Mahmoud Assran, Mathilde Caron, Ishan Misra, Piotr Bojanowski, Florian Bordes, Pascal Vincent, Armand Joulin, Michael Rabbat et Nicolas Ballas. L’article présente une architecture d’embarquement conjoint visant à faire correspondre les prototypes des patches masqués avec ceux des patches non masqués. Grâce à cette configuration, leur méthode offre d’excellentes performances dans les régimes low-shot et extreme low-shot.

L'abstract de l'article est le suivant :

*Nous proposons les réseaux siameses masqués (MSN), un cadre d'apprentissage auto-supervisé pour l'apprentissage de représentations d'images. Notre approche associe la représentation d'une vue d'image contenant des patches masqués aléatoirement à la représentation de l'image d'origine non masquée. Cette stratégie de pré-entraînement auto-supervisé est particulièrement évolutive lorsqu'elle est appliquée aux Vision Transformers, car seuls les patches non masqués sont traités par le réseau. En conséquence, les MSN améliorent l'évolutivité des architectures à joint-embedding, tout en produisant des représentations de haut niveau sémantique qui obtiennent des performances compétitives en classification d'images à faible nombre d'exemples. Par exemple, sur ImageNet-1K, avec seulement 5 000 images annotées, notre modèle MSN de base atteint une précision top-1 de 72,4 %, et avec 1 % des étiquettes d'ImageNet-1K, nous atteignons une précision top-1 de 75,7 %, établissant un nouvel état de l'art pour l'apprentissage auto-supervisé sur ce benchmark.*

 Architecture MSN. Issue de l'article original.

Ce modèle a été contribué par [sayakpaul](https://huggingface.co/sayakpaul). Le code d’origine est disponible [ici](https://github.com/facebookresearch/msn).

## Conseils d'utilisation

- MSN (masked siamese networks) est une méthode de pré-entraînement auto-supervisé des Vision Transformers (ViTs). Le pré-entraînement
l'objectif est d'associer les prototypes attribués aux vues non masquées des images à ceux des vues masquées des mêmes images.
- Les auteurs n'ont publié que les poids pré-entraînés du backbone (pré-entraînement sur ImageNet-1k). Ainsi, pour l'utiliser sur votre propre jeu de données de classification d'images,
utilisez la classe [ViTMSNForImageClassification](/docs/transformers/v5.23.0/fr/model_doc/vit_msn#transformers.ViTMSNForImageClassification), initialisée à partir de [ViTMSNModel](/docs/transformers/v5.23.0/fr/model_doc/vit_msn#transformers.ViTMSNModel). Suivez [ce notebook](https://github.com/huggingface/notebooks/blob/main/examples/image_classification.ipynb) pour un tutoriel détaillé sur le fine-tuning.
- MSN est particulièrement utile dans les régimes low-shot et extreme low-shot. Notamment, il atteint une précision top-1 de 75,7 % avec seulement 1 % d'ImageNet-1K
étiquettes lors de l'ajustement fin.

### Utilisation de l'attention à produit scalaire mis à l'échelle (SDPA)

PyTorch intègre un opérateur natif d'attention par produit scalaire mis à l'échelle (SDPA) au sein de `torch.nn.functional`. Cette fonction englobe plusieurs implémentations qui peuvent être appliquées en fonction des entrées et du matériel utilisé. Consultez la [documentation officielle](https://pytorch.org/docs/stable/generated/torch.nn.functional.scaled_dot_product_attention.html) ou la page [GPU Inference](https://huggingface.co/docs/transformers/main/en/perf_infer_gpu_one#pytorch-scaled-dot-product-attention) pour plus d'informations.

SDPA est utilisé par défaut pour `torch>=2.1.1` lorsqu’une implémentation est disponible, mais vous pouvez également définir `attn_implementation="sdpa"` dans `from_pretrained()` pour demander explicitement l’utilisation de SDPA.

```python
from transformers import ViTMSNForImageClassification

model = ViTMSNForImageClassification.from_pretrained("facebook/vit-msn-base", attn_implementation="sdpa", device_map="auto")
...
```

Pour obtenir les accélérations optimales, nous recommandons de charger le modèle en demi-précision (par exemple `torch.float16` ou `torch.bfloat16`).

Sur un benchmark local (A100-40GB, PyTorch 2.3.0, OS Ubuntu 22.04) avec `float32` et le modèle `facebook/vit-msn-base`, nous avons observé les accélérations suivantes lors de l’inférence.

|   Taille du lot |   Temps d'inférence moyen (ms), mode eager |   Temps d'inférence moyen (ms), modèle sdpa |   Accélération, Sdpa / Eager (x) |
|--------------|-------------------------------------------|-------------------------------------------|------------------------------|
|            1 |                                         7 |                                         6 |                      1.17 |
|            2 |                                         8 |                                         6 |                      1.33 |
|            4 |                                         8 |                                         6 |                      1.33 |
|            8 |                                         8 |                                         6 |                      1.33 |

## Ressources

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

- [ViTMSNForImageClassification](/docs/transformers/v5.23.0/fr/model_doc/vit_msn#transformers.ViTMSNForImageClassification) 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.

## ViTMSNConfig[[transformers.ViTMSNConfig]]

#### transformers.ViTMSNConfig[[transformers.ViTMSNConfig]]

```python
transformers.ViTMSNConfig(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, intermediate_size: int = 3072, 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)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/vit_msn/configuration_vit_msn.py#L24)

**Paramètres :**

hidden_size (`int`, *facultatif*, par défaut `768`) : Dimension des représentations cachées.

num_hidden_layers (`int`, *facultatif*, par défaut `12`) : Nombre de couches cachées dans le décodeur Transformer.

num_attention_heads (`int`, *facultatif*, valeur par défaut `12`) : Nombre de têtes d'attention pour chaque couche d'attention du décodeur Transformer.

intermediate_size (`int`, *facultatif*, par défaut `3072`) : Dimension des représentations MLP.

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.

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.

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*, par défaut `1e-06`) : L'épsilon utilisé par les couches de normalisation par couche.

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

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

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

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

Ceci est la classe de configuration destinée à stocker la configuration d'un ViTMSNModel. Elle est utilisée pour instancier un modèle Vit Msn 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 [facebook/vit_msn_base](https://huggingface.co/facebook/vit_msn_base)

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 ViTMSNModel, ViTMSNConfig

>>> # Initializing a ViT MSN vit-msn-base style configuration
>>> configuration = ViTConfig()

>>> # Initializing a model from the vit-msn-base style configuration
>>> model = ViTMSNModel(configuration)

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

## ViTMSNModel[[transformers.ViTMSNModel]]

#### transformers.ViTMSNModel[[transformers.ViTMSNModel]]

```python
transformers.ViTMSNModel(config: ViTMSNConfig, use_mask_token: bool = False)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/vit_msn/modeling_vit_msn.py#L317)

**Paramètres :**

config ([ViTMSNConfig](/docs/transformers/v5.23.0/fr/model_doc/vit_msn#transformers.ViTMSNConfig)) : 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.

use_mask_token (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut utiliser un jeton de masque pour le modélisation d'image masquée.

Le modèle Vit Msn 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.ViTMSNModel.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, bool_masked_pos: typing.Optional[torch.BoolTensor] = None, interpolate_pos_encoding: bool | None = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/vit_msn/modeling_vit_msn.py#L331)

**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).

bool_masked_pos (`torch.BoolTensor` de forme `(batch_size, num_patches)`, *facultatif*) : Positions masquées booléennes. Indique quels patches sont masqués (1) et lesquels ne le sont pas (0).

interpolate_pos_encoding (`bool`, *facultatif*) : Indique s'il faut interpoler les encodages de position pré-entraînés.

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

**Retourne :** [BaseModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.modeling_outputs.BaseModelOutput) ou `tuple(torch.Tensor)`

Un [BaseModelOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.modeling_outputs.BaseModelOutput) ou un tuple de `torch.Tensor` (si `return_dict=False` est passé ou lorsque `config.return_dict=False`) comprenant divers éléments en fonction de la configuration ([ViTMSNConfig](/docs/transformers/v5.23.0/fr/model_doc/vit_msn#transformers.ViTMSNConfig)) et des entrées.

La méthode forward de [ViTMSNModel](/docs/transformers/v5.23.0/fr/model_doc/vit_msn#transformers.ViTMSNModel) 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)`) -- Séquence d'états cachés à la sortie de la dernière couche du modèle.
- **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.

Exemples :

```python
>>> from transformers import AutoImageProcessor, ViTMSNModel
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read()))

>>> image_processor = AutoImageProcessor.from_pretrained("facebook/vit-msn-small")
>>> model = ViTMSNModel.from_pretrained("facebook/vit-msn-small")
>>> inputs = image_processor(images=image, return_tensors="pt")
>>> with torch.no_grad():
...     outputs = model(**inputs)
>>> last_hidden_states = outputs.last_hidden_state
```

## ViTMSNForImageClassification[[transformers.ViTMSNForImageClassification]]

#### transformers.ViTMSNForImageClassification[[transformers.ViTMSNForImageClassification]]

```python
transformers.ViTMSNForImageClassification(config: ViTMSNConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/vit_msn/modeling_vit_msn.py#L387)

**Paramètres :**

config ([ViTMSNConfig](/docs/transformers/v5.23.0/fr/model_doc/vit_msn#transformers.ViTMSNConfig)) : 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.

Le modèle Vit Msn avec une tête de classification d'images au sommet, 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.ViTMSNForImageClassification.forward]]

```python
forward(pixel_values: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, interpolate_pos_encoding: bool | None = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/vit_msn/modeling_vit_msn.py#L395)

**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.

interpolate_pos_encoding (`bool`, *facultatif*) : Indique s'il faut interpoler les encodages de position pré-entraînés.

attention_mask (`torch.Tensor` de forme `(batch_size, sequence_length)`, *facultatif*) : Masque pour éviter d'appliquer l'attention aux indices des jetons de bourrage. Les valeurs du masque sont choisies dans `[0, 1]` : - 1 pour les jetons qui ne sont **pas masqués**, - 0 pour les jetons qui sont **masqués**. [Qu'est-ce qu'un masque d'attention ?](../glossary#attention-mask)

**Retourne :** [ImageClassifierOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput) ou `tuple(torch.Tensor)`

Un [ImageClassifierOutput](/docs/transformers/v5.23.0/fr/main_classes/output#transformers.modeling_outputs.ImageClassifierOutput) 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 ([ViTMSNConfig](/docs/transformers/v5.23.0/fr/model_doc/vit_msn#transformers.ViTMSNConfig)) et les entrées.

La méthode forward de [ViTMSNForImageClassification](/docs/transformers/v5.23.0/fr/model_doc/vit_msn#transformers.ViTMSNForImageClassification) 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 étape) de forme `(batch_size, sequence_length, hidden_size)`. États cachés (également appelés cartes de caractéristiques) du modèle à la sortie de chaque étape.
- **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, patch_size, 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.

Exemples :

```python
>>> from transformers import AutoImageProcessor, ViTMSNForImageClassification
>>> import torch
>>> from PIL import Image
>>> from huggingface_hub.utils import httpx
>>> from io import BytesIO

>>> torch.manual_seed(2)
>>> url = "http://images.cocodataset.org/val2017/000000039769.jpg"
>>> with httpx.stream("GET", url) as response:
...     image = Image.open(BytesIO(response.read())).convert("RGB")

>>> image_processor = AutoImageProcessor.from_pretrained("facebook/vit-msn-small")
>>> model = ViTMSNForImageClassification.from_pretrained("facebook/vit-msn-small")

>>> inputs = image_processor(images=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])
tusker
```

