Transformers documentation
FocalNet
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
< source >( 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éfaut224) — La taille (résolution) de chaque image. - patch_size (
Union[int, list[int], tuple[int, int]], facultatif, par défaut4) — La taille (résolution) de chaque patch. - num_channels (
int, facultatif, par défaut3) — Le nombre de canaux d'entrée. - embed_dim (
int, facultatif, par défaut96) — Dimension des embeddings et des états cachés. - use_conv_embed (
bool, facultatif, valeur par défautFalse) — 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éfautgelu) — 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éfaut4.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éfaut0.1) — Taux de drop path pour la fusion des patches. - use_layerscale (
bool, facultatif, valeur par défautFalse) — 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éfautFalse) — Indique s'il faut utiliser la normalisation de couche postérieure dans l'encodeur. - use_post_layernorm_in_modulation (
bool, facultatif, valeur par défautFalse) — Indique s'il faut utiliser la normalisation post-couche dans la couche de modulation. - normalize_modulator (
bool, facultatif, par défautFalse) — Indique s'il faut normaliser le modulateur. - initializer_range (
float, facultatif, par défaut0.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éfaut1e-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.configFocalNetModel
classe transformers.FocalNetModel
< source >( 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éfautTrue) — Indique s'il faut ajouter une couche de pooling - use_mask_token (
bool, facultatif, par défautFalse) — 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
< source >( 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.Tensorde 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_classutilise BitImageProcessor pour le traitement des images). - bool_masked_pos (
torch.BoolTensorde 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. Voirhidden_statessous 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
Moduleplutô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.Tensorde 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.Tensorde forme(batch_size, hidden_size), facultatif, renvoyé lorsqueadd_pooling_layer=Trueest passé) — Pooling moyen de l'état caché de la dernière couche.hidden_states (
tuple[torch.Tensor], facultatif, renvoyé lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.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é lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.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.
FocalNetForMaskedImageModeling
classe transformers.FocalNetForMaskedImageModeling
< source >( 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
< source >( 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.Tensorde 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_classutilise BitImageProcessor pour le traitement des images). - bool_masked_pos (
torch.BoolTensorde 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. Voirhidden_statessous 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
Moduleplutô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.Tensorde forme(1,), facultatif, renvoyé lorsquebool_masked_posest fourni) — Perte de modélisation d'images masquées (MLM).reconstruction (
torch.Tensorde forme(batch_size, num_channels, height, width)) — Valeurs de pixels reconstruites.hidden_states (
tuple[torch.Tensor], facultatif, renvoyé lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.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é lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.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
< source >( 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
< source >( 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.Tensorde 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_classutilise BitImageProcessor pour le traitement des images). - labels (
torch.LongTensorde 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]. Siconfig.num_labels == 1, une perte de régression est calculée (perte du carré moyen). Siconfig.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. Voirhidden_statessous 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
Moduleplutô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.Tensorde forme(1,), facultatif, renvoyé lorsquelabelsest fourni) — Perte de classification (ou de régression si config.num_labels==1).logits (
torch.Tensorde 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é lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.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é lorsqueoutput_hidden_states=Trueest passé ou lorsqueconfig.output_hidden_states=True) — Tuple detorch.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])
...