Transformers documentation

Modèles

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

and get access to the augmented documentation experience

to get started

Modèles

La classe de base PreTrainedModel implémente les méthodes communes pour charger/enregistrer un modèle à partir d'un fichier ou d'un répertoire local, ou à partir d'une configuration de modèle préentraînée fournie par la bibliothèque (téléchargée depuis le Hub de HuggingFace).

PreTrainedModel implémente également quelques méthodes communes à tous les modèles :

  • redimensionner les embeddings de jetons d'entrée lorsque de nouveaux jetons sont ajoutés au vocabulaire

Les autres méthodes communes à chaque modèle sont définies dans ModuleUtilsMixin et GenerationMixin.

PreTrainedModel

classe transformers.PreTrainedModel

< >

( config: PreTrainedConfig*inputs**kwargs )

Classe de base pour tous les modèles.

PreTrainedModel gère le stockage de la configuration des modèles et prend en charge les méthodes de chargement, de téléchargement et d’enregistrement des modèles, ainsi que quelques méthodes communes à tous les modèles :

  • redimensionner les embeddings d'entrée

Attributs de classe (réécrits par les classes dérivées) :

  • config_class (PreTrainedConfig) — Une sous-classe de PreTrainedConfig à utiliser comme classe de configuration pour cette architecture de modèle.
  • base_model_prefix (str) — Une chaîne de caractères indiquant l'attribut associé au modèle de base dans les classes dérivées de la même architecture qui ajoutent des modules au-dessus du modèle de base.
  • main_input_name (str) — Le nom de l'entrée principale du modèle (souvent input_ids pour les modèles NLP, pixel_values pour les modèles de vision et input_values pour les modèles de parole).
  • can_record_outputs (dict) :

push_to_hub

< >

( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )

Paramètres

  • repo_id (str) — Le nom du dépôt vers lequel vous souhaitez pousser votre modèle. Il doit contenir le nom de votre organisation lors d’une poussée vers une organisation donnée.
  • commit_message (str, facultatif) — Message à committer lors de la poussée. La valeur par défaut est "Upload model".
  • commit_description (str, facultatif) — La description du commit qui sera créé
  • private (bool, facultatif) — Indique s'il faut rendre le dépôt privé. Si None (par défaut), le dépôt sera public sauf si le paramètre par défaut de l'organisation est privé. Cette valeur est ignorée si le dépôt existe déjà.
  • token (bool ou str, facultatif) — Le jeton à utiliser comme autorisation bearer HTTP pour les fichiers distants. Si True (par défaut), le jeton généré lors de l’exécution de hf auth login (stocké dans ~/.huggingface) sera utilisé.
  • revision (str, facultatif) — Branche vers laquelle pousser les fichiers téléversés.
  • create_pr (bool, facultatif, par défaut False) — Indique s'il faut créer une PR avec les fichiers téléversés ou effectuer un commit direct.
  • max_shard_size (int ou str, facultatif, par défaut "50GB") — Applicable uniquement aux modèles. La taille maximale d'un point de contrôle avant son fractionnement. Les points de contrôle fractionnés auront chacun une taille inférieure à cette valeur. S'il est exprimé sous forme de chaîne, il doit être composé de chiffres suivis d'une unité (comme "5MB").
  • tags (list[str], facultatif) — Liste des tags à pousser sur le Hub.

Téléchargez le fichier du modèle sur le 🤗 Model Hub.

Exemples :

from transformers import AutoModel

model = AutoModel.from_pretrained("google-bert/bert-base-cased")

# Push the model to your namespace with the name "my-finetuned-bert".
model.push_to_hub("my-finetuned-bert")

# Push the model to an organization with the name "my-finetuned-bert".
model.push_to_hub("huggingface/my-finetuned-bert")

activation_checkpointing_disable

< >

( )

Désactive le checkpointing d'activation pour le modèle actuel.

activation_checkpointing_enable

< >

( activation_checkpointing_kwargs = Noneevery_n_layers: int = 1offload: bool = False )

Paramètres

  • every_n_layers (int, facultatif, valeur par défaut 1) — Effectue un checkpoint uniquement toutes les every_n_layers couches décodeur, en laissant les autres conserver leurs activations. 1 effectue un checkpoint de chaque couche, ce qui correspond au comportement habituel tout-ou-rien. Des valeurs plus élevées sacrifient la mémoire au profit de la vitesse, ce qui est avantageux lorsque la mémoire libérée par le checkpoint complet reste inutilisée.
  • offload (bool, facultatif, par défaut False) — Conserve les activations enregistrées pour le recalcul en mémoire hôte épinglée plutôt que sur l'accélérateur. Cela libère layers x sequence x hidden octets de mémoire de l'appareil, ce qui domine aux longues longueurs de séquence, et impose une copie de l'appareil vers l'hôte dans le calcul avant et une copie de l'hôte vers l'appareil dans le calcul arrière. Les deux copies s'exécutent sur le flux de calcul, ce qui ralentit l'étape.
  • activation_checkpointing_kwargs (dict, facultatif) — Arguments de mot-clé supplémentaires transmis à la fonction torch.utils.checkpoint.checkpoint.

Active le checkpointing d’activation pour le modèle actuel.

Nous passons la méthode __call__ des modules plutôt que forward car __call__ attache tous les hooks du module. https://discuss.pytorch.org/t/any-different-between-model-input-and-model-forward-input/3690/2

add_model_tags

< >

( tags: list[str] | str )

Paramètres

  • tags (Union[list[str], str]) — Les tags souhaités à injecter dans le modèle

Ajoute des balises personnalisées au modèle qui est poussé sur le Hugging Face Hub. N'écrasera pas les balises existantes du modèle.

Exemples :

from transformers import AutoModel

model = AutoModel.from_pretrained("google-bert/bert-base-cased")

model.add_model_tags(["custom", "custom-bert"])

# Push the model to your namespace with the name "my-custom-bert".
model.push_to_hub("my-custom-bert")

can_generate

< >

( ) → bool

Retourne

bool

Si ce modèle peut générer des séquences avec .generate().

Indique si ce modèle peut générer des séquences avec .generate(), à partir de GenerationMixin ou d'une classe ayant une interface similaire.

En interne, pour les classes pour lesquelles cette fonction renvoie True, certaines modifications spécifiques à la génération sont déclenchées : par exemple, l’instance du modèle aura un attribut generation_config renseigné.

cuda

( *args**kwargs )

Valeur factice pour un chemin pointé (par exemple torch.float32) : les chaînes d’accès aux attributs et les appels se comportent comme des décorateurs de pass-through, repr est le chemin pointé, et son utilisation comme classe de base substitue une base type ordinaire (PEP 560 __mro_entries__), de sorte que les vraies sous-classes conservent un métaclasse normal et que inspect.signature lit leur __init__ réel plutôt que celui d’une valeur factice.

déquantiser

< >

( dtype = None )

Déquantiser éventuellement le modèle s'il a été quantisé par une méthode de quantisation prenant en charge la déquantisation.

disable_input_require_grads

< >

( )

Supprime le _require_grads_hook.

enable_input_require_grads

< >

( )

Active les gradients pour les embeddings d'entrée. Cela est utile pour l'ajustement fin des poids d'adaptateurs tout en maintenant les poids du modèle fixes.

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLike | None*model_argsconfig: transformers.configuration_utils.PreTrainedConfig | str | os.PathLike | None = Nonecache_dir: str | os.PathLike | None = Noneignore_mismatched_sizes: bool = Falseforce_download: bool = Falselocal_files_only: bool = Falsetoken: str | bool | None = Nonerevision: str = 'main'use_safetensors: bool | None = Noneweights_only: bool = Truefusion_config: dict[str, bool | dict[str, typing.Any]] | None = Nonedisable_mmap: bool | None = None**kwargs )

Paramètres

  • pretrained_model_name_or_path (str ou os.PathLike, facultatif) — Peut être l'un des éléments suivants :
    • Une chaîne de caractères, l'identifiant du modèle d'un modèle pré-entraîné hébergé dans un dépôt de modèles sur huggingface.co.
    • Chemin vers un répertoire contenant les poids du modèle enregistrés à l’aide de save_pretrained(), par exemple ./my_model_directory/. Les répertoires enregistrés avec save_pretrained(..., distributed_checkpoint=True) sont détectés et chargés avec le checkpointing distribué (DCP), en conservant le maillage et les placements actuels du modèle. Cela nécessite torch>=2.7 et effectue un chargement strict : chaque clé du modèle doit être présente dans le checkpoint.
    • None si vous fournissez à la fois la configuration et le dictionnaire d'état (respectivement avec les arguments par mot-clé config et state_dict).
  • model_args (séquence d’arguments positionnels, facultatif) — Tous les arguments positionnels restants seront transmis à la méthode __init__ du modèle sous-jacent.
  • config (Union[PreTrainedConfig, str, os.PathLike], facultatif) — Peut être soit :

    Configuration du modèle à utiliser à la place d'une configuration chargée automatiquement. La configuration peut être chargée automatiquement lorsque :

    • Le modèle est un modèle fourni par la bibliothèque (chargé avec la chaîne model id d'un modèle pré-entraîné).
    • Le modèle a été enregistré à l'aide de save_pretrained() et est rechargé en fournissant le dossier d'enregistrement.
    • Le modèle est chargé en fournissant un répertoire local en tant que pretrained_model_name_or_path et un fichier JSON de configuration nommé config.json est trouvé dans le répertoire.
  • state_dict (dict[str, torch.Tensor], facultatif) — Un dictionnaire d'état à utiliser à la place d'un dictionnaire d'état chargé depuis un fichier de poids enregistré. Cette option peut être utilisée si vous souhaitez créer un modèle à partir d'une configuration préentraînée mais charger vos propres poids. Dans ce cas, toutefois, vous devriez vérifier si l'utilisation de save_pretrained() et from_pretrained() n'est pas une option plus simple.

    Cette option peut être utilisée si vous souhaitez créer un modèle à partir d'une configuration préentraînée mais charger vos propres poids. Dans ce cas, toutefois, vous devriez vérifier si l'utilisation de save_pretrained() et de from_pretrained() n'est pas une option plus simple.

  • cache_dir (Union[str, os.PathLike], facultatif) — Chemin vers un répertoire dans lequel la configuration d'un modèle pré-entraîné téléchargé doit être mise en cache si le cache standard ne doit pas être utilisé.
  • ignore_mismatched_sizes (bool, facultatif, valeur par défaut False) — Indique s'il faut lever une erreur si certaines des poids du checkpoint n'ont pas la même taille que les poids du modèle (par exemple, si vous instanciez un modèle avec 10 étiquettes à partir d'un checkpoint avec 3 étiquettes).
  • force_download (bool, facultatif, par défaut False) — Indique s'il faut forcer le (re)téléchargement des poids du modèle et des fichiers de configuration, en ignorant les versions mises en cache si elles existent.
  • proxies (dict[str, str], facultatif) — Un dictionnaire de serveurs proxy à utiliser par protocole ou point de terminaison, par exemple {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Les proxys sont utilisés pour chaque requête.
  • output_loading_info(bool, facultatif, par défaut False) — Indique s'il faut également retourner un dictionnaire contenant les clés manquantes, les clés inattendues et les messages d'erreur.
  • local_files_only(bool, facultatif, valeur par défaut False) — Indique s'il faut uniquement consulter les fichiers locaux (c'est-à-dire ne pas tenter de télécharger le modèle).
  • token (str ou bool, facultatif) — Le jeton à utiliser comme autorisation bearer HTTP pour les fichiers distants. Si True, ou non spécifié, utilisera le jeton généré lors de l’exécution de hf auth login (stocké dans ~/.huggingface).
  • revision (str, facultatif, par défaut "main") — La version spécifique du modèle à utiliser. Il peut s'agir d'un nom de branche, d'un nom de tag ou d'un identifiant de commit, car nous utilisons un système basé sur git pour stocker les modèles et autres artefacts sur huggingface.co, donc revision peut être n'importe quel identifiant autorisé par git.

    Pour tester une pull request que vous avez créée sur le Hub, vous pouvez passer revision="refs/pr/<pr_number>".

  • attn_implementation (str, facultatif) — L'implémentation de l'attention à utiliser dans le modèle (le cas échéant). Peut être l'une des valeurs suivantes :

    Accepter les références de noyau HF sous la forme :

    /[@][:]
    • et sont des séquences quelconques ne contenant ni « / » ni « : ».
    • « @ » est facultatif (branche, étiquette ou commit-ish), par exemple « @main », « @v1.2.0 », « @abc123 ».
    • ”:” est facultatif et permet de sélectionner une fonction dans le dépôt du noyau.
    • Les deux options peuvent apparaître ensemble et uniquement dans cet ordre : @revision d'abord, puis :kernel_name.
    • Nous autorisons intentionnellement un préfixe initial « | » (par exemple, « flash|… ») car le code le supprime avant le chargement ; le caractère « | » n’est pas exclu dans les classes de caractères ici.

    Exemples correspondants : “org/model” “org/model@main” “org/model:custom_kernel” “org/model@v1.2.3:custom_kernel”

  • experts_implementation (str, facultatif) — Implémentation des experts à utiliser dans le modèle (le cas échéant). Peut être l'une des valeurs suivantes :

    Par défaut, si le modèle le prend en charge, "grouped_mm" sera utilisé. Sinon, la valeur par défaut est l'implémentation manuelle "eager".

Paramètres pour l'inférence de grands modèles

  • dtype (str ou torch.dtype, facultatif, par défaut "auto") — Remplace la valeur par défaut de torch_dtype et charge le modèle avec un dtype. Les différentes options sont les suivantes :
    1. torch.float16 ou torch.bfloat16 ou torch.float : charge dans un dtype spécifié, en ignorant le config.dtype du modèle s’il existe. Si non spécifié

      • le modèle sera chargé en torch.float (fp32).
    2. "auto" - Une entrée dtype ou torch_dtype dans le fichier config.json du modèle sera tentée d’être utilisée. Si cette entrée n’est pas trouvée, on vérifie ensuite le dtype du premier poids du point de contrôle qui est de type à virgule flottante et on l’utilise comme dtype. Cela chargera le modèle en utilisant le dtype dans lequel il a été enregistré à la fin de l’entraînement. Il ne peut pas servir d’indicateur de la façon dont le modèle a été entraîné. Car il aurait pu être entraîné dans l’un des dtypes de demi-précision, mais enregistré en fp32.

    3. Une chaîne de caractères valide pour torch.dtype. Par exemple, « float32 » charge le modèle en torch.float32, « float16 » en torch.float16, etc.

    Pour certains modèles, le dtype dans lequel ils ont été entraînés est inconnu - vous pouvez essayer de consulter le papier du modèle ou contacter les auteurs et leur demander d'ajouter ces informations à la carte du modèle et d'insérer l'entrée dtype ou torch_dtype dans config.json sur le hub.

  • device_map (str ou dict[str, Union[int, str, torch.device]] ou int ou torch.device, facultatif) — Une carte qui spécifie où chaque sous-module doit être placé. Il n'est pas nécessaire de la préciser pour chaque nom de paramètre/buffer, dès qu'un nom de module est inclus, tous ses sous-modules seront envoyés sur le même appareil. Si nous ne passons que l'appareil (e.g., "cpu", "cuda:1", "mps", ou un rang ordinal de GPU comme 1) sur lequel le modèle sera alloué, la carte d'appareils mapera l'ensemble du modèle sur cet appareil. Passer device_map = 0 signifie placer le modèle entier sur le GPU 0.

    Pour que Accelerate calcule automatiquement le device_map le plus optimisé, définissez device_map="auto". Pour plus d'informations sur chaque option, consultez concevoir une carte de périphériques.

  • max_memory (Dict, facultatif) — Un dictionnaire associant un identifiant d’appareil à la mémoire maximale à utiliser si device_map est employé. Par défaut, la valeur est la mémoire maximale disponible pour chaque GPU et la RAM CPU disponible si non définie.
  • distributed_config (DistributedConfig, facultatif) — Configuration pour le chargement distribué natif avec parallélisme de tenseurs ou FSDP2. Passez DistributedConfig(tp_size=N) pour utiliser le plan de parallélisme de tenseurs prédéfini d’un modèle, DistributedConfig(tp_plan=...) pour spécifier un plan de parallélisme de tenseurs, ou DistributedConfig(fsdp_size=N) pour FSDP2. Nécessite torchrun et un groupe de processus initialisé lorsque tp_size > 1 ou fsdp_size > 1. Mutuellement exclusif avec device_map.
  • device_mesh (torch.distributed.DeviceMesh, facultatif) — Un mesh de dispositifs torch. S’il n’est pas fourni, la taille du monde est utilisée par défaut. Utilisé uniquement pour le parallélisme de tenseurs pour le moment. S’il est fourni, il doit contenir une dimension nommée "tp" s’il est de dimension supérieure à 1 ; cette dimension sera utilisée pour le parallélisme de tenseurs.
  • offload_folder (str ou os.PathLike, facultatif) — Si la device_map contient la valeur "disk", le dossier où les poids seront déchargés.
  • offload_buffers (bool, facultatif) — Indique s'il faut décharger les tampons avec les paramètres du modèle.
  • quantization_config (Union[QuantizationConfigMixin,Dict], facultatif) — Un dictionnaire de paramètres de configuration ou un objet QuantizationConfigMixin pour la quantification (par exemple bitsandbytes, gptq).
  • subfolder (str, facultatif, par défaut "") — Si les fichiers pertinents se trouvent dans un sous-dossier du dépôt de modèle sur huggingface.co, vous pouvez spécifier le nom du dossier ici.
  • variant (str, facultatif) — Si spécifié, charge les poids depuis le nom de fichier variant, par ex. pytorch_model..bin.
  • use_safetensors (bool, facultatif, valeur par défaut None) — Indique s'il faut ou non utiliser des points de contrôle safetensors. La valeur par défaut est None. Si cette valeur n'est pas spécifiée et que safetensors n'est pas installé, elle est définie sur False.
  • weights_only (bool, facultatif, valeur par défaut True) — Indique si le dépickler doit être restreint au chargement de tenseurs, de types primitifs, de dictionnaires et de tout type ajouté via torch.serialization.add_safe_globals(). Lorsqu’il est défini sur False, il est possible de charger les poids des sous-classes de tenseurs enveloppés.
  • disable_mmap (bool, facultatif) — Indique s'il faut désactiver le mappage mémoire lors du chargement des points de contrôle safetensors. Lorsque la valeur est None (par défaut), la détection automatique définit la valeur à True si le point de contrôle se trouve sur un système de fichiers FUSE hf-mount (utilisé par HF Spaces/Endpoints), car le mappage mémoire combiné aux défauts de page parallèles peut provoquer un blocage. Lorsque la valeur est True, les fichiers sont entièrement lus en mémoire et analysés avec safetensors.torch.load. Lorsque la valeur est False, le chargeur par défaut basé sur le mappage mémoire est toujours utilisé.
  • fusion_config (dict[str, bool | dict[str, Any]], facultatif) — Configuration de fusion facultative appliquée avant l’instanciation du modèle. Chaque clé active une famille de fusion et sa valeur peut être True pour activer cette fusion avec les options par défaut, ou un dictionnaire d’options spécifiques à la famille. Par exemple, {"patch_embeddings": True} active la fusion des embeddings de patch. Cela ne doit être utilisé que comme optimisation d’inférence, car cela peut légèrement modifier les sorties. Si omis, from_pretrained() utilise config.fusion_config en repli lorsque celui-ci est disponible. Consultez le guide de correspondance des fusions dans docs/source/en/fusion_mapping.md pour plus de détails.
  • key_mapping (`dict[str, str], facultatif) — Une correspondance potentielle des noms de poids si vous utilisez un modèle sur le Hub qui est compatible avec une architecture Transformers, mais qui n’a pas été converti en conséquence.
  • kwargs (dictionnaire restant d'arguments nommés, facultatif) — Peut être utilisé pour mettre à jour l'objet de configuration (après son chargement) et initialiser le modèle (par ex., output_attentions=True). Se comporte différemment selon qu'une config est fournie ou chargée automatiquement :
    • Si une configuration est fournie avec config, **kwargs sera transmis directement à la méthode __init__ du modèle sous-jacent (nous supposons que toutes les mises à jour pertinentes de la configuration ont déjà été effectuées)
    • Si aucune configuration n’est fournie, kwargs est d’abord transmis à la fonction d’initialisation de la classe de configuration (from_pretrained()). Chaque clé de kwargs qui correspond à un attribut de configuration est utilisée pour remplacer ledit attribut par la valeur kwargs fournie. Les clés restantes qui ne correspondent à aucun attribut de configuration sont transmises à la fonction __init__ du modèle sous-jacent.

Instanciez un modèle pytorch pré-entraîné à partir d'une configuration de modèle pré-entraîné.

Le modèle est défini par défaut en mode d'évaluation à l'aide de model.eval() (les modules Dropout sont désactivés). Pour entraîner le modèle, vous devez d'abord le remettre en mode d'entraînement avec model.train().

L'avertissement Weights from XXX not initialized from pretrained model signifie que les poids de XXX ne sont pas pré-entraînés avec le reste du modèle. Il vous incombe d'entraîner ces poids avec une tâche de fine-tuning en aval.

L'avertissement Weights from XXX not used in YYY signifie que la couche XXX n'est pas utilisée par YYY, ces poids sont donc ignorés.

Activez le mode spécial « offline-mode » pour utiliser cette méthode dans un environnement protégé par un pare-feu.

Exemples :

>>> from transformers import BertConfig, BertModel

>>> # Download model and configuration from huggingface.co and cache.
>>> model = BertModel.from_pretrained("google-bert/bert-base-uncased")
>>> # Model was saved using *save_pretrained('./test/saved_model/')* (for example purposes, not runnable).
>>> model = BertModel.from_pretrained("./test/saved_model/")
>>> # Update configuration during loading.
>>> model = BertModel.from_pretrained("google-bert/bert-base-uncased", output_attentions=True)
>>> assert model.config.output_attentions == True

get_compiled_call

< >

( compile_config: transformers.generation.configuration_utils.CompileConfig | None )

Retourne une version compilée avec torch.compile de self.__call__. Cela est utile pour choisir dynamiquement entre forward non compilé/compilé pendant l’inférence, en particulier pour basculer entre le préremplissage (où nous ne voulons pas utiliser la version compilée afin d’éviter de recalculer le graphe avec de nouvelles formes) et le décodage itératif (où nous voulons les accélérations de la version compilée avec des formes statiques).

get_decoder

< >

( )

Recherche au mieux du module decoder.

Ordre des tentatives (couvre ~85 % des usages actuels) :

  1. self.decoder/self.language_model/self.text_model
  2. self.base_model (de nombreux wrappers stockent le décodeur ici)
  3. self.base_model.get_decoder() (enveloppes imbriquées)
  4. fallback : lever une exception pour les quelques modèles exotiques qui nécessitent une règle sur mesure

get_encoder

< >

( modality: str | None = None )

Recherche au mieux du module encoder. Si l'argument modality est fourni, elle recherche un encodeur spécifique à la modalité dans les modèles multimodaux (par ex. « image_encoder ») Par défaut, la fonction renvoie l'encodeur de texte du modèle s'il en existe un, et sinon renvoie self.

Les valeurs possibles de modality sont « image », « video » et « audio ».

get_expanded_tied_weights_keys

< >

( all_submodels: bool = False )

Retourne les clés de poids liés développées (au cas où elles contiennent des modules ou des motifs regex) uniquement pour le modèle actuel, ou récursivement pour tous les sous-modèles si all_submodels=True (c’est-à-dire qu’il réexaminera les valeurs de configuration pour tous les sous-modèles).

Pour la quasi-totalité des modèles, il suffit de lier les embeddings, de sorte que le modèle possède une propriété interne _tied_weights_keys = {"lm_head.weight": "model.embed_tokens.weight"}. Dans ce cas, la correspondance est déjà « développée », c'est-à-dire qu'elle contient déjà les paramètres complets, et cette fonction renverra simplement une copie de la propriété. Pour des motifs plus complexes, par exemple pour DFineForObjectDetection, nous avons l'attribut suivant

_tied_weights_keys = {
    r"bbox_embed.(?![0])\d+": "bbox_embed.0",
    r"class_embed.(?![0])\d+": "class_embed.0",
    "model.decoder.class_embed": "class_embed",
    "model.decoder.bbox_embed": "bbox_embed",
}
In this case, the function looks up all the model's parameters and buffers, and matches all the params,

retournant ce qui suit :

{
    'bbox_embed.1.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'bbox_embed.1.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    'bbox_embed.1.layers.1.bias': 'bbox_embed.0.layers.1.bias',
    'bbox_embed.1.layers.1.weight': 'bbox_embed.0.layers.1.weight',
    'bbox_embed.1.layers.2.bias': 'bbox_embed.0.layers.2.bias',
    'bbox_embed.1.layers.2.weight': 'bbox_embed.0.layers.2.weight',
    'bbox_embed.2.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'bbox_embed.2.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    ...
    'class_embed.1.bias': 'class_embed.0.bias',
    'class_embed.1.weight': 'class_embed.0.weight',
    'class_embed.2.bias': 'class_embed.0.bias',
    'class_embed.2.weight': 'class_embed.0.weight',
    ...
    'model.decoder.class_embed.0.bias': 'class_embed.0.bias',
    'model.decoder.class_embed.0.weight': 'class_embed.0.weight',
    'model.decoder.class_embed.1.bias': 'class_embed.0.bias',
    'model.decoder.class_embed.1.weight': 'class_embed.0.weight',
    ...
    'model.decoder.bbox_embed.0.layers.0.bias': 'bbox_embed.0.layers.0.bias',
    'model.decoder.bbox_embed.0.layers.0.weight': 'bbox_embed.0.layers.0.weight',
    'model.decoder.bbox_embed.0.layers.1.bias': 'bbox_embed.0.layers.1.bias',
    'model.decoder.bbox_embed.0.layers.1.weight': 'bbox_embed.0.layers.1.weight',
    ...
}
i.e. all the parameters matching the regex and modules patterns in `_tied_weights_keys`

get_experts_implementation

< >

( )

Retourne l’implémentation des experts de ce modèle et de ses sous-modèles, sous forme d’un dict au format accepté par set_experts_implementation ("" pour ce modèle, et une entrée par sous_configuration). C’est l’opération inverse de set_experts_implementation, par exemple pour capturer l’implémentation actuelle et la restaurer ultérieurement.

get_memory_footprint

< >

( return_buffers = True )

Paramètres

  • return_buffers (bool, facultatif, par défaut True) — Indique s'il faut inclure la taille des tenseurs de tampon dans le calcul de l'empreinte mémoire. Les tampons sont des tenseurs qui ne nécessitent pas de gradients et qui ne sont pas enregistrés en tant que paramètres. Par exemple, la moyenne et l'écart-type dans les couches de normalisation par lot. Voir : https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

Obtenir l’empreinte mémoire d’un modèle. Cette opération renvoie l’empreinte mémoire du modèle actuel en octets. Utile pour mesurer l’empreinte mémoire du modèle actuel et concevoir des tests. Solution inspirée des discussions PyTorch : https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

get_parameter_or_buffer

< >

( target: str )

Retourne le paramètre ou le tampon indiqué par target s'il existe, sinon lève une erreur. Cette fonction combine get_parameter() et get_buffer() en une seule fonction pratique. Si la cible est un attribut _extra_state, elle retourne l'état supplémentaire fourni par le module. Notez que cela ne fonctionne que si target est une feuille du modèle.

gradient_checkpointing_disable

< >

( )

Alias obsolète de activation_checkpointing_disable(), sera supprimé dans la v6.

gradient_checkpointing_enable

< >

( gradient_checkpointing_kwargs = None**kwargs )

Alias obsolète de activation_checkpointing_enable(), sera supprimé dans la v6.

init_weights

< >

( )

Initialiser et lier les poids si nécessaire. Si vous utilisez un PreTrainedModel personnalisé, vous devez implémenter toute logique d’initialisation dans _init_weights.

initialize_weights

< >

( )

Cela équivaut à appeler self.apply(self._initialize_weights), mais gère correctement les modèles composites. Cette fonction dispatche dynamiquement la fonction init_weights appropriée aux modules au fur et à mesure que nous avançons dans le graphe de modules le long de la récursion. Elle peut gérer un nombre arbitraire de sous-modèles. Sans elle, chaque modèle composite devrait récursiver une seconde fois sur tous les sous-modèles explicitement dans le _init_weights le plus externe, ce qui est extrêmement sujet aux erreurs et inefficace.

is_custom_code

< >

( )

Indique si le modèle actuel est du code personnalisé, c'est-à-dire soit du code chargé depuis le hub, soit défini dans un module/session spécifique à l'utilisateur.

is_remote_code

< >

( )

Indique si le modèle actuel est un code personnalisé, c'est-à-dire un code chargé depuis le hub, ou une classe que nous venons d'enregistrer via register_for_auto_class.

mark_tied_weights_as_initialized

< >

( loading_info )

Ajoute le drapeau _is_hf_initialized sur les paramètres qui seront liés, afin d'éviter de les initialiser ultérieurement, puisqu'ils seront de toute façon liés (écrasés). C'est très important car la plupart des embeddings sont liés, et ce sont de très gros paramètres (les vocabulaires font souvent 256k), de sorte que l'exécution des initialisations sur eux est très coûteuse.

named_non_persistent_buffers

< >

( recurse: bool = Trueremove_duplicate: bool = True )

Similaire à named_buffers, mais ne renvoie que les tampons non persistants. C’est pratique car il n’est pas parfaitement évident de savoir s’ils sont persistants ou non.

post_init

< >

( )

Une méthode exécutée à la fin de l’initialisation de chaque modèle Transformer, afin d’exécuter le code qui nécessite que les modules du modèle soient correctement initialisés (comme l’initialisation des poids). Elle est également utilisée pour obtenir correctement toutes les propriétés statiques (plans de parallélisme, tied_weights_keys, _keep_in_fp32_modules, etc.) dans le cas des modèles composites (c’est-à-dire que le modèle de niveau supérieur doit connaître ces propriétés à partir de ses enfants).

register_for_auto_class

< >

( auto_class = 'AutoModel' )

Paramètres

  • auto_class (str ou type, facultatif, par défaut "AutoModel") — La classe auto avec laquelle enregistrer ce nouveau modèle.

Enregistrez cette classe avec une classe auto donnée. Cette opération ne doit être utilisée que pour les modèles personnalisés, car ceux de la bibliothèque sont déjà associés à une classe auto.

resize_token_embeddings

< >

( new_num_tokens: int | None = Nonepad_to_multiple_of: int | None = Nonemean_resizing: bool = True ) → torch.nn.Embedding

Paramètres

  • new_num_tokens (int, facultatif) — Le nouveau nombre de jetons dans la matrice d’incorporation. Augmenter la taille ajoute de nouveaux vecteurs initialisés à la fin. Réduire la taille supprime des vecteurs à partir de la fin. S’il n’est pas fourni ou vaut None, renvoie simplement un pointeur vers le module torch.nn.Embedding des jetons d’entrée du modèle sans rien faire.
  • pad_to_multiple_of (int, facultatif) — Si défini, la matrice d'incorporation sera rembourdée jusqu'à un multiple de la valeur fournie. Si new_num_tokens est défini sur None , seule l'incorporation sera rembourdée jusqu'à un multiple de pad_to_multiple_of.

    Ceci est particulièrement utile pour permettre l'utilisation des Tensor Cores sur le matériel NVIDIA avec une capacité de calcul >= 7.5 (Volta), ou sur les TPU qui bénéficient d'avoir des longueurs de séquence qui sont un multiple de 128. Pour plus de détails à ce sujet, ou pour de l'aide sur le choix de la valeur correcte pour le redimensionnement, consultez ce guide : https://docs.nvidia.com/deeplearning/performance/dl-performance-matrix-multiplication/index.html#requirements-tc

  • mean_resizing (bool) — Indique s'il faut initialiser les embeddings ajoutés à partir d'une distribution normale multivariée ayant la moyenne et la covariance des anciens embeddings, ou s'il faut les initialiser avec une distribution normale ayant une moyenne nulle et un écart-type égal à config.initializer_range.

    Définir mean_resizing sur True est utile lors de l’augmentation de la taille des embeddings des modèles de langage causaux, car les probabilités des jetons générés ne seront pas affectées par les embeddings ajoutés, puisque l’initialisation des nouveaux embeddings avec la moyenne des anciens embeddings réduira la divergence de KL entre la probabilité du jeton suivant avant et après l’ajout des nouveaux embeddings. Consultez cet article pour plus d’informations : https://nlp.stanford.edu/~johnhew/vocab-expansion.html

Retourne

torch.nn.Embedding

Pointeur vers le module d'embeddings des jetons d'entrée du modèle.

Redimensionne la matrice des embeddings de jetons d'entrée du modèle si new_num_tokens != config.vocab_size.

Gère le rattachement des poids des embeddings par la suite si la classe du modèle dispose d'une méthode tie_weights().

save_pretrained

< >

( save_directory: str | os.PathLikeis_main_process: bool = Truestate_dict: dict | None = Nonepush_to_hub: bool = Falsemax_shard_size: int | str = '50GB'variant: str | None = Nonetoken: str | bool | None = Nonesave_peft_format: bool = Truesave_original_format: bool = Truedistributed_checkpoint: bool = False**kwargs )

Paramètres

  • save_directory (str ou os.PathLike) — Répertoire de destination. Sera créé s'il n'existe pas.
  • is_main_process (bool, facultatif, par défaut True) — Indique si le processus qui appelle cette fonction est le processus principal ou non. Utile lors d'un entraînement distribué, par exemple sur des TPU, où il est nécessaire d'appeler cette fonction sur tous les processus. Dans ce cas, définissez is_main_process=True uniquement sur le processus principal afin d'éviter les conditions de course.
  • state_dict (dictionnaire imbriqué de torch.Tensor) — Le dictionnaire d'état du modèle à enregistrer. Par défaut, il vaut self.state_dict(), mais il peut être utilisé pour n'enregistrer que certaines parties du modèle ou si des précautions particulières doivent être prises lors de la récupération du dictionnaire d'état d'un modèle (comme lors de l'utilisation du parallélisme de modèle).
  • push_to_hub (bool, facultatif, par défaut False) — Indique s'il faut ou non pousser votre modèle sur le hub de modèles Hugging Face après l'avoir enregistré. Vous pouvez spécifier le dépôt auquel vous souhaitez pousser avec repo_id (par défaut, il s'agit du nom de save_directory dans votre espace de noms).
  • max_shard_size (int ou str, facultatif, défaut : "50GB") — Taille maximale d'un checkpoint avant son fractionnement. Les shards du checkpoint auront chacun une taille inférieure à cette valeur. S'il est exprimé sous forme de chaîne, il doit être composé de chiffres suivis d'une unité (comme "5MB").

    Si un seul poids du modèle est plus grand que max_shard_size, il sera placé dans sa propre partition de point de contrôle, qui sera plus grande que max_shard_size.

  • variant (str, facultatif) — Si spécifié, les poids sont enregistrés au format model..safetensors.
  • token (str ou bool, facultatif) — Le jeton à utiliser comme autorisation bearer HTTP pour les fichiers distants. Si True, ou non spécifié, utilisera le jeton généré lors de l’exécution de hf auth login (stocké dans ~/.huggingface).
  • save_peft_format (bool, facultatif, valeur par défaut True) — Pour la compatibilité ascendante avec la bibliothèque PEFT, si des poids d’adaptateurs sont attachés au modèle, toutes les clés du dictionnaire d’état des adaptateurs doivent être préfixées par base_model.model. Les utilisateurs avancés peuvent désactiver ce comportement en définissant save_peft_format sur False.
  • save_original_format (bool, facultatif, valeur par défaut True) — Pour la compatibilité ascendante avec les versions précédentes de transformers, vous pouvez enregistrer le point de contrôle avec sa correspondance inverse. La correspondance inverse doit exister même si le modèle a été chargé à partir d'un point de contrôle legacy None.
  • distributed_checkpoint (bool, facultatif, valeur par défaut False) — Lors de l’enregistrement d’un modèle sharded FSDP ou TP, écrit les safetensors avec le checkpointing distribué (DCP) au lieu de rassembler d’abord les poids sur le CPU. Chaque rang doit appeler cette méthode. Si False, les poids sont rassemblés sur le CPU sur le rang 0 via gather_full_state_dict avant l’écriture. Cette option est destinée uniquement à l’enregistrement et à la reprise de l’entraînement ; définissez-la sur False si vous souhaitez bénéficier de toutes les fonctionnalités de save_pretrained. Avec push_to_hub=True, le rang 0 consolide le checkpoint dans un sous-répertoire consolidated/ et téléverse ce répertoire. Nécessite torch>=2.7.
  • kwargs (dict[str, Any], facultatif) — Arguments supplémentaires passés à la méthode push_to_hub().

Enregistrer un modèle et son fichier de configuration dans un répertoire, afin qu’il puisse être rechargé à l’aide de la méthode de classe from_pretrained().

set_attn_implementation

< >

( attn_implementation: str | dictallow_all_kernels: bool = False )

Paramètres

  • attn_implementation (str ou dict) — L’implémentation de l’attention à définir pour ce modèle. Elle peut être soit une str, auquel cas elle sera distribuée à tous les sous-modèles si pertinent, soit un dict dont les clés sont les noms des sub_configs, auquel cas chaque sous-modèle distribuera la valeur correspondante (à lui-même et à tous les sous-modèles imbriqués en son sein). Une valeur peut elle-même être un dict au même format, pour cibler les sub_configs de ce sous-modèle (comme lors de l’initialisation d’un config avec un dict attn_implementation imbriqué).
  • allow_all_kernels (bool, optionnel) — Indique s'il faut charger des kernels depuis des dépôts hub non vérifiés, si attn_implementation est un kernel personnalisé en dehors du dépôt hub kernels-community.

Définissez le attn_implementation demandé pour ce modèle.

set_decoder

< >

( decoder )

Définisseur symétrique. Reprend la logique de recherche utilisée dans get_decoder.

set_encoder

< >

( encodermodality: str | None = None )

Définisseur symétrique. Reprend la logique de recherche utilisée dans get_encoder.

set_experts_implementation

< >

( experts_implementation: str | dict )

Paramètres

  • experts_implementation (str ou dict) — L’implémentation des experts à définir pour ce modèle. Elle peut être soit une str, auquel cas elle sera distribuée à tous les sous-modèles si pertinent, soit un dict dont les clés sont les noms des sub_configs, auquel cas chaque sous-modèle distribuera la valeur correspondante.

Définissez l'experts_implementation demandé pour ce modèle.

set_use_kernels

< >

( use_kernelskernel_config: transformers.utils.kernel_config.KernelConfig | None = Nonemode: Mode | None = None )

Paramètres

  • use_kernels (bool) — Indique s'il faut utiliser la bibliothèque kernels pour kerneliser certaines couches du modèle.
  • kernel_config (KernelConfig, facultatif) — La configuration du noyau à utiliser pour kerneliser le modèle. Si None, la correspondance de noyaux par défaut sera utilisée.
  • mode (Mode, facultatif) — Le mode à appliquer lors de kernelize. Facultatif, par défaut il est défini sur le mode d’entraînement ou d’inférence en fonction du drapeau interne training.

Définir si la bibliothèque kernels doit être utilisée pour kerneliser certaines couches du modèle.

tie_weights

< >

( missing_keys: set[str] | None = Nonerecompute_mapping: bool = True )

Lier les poids du modèle. Si recompute_mapping=False (valeur par défaut lors d'un appel interne), il s'appuiera sur l'attribut model.all_tied_weights_keys, contenant la correspondance {target: source} pour les paramètres liés. Si recompute_mapping=True, il réexaminera tous les sous-modèles internes et leur configuration pour déterminer les paramètres qui doivent être liés. C'est la valeur par défaut lorsque model.tie_weights() est appelé seul, en dehors de __init__ et de from_pretrained, au cas où les valeurs de la configuration auraient été modifiées ailleurs.

Notez que lors de from_pretrained, le rattachement est symétrique : si la correspondance indique « tie target -> source » mais que source est absent du point de contrôle tandis que target existe, nous inversions source et cible afin de pouvoir toujours rattacher tout au paramètre qui existe réellement.

à

( *args**kwargs )

Valeur factice pour un chemin pointé (par exemple torch.float32) : les chaînes d’accès aux attributs et les appels se comportent comme des décorateurs de pass-through, repr est le chemin pointé, et son utilisation comme classe de base substitue une base type ordinaire (PEP 560 __mro_entries__), de sorte que les vraies sous-classes conservent un métaclasse normal et que inspect.signature lit leur __init__ réel plutôt que celui d’une valeur factice.

warn_if_padding_and_no_attention_mask

< >

( input_idsattention_mask )

Affiche un avertissement unique si les input_ids semblent contenir du padding et qu'aucun masque d'attention n'a été fourni.

Les modèles personnalisés doivent également inclure _supports_assign_param_buffer, qui détermine si l'initialisation superfast peut s'appliquer au modèle en question. Un signe que votre modèle en a besoin est l'échec de test_save_and_load_from_pretrained. Dans ce cas, définissez cette valeur sur False.

ModuleUtilsMixin

classe transformers.modeling_utils.ModuleUtilsMixin

< >

( )

Quelques utilitaires pour torch.nn.Modules, à utiliser en tant que mixin.

num_parameters

< >

( only_trainable: bool = Falseexclude_embeddings: bool = False ) → int

Paramètres

  • only_trainable (bool, facultatif, par défaut False) — Indique s'il faut renvoyer uniquement le nombre de paramètres entraînables
  • exclude_embeddings (bool, facultatif, par défaut False) — Indique s'il faut renvoyer uniquement le nombre de paramètres non liés aux embeddings

Retourne

int

Le nombre de paramètres.

Obtenir le nombre de paramètres (facultativement, entraînables ou non-embeddings) du module.

Pousser vers le Hub

classe transformers.utils.PushToHubMixin

< >

( )

Un Mixin contenant la fonctionnalité permettant de pousser un modèle ou un tokenizer vers le hub.

push_to_hub

< >

( repo_id: strcommit_message: str | None = Nonecommit_description: str | None = Noneprivate: bool | None = Nonetoken: bool | str | None = Nonerevision: str | None = Nonecreate_pr: bool = Falsemax_shard_size: int | str | None = '50GB'tags: list[str] | None = None )

Paramètres

  • repo_id (str) — Le nom du dépôt vers lequel vous souhaitez pousser votre {object}. Il doit contenir le nom de votre organisation lors d’une poussée vers une organisation donnée.
  • commit_message (str, facultatif) — Message à committer lors de la poussée. La valeur par défaut est "Upload {object}".
  • commit_description (str, facultatif) — La description du commit qui sera créé
  • private (bool, facultatif) — Indique s'il faut rendre le dépôt privé. Si None (par défaut), le dépôt sera public sauf si le paramètre par défaut de l'organisation est privé. Cette valeur est ignorée si le dépôt existe déjà.
  • token (bool ou str, facultatif) — Le jeton à utiliser comme autorisation bearer HTTP pour les fichiers distants. Si True (par défaut), le jeton généré lors de l’exécution de hf auth login (stocké dans ~/.huggingface) sera utilisé.
  • revision (str, facultatif) — Branche vers laquelle pousser les fichiers téléversés.
  • create_pr (bool, facultatif, par défaut False) — Indique s'il faut créer une PR avec les fichiers téléversés ou effectuer un commit direct.
  • max_shard_size (int ou str, facultatif, par défaut "50GB") — Applicable uniquement aux modèles. La taille maximale d'un point de contrôle avant son fractionnement. Les points de contrôle fractionnés auront chacun une taille inférieure à cette valeur. S'il est exprimé sous forme de chaîne, il doit être composé de chiffres suivis d'une unité (comme "5MB").
  • tags (list[str], facultatif) — Liste des tags à pousser sur le Hub.

Téléversez {object_files} sur le 🤗 Model Hub.

Exemples :

from transformers import {object_class}

{object} = {object_class}.from_pretrained("google-bert/bert-base-cased")

# Push the {object} to your namespace with the name "my-finetuned-bert".
{object}.push_to_hub("my-finetuned-bert")

# Push the {object} to an organization with the name "my-finetuned-bert".
{object}.push_to_hub("huggingface/my-finetuned-bert")
Update on GitHub