Transformers documentation

FocalNet

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 2022-03-22 et ajouté à Hugging Face Transformers le 2023-04-23.

FocalNet

Aperçu

Le modèle FocalNet a été proposé dans Focal Modulation Networks par Jianwei Yang, Chunyuan Li, Xiyang Dai, Lu Yuan, Jianfeng Gao. Les FocalNets remplacent complètement l'auto-attention (utilisée dans des modèles comme ViT et Swin) par un mécanisme de modulation focale pour modéliser les interactions entre jetons en vision. Les auteurs affirment que les FocalNets surpassent les modèles basés sur l'auto-attention avec des coûts de calcul similaires sur les tâches de classification d'images, de détection d'objets et de segmentation.

L'abstract de l'article est le suivant :

Nous proposons des réseaux de modulation focale (FocalNets en abrégé), dans lesquels l'auto-attention (SA) est entièrement remplacée par un mécanisme de modulation focale pour modéliser les interactions entre jetons en vision. La modulation focale comprend trois composants : (i) la contextualisation hiérarchique, implémentée à l'aide d'une pile de couches de convolution en profondeur, pour encoder les contextes visuels des courtes aux longues portées, (ii) l'agrégation pilotée par porte pour collecter sélectivement les contextes pour chaque jeton de requête en fonction de son contenu, et (iii) la modulation élément par élément ou la transformation affine pour injecter le contexte agrégé dans la requête. Des expériences étendues montrent que FocalNets surpassent les équivalents SA de l'état de l'art (par exemple, Swin et Focal Transformers) avec des coûts de calcul similaires sur les tâches de classification d'images, de détection d'objets et de segmentation. Plus précisément, FocalNets de taille tiny et base atteignent 82,3 % et 83,9 % de précision top-1 sur ImageNet-1K. Après pré-entraînement sur ImageNet-22K en résolution 224, il atteint 86,5 % et 87,3 % de précision top-1 lors de l'ajustement fin en résolution 224 et 384, respectivement. Lors du transfert vers des tâches en aval, FocalNets présentent une supériorité claire. Pour la détection d'objets avec Mask R-CNN, FocalNet base entraîné avec 1\times surpasse l'équivalent Swin de 2,1 points et dépasse déjà Swin entraîné avec un planning 3\times (49,0 contre 48,5). Pour la segmentation sémantique avec UPerNet, FocalNet base à échelle unique surpasse Swin de 2,4 et bat Swin à multi-échelle (50,5 contre 49,7). En utilisant un grand FocalNet et Mask2former, nous atteignons 58,5 mIoU pour la segmentation sémantique ADE20K, et 57,9 PQ pour la segmentation panoptique COCO. En utilisant un FocalNet huge et DINO, nous avons atteint 64,3 et 64,4 mAP sur COCO minival et test-dev, respectivement, établissant un nouveau SoTA au-dessus de modèles basés sur l'attention beaucoup plus grands comme Swinv2-G et BEIT-3.

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

FocalNetConfig

classe transformers.FocalNetConfig

< >

( 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 = Noneimage_size: int | list[int] | tuple[int, int] = 224patch_size: int | list[int] | tuple[int, int] = 4num_channels: int = 3embed_dim: int = 96use_conv_embed: bool = Falsehidden_sizes: list[int] | tuple[int, ...] = (192, 384, 768, 768)depths: list[int] | tuple[int, ...] = (2, 2, 6, 2)focal_levels: list[int] | tuple[int, ...] = (2, 2, 2, 2)focal_windows: list[int] | tuple[int, ...] = (3, 3, 3, 3)hidden_act: str = 'gelu'mlp_ratio: float = 4.0hidden_dropout_prob: float | int = 0.0drop_path_rate: float | int = 0.1use_layerscale: bool = Falselayerscale_value: float = 0.0001use_post_layernorm: bool = Falseuse_post_layernorm_in_modulation: bool = Falsenormalize_modulator: bool = Falseinitializer_range: float = 0.02layer_norm_eps: float = 1e-05encoder_stride: int = 32_out_features: list[str] | None = None_out_indices: list[int] | None = None )

Paramètres

  • 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 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 96) — Dimension des embeddings et des états cachés.
  • use_conv_embed (bool, facultatif, valeur par défaut False) — Indique s'il faut utiliser un embedding convolutif. Les auteurs ont noté que l'utilisation d'un embedding convolutif améliore généralement les performances, mais il n'est pas utilisé par défaut.
  • hidden_sizes (Union[list[int], tuple[int, ...]], facultatif, par défaut (192, 384, 768, 768)) — Dimension (taille cachée) à chaque étape du modèle.
  • depths (Union[list[int], tuple[int, ...]], facultatif, par défaut (2, 2, 6, 2)) — Profondeur de chaque couche du Transformer.
  • focal_levels (list(int), facultatif, par défaut [2, 2, 2, 2]) — Nombre de niveaux focaux dans chaque couche des différentes étapes de l'encodeur.
  • focal_windows (list(int), facultatif, par défaut [3, 3, 3, 3]) — Taille de la fenêtre focale de chaque couche des étapes respectives de l'encodeur.
  • 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.
  • mlp_ratio (float, facultatif, par défaut 4.0) — Ratio de la dimension cachée du MLP par rapport à la dimension d'embedding.
  • hidden_dropout_prob (float, facultatif, valeur par défaut 0.0) — Probabilité de dropout pour toutes les couches entièrement connectées des embeddings et de l'encodeur.
  • drop_path_rate (Union[float, int], facultatif, par défaut 0.1) — Taux de drop path pour la fusion des patches.
  • use_layerscale (bool, facultatif, valeur par défaut False) — Indique s'il faut utiliser l'échelle de couche dans l'encodeur.
  • layerscale_value (float, facultatif, valeur par défaut 0.0001) — La valeur initiale de l'échelle de couche.
  • use_post_layernorm (bool, facultatif, valeur par défaut False) — Indique s'il faut utiliser la normalisation de couche postérieure dans l'encodeur.
  • use_post_layernorm_in_modulation (bool, facultatif, valeur par défaut False) — Indique s'il faut utiliser la normalisation post-couche dans la couche de modulation.
  • normalize_modulator (bool, facultatif, par défaut False) — Indique s'il faut normaliser le modulateur.
  • 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-05) — L'épsilon utilisé par les couches de normalisation de couche.
  • encoder_stride (int, facultatif, valeur par défaut 32) — Facteur d'augmentation de la résolution spatiale dans la tête du décodeur pour le masquage d'images.

Ceci est la classe de configuration destinée à stocker la configuration d'un FocalNetModel. Elle est utilisée pour instancier un modèle Focalnet 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 microsoft/focalnet-tiny

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 FocalNetConfig, FocalNetModel

>>> # Initializing a FocalNet microsoft/focalnet-tiny style configuration
>>> configuration = FocalNetConfig()

>>> # Initializing a model (with random weights) from the microsoft/focalnet-tiny style configuration
>>> model = FocalNetModel(configuration)

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

FocalNetModel

classe transformers.FocalNetModel

< >

( config: FocalNetConfigadd_pooling_layer = Trueuse_mask_token = False )

Paramètres

  • config (FocalNetConfig) — 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.
  • add_pooling_layer (bool, facultatif, par défaut True) — Indique s'il faut ajouter une couche de pooling
  • use_mask_token (bool, facultatif, par défaut False) — Indique s'il faut utiliser un jeton de masque pour le modélisation d'images masquées.

Le modèle Focalnet 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.BoolTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetModelOutput 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 BitImageProcessor. Voir BitImageProcessor.call() pour plus de détails (processor_class utilise BitImageProcessor pour le traitement des images).
  • bool_masked_pos (torch.BoolTensor de forme (batch_size, num_patches)) — Positions masquées booléennes. Indique quels patches sont masqués (1) et lesquels ne le sont pas (0).
  • output_hidden_states (bool, facultatif) — Indique s'il faut retourner les états cachés de toutes les couches. Voir hidden_states sous les tenseurs retournés pour plus de détails.
  • return_dict (bool, facultatif) — Indique s'il faut retourner un ModelOutput plutôt qu'un simple tuple.

Retourne

FocalNetModelOutput ou tuple(torch.Tensor)

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

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

  • 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 des embeddings initiaux, redimensionnés pour inclure les dimensions spatiales.

Exemple :

FocalNetForMaskedImageModeling

classe transformers.FocalNetForMaskedImageModeling

< >

( config: FocalNetConfig )

Paramètres

  • config (FocalNetConfig) — 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 FocalNet avec un décodeur en tête pour la modélisation d'images masquées.

Cela suit la même implémentation que dans SimMIM.

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.BoolTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetMaskedImageModelingOutput 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 BitImageProcessor. Voir BitImageProcessor.call() pour plus de détails (processor_class utilise BitImageProcessor pour le traitement des images).
  • bool_masked_pos (torch.BoolTensor de forme (batch_size, num_patches)) — Positions masquées booléennes. Indique quels patches sont masqués (1) et lesquels ne le sont pas (0).
  • output_hidden_states (bool, facultatif) — Indique s'il faut retourner les états cachés de toutes les couches. Voir hidden_states sous les tenseurs retournés pour plus de détails.
  • return_dict (bool, facultatif) — Indique s'il faut retourner un ModelOutput plutôt qu'un simple tuple.

Retourne

FocalNetMaskedImageModelingOutput ou tuple(torch.Tensor)

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

La méthode forward de FocalNetForMaskedImageModeling 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 bool_masked_pos est fourni) — Perte de modélisation d'images masquées (MLM).

  • reconstruction (torch.Tensor de forme (batch_size, num_channels, height, width)) — Valeurs de pixels reconstruites.

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

  • 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 des embeddings initiaux, redimensionnés pour inclure les dimensions spatiales.

Exemples :

>>> from transformers import AutoImageProcessor, FocalNetConfig, FocalNetForMaskedImageModeling
>>> 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("microsoft/focalnet-base-simmim-window6-192")
>>> config = FocalNetConfig()
>>> model = FocalNetForMaskedImageModeling(config)

>>> num_patches = (model.config.image_size // model.config.patch_size) ** 2
>>> pixel_values = image_processor(images=image, return_tensors="pt").pixel_values
>>> # create random boolean mask of shape (batch_size, num_patches)
>>> bool_masked_pos = torch.randint(low=0, high=2, size=(1, num_patches)).bool()

>>> outputs = model(pixel_values, bool_masked_pos=bool_masked_pos)
>>> loss, reconstructed_pixel_values = outputs.loss, outputs.logits
>>> list(reconstructed_pixel_values.shape)
[1, 3, 192, 192]

FocalNetForImageClassification

classe transformers.FocalNetForImageClassification

< >

( config: FocalNetConfig )

Paramètres

  • config (FocalNetConfig) — 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 FocalNet avec une tête de classification d'images au sommet (une couche linéaire au-dessus de la sortie agrégée), 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.LongTensor] = Noneoutput_hidden_states: bool | None = Nonereturn_dict: bool | None = None**kwargs ) → FocalNetImageClassifierOutput 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 BitImageProcessor. Voir BitImageProcessor.call() pour plus de détails (processor_class utilise BitImageProcessor 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_hidden_states (bool, facultatif) — Indique s'il faut retourner les états cachés de toutes les couches. Voir hidden_states sous les tenseurs retournés pour plus de détails.
  • return_dict (bool, facultatif) — Indique s'il faut retourner un ModelOutput plutôt qu'un simple tuple.

Retourne

FocalNetImageClassifierOutput ou tuple(torch.Tensor)

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

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

  • 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 des embeddings initiaux, redimensionnés pour inclure les dimensions spatiales.

Exemple :

>>> from transformers import AutoImageProcessor, FocalNetForImageClassification
>>> import torch
>>> from datasets import load_dataset

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

>>> image_processor = AutoImageProcessor.from_pretrained("microsoft/focalnet-tiny")
>>> model = FocalNetForImageClassification.from_pretrained("microsoft/focalnet-tiny")

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