Hugging Face's logo

Transformers documentation

DINOv2 avec des registres

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Ce modèle a été publié dans HF papers le 2023-09-28 et ajouté à Hugging Face Transformers le 2024-12-24.

DINOv2 avec des registres

FlashAttention SDPA

Aperçu

Le modèle DINOv2 with Registers a été proposé dans Vision Transformers Need Registers par Timothée Darcet, Maxime Oquab, Julien Mairal, Piotr Bojanowski.

Le Vision Transformer (ViT) est un modèle d'encodeur transformer (de type BERT) initialement introduit pour effectuer la classification d'images supervisée sur ImageNet.

Ensuite, des méthodes ont été développées pour permettre à ViT d’exceller dans l’extraction auto-supervisée de caractéristiques d’images (c’est-à-dire l’apprentissage de caractéristiques significatives, également appelées embeddings) sans nécessiter d’étiquettes. Parmi les articles illustrant cette approche, on trouve DINOv2 et MAE.

Les auteurs de DINOv2 ont constaté que les ViTs présentent des artefacts dans les cartes d’attention. Cela est dû au fait que le modèle utilise certains patches d’image comme « registres ». Les auteurs proposent une solution : il suffit d’ajouter de nouveaux tokens (appelés tokens « register »), que l’on n’utilise que pendant le pré-entraînement (et que l’on jette ensuite). Cela donne :

  • aucun artefact
  • cartes d'attention interprétables
  • et des performances améliorées.

L'abstract de l'article est le suivant :

Les Transformers sont récemment apparus comme un outil puissant pour l’apprentissage de représentations visuelles. Dans cet article, nous identifions et caractérisons des artefacts dans les cartes de caractéristiques des réseaux ViT supervisés et auto-supervisés. Ces artefacts correspondent à des jetons de grande norme apparaissant lors de l’inférence, principalement dans les zones de fond peu informatives des images, qui sont réaffectées à des calculs internes. Nous proposons une solution simple mais efficace, consistant à fournir des jetons supplémentaires à la séquence d’entrée du Vision Transformer afin de remplir ce rôle. Nous montrons que cette solution corrige entièrement ce problème pour les modèles supervisés et auto-supervisés, établit un nouvel état de l’art pour les modèles visuels auto-supervisés sur les tâches de prédiction visuelle dense, permet l’utilisation de méthodes de découverte d’objets avec des modèles plus grands et, surtout, conduit à des cartes de caractéristiques et des cartes d’attention plus lisses pour le traitement visuel en aval.

drawing Visualization of attention maps of various models trained with vs. without registers. Taken from the original paper.

Astuces :

  • L’utilisation de DINOv2 avec Registers est identique à celle de DINOv2 sans, vous obtiendrez simplement de meilleures performances.

Ce modèle a été contribué par nielsr. Le code d'origine peut être trouvé ici.

Dinov2WithRegistersConfig

classe transformers.Dinov2WithRegistersConfig

< >

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

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.
  • mlp_ratio (int, facultatif, par défaut 4) — Ratio de la dimension cachée du MLP par rapport à la dimension d'embedding.
  • hidden_act (str, facultatif, par défaut gelu) — La fonction d'activation non linéaire (fonction ou chaîne de caractères) du décodeur. Par exemple, "gelu", "relu", "silu", etc.
  • hidden_dropout_prob (Union[float, int], facultatif, 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, par défaut 0.0) — Le taux de dropout appliqué aux probabilités d'attention.
  • initializer_range (float, facultatif, par défaut 0.02) — L'écart-type de la truncated_normal_initializer utilisé pour initialiser toutes les matrices de poids.
  • layer_norm_eps (float, facultatif, valeur par défaut 1e-06) — L'épsilon utilisé par les couches de normalisation de couche.
  • image_size (Union[int, list[int], tuple[int, int]], facultatif, par défaut 224) — La taille (résolution) de chaque image.
  • patch_size (Union[int, list[int], tuple[int, int]], facultatif, 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.
  • layerscale_value (float, facultatif, valeur par défaut 1.0) — Valeur initiale à utiliser pour l'échelle de couche.
  • drop_path_rate (Union[float, int], facultatif, par défaut 0.0) — Taux de drop path pour la fusion des patches.
  • use_swiglu_ffn (bool, facultatif, valeur par défaut False) — Indique s'il faut utiliser le réseau de neurones feedforward SwiGLU.
  • num_register_tokens (int, facultatif, valeur par défaut : 4) — Nombre de jetons d'enregistrement à utiliser.
  • apply_layernorm (bool, facultatif, par défaut True) — Indique s'il faut appliquer la normalisation par couche aux cartes de caractéristiques lorsque le modèle est utilisé comme backbone.
  • reshape_hidden_states (bool, facultatif, par défaut True) — Indique s'il faut redimensionner les cartes de caractéristiques en tenseurs 4D de forme (batch_size, hidden_size, height, width) lorsque le modèle est utilisé comme backbone. Si False, les cartes de caractéristiques seront des tenseurs 3D de forme (batch_size, seq_len, hidden_size).

Ceci est la classe de configuration destinée à stocker la configuration d'un Dinov2WithRegistersModel. Elle est utilisée pour instancier un modèle Dinov2 With Registers en fonction des arguments spécifiés, définissant ainsi l'architecture du modèle. L'instanciation d'une configuration avec les valeurs par défaut produira une configuration similaire à celle de facebook/dinov2-with-registers-base

Les objets de configuration héritent de PreTrainedConfig et peuvent être utilisés pour contrôler les sorties du modèle. Consultez la documentation de PreTrainedConfig pour plus d’informations.

Exemple :

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

classe transformers.Dinov2WithRegistersModel

< >

( config: Dinov2WithRegistersConfig )

Paramètres

  • config (Dinov2WithRegistersConfig) — 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() pour charger les poids du modèle.

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

Ce modèle hérite de 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, la taille des têtes, etc.)

Ce modèle est également une sous-classe de 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

< >

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

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 image_processor_class. Voir image_processor_class.__call__ pour plus de détails (processor_class utilise image_processor_class pour le traitement des images).
  • bool_masked_pos (torch.BoolTensor de forme (batch_size, sequence_length)) — Positions masquées booléennes. Indique quels patches sont masqués (1) et lesquels ne le sont pas (0). Pertinent uniquement pour le pré-entraînement.
  • 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 masqués.

    Qu'est-ce que les masques d'attention ?

Retourne

BaseModelOutputWithPooling ou tuple(torch.Tensor)

Un BaseModelOutputWithPooling 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 (Dinov2WithRegistersConfig) et des entrées.

La méthode forward du modèle Dinov2WithRegistersModel 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.

  • pooler_output (torch.Tensor de forme (batch_size, hidden_size)) — État caché de la dernière couche du premier jeton de la séquence (jeton de classification) après un traitement supplémentaire par les couches utilisées pour la tâche de pré-entraînement auxiliaire. Par exemple, pour les modèles de la famille BERT, cela renvoie le jeton de classification après traitement par une couche linéaire et une fonction d'activation tanh. Les poids de la couche linéaire sont entraînés à partir de l'objectif de prédiction de la phrase suivante (classification) pendant le pré-entraînement.

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

    Poids des attentions après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.

Exemple :

Dinov2WithRegistersForImageClassification

classe transformers.Dinov2WithRegistersForImageClassification

< >

( config: Dinov2WithRegistersConfig )

Paramètres

  • config (Dinov2WithRegistersConfig) — 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() pour charger les poids du modèle.

Modèle Dinov2WithRegisters : transformer 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. 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, la taille des têtes, etc.)

Ce modèle est également une sous-classe de 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

< >

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

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 image_processor_class. Voir image_processor_class.__call__ pour plus de détails (processor_class utilise image_processor_class 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).
  • 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 masqués.

    Qu'est-ce que les masques d'attention ?

Retourne

ImageClassifierOutput ou tuple(torch.Tensor)

Un ImageClassifierOutput 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 (Dinov2WithRegistersConfig) et des entrées.

La méthode forward de Dinov2WithRegistersForImageClassification 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).

    Poids des attentions après le softmax d'attention, utilisés pour calculer la moyenne pondérée dans les têtes d'auto-attention.

Exemple :

>>> 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])
...
Update on GitHub

←DINOV2 DINOv3→