Transformers documentation

Cartographie de fusion (fonctionnalité expérimentale)

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Cartographie de fusion (fonctionnalité expérimentale)

La fusion mapping offre une option facultative pour remplacer les sous-modules d'un modèle au moment du chargement, tout en conservant le format de point de contrôle d'origine.

Il s'appuie sur :

Le mappage de fusion est une fonctionnalité de chargement expérimentale. Il modifie la structure des modules d'exécution et peut affecter le comportement du modèle. Utilisez-le uniquement si vous souhaitez explicitement une disposition d'exécution fusionnée.

Démarrage rapide

La fusion est activée via from_pretrained() avec fusion_config :

from transformers import AutoModelForImageTextToText


model = AutoModelForImageTextToText.from_pretrained(
    "Qwen/Qwen2-VL-2B-Instruct",
    fusion_config={"patch_embeddings": True},
)

Par défaut, aucune fusion n'est appliquée. Si fusion_config est stocké dans la configuration du modèle, from_pretrained() le réutilisera automatiquement.

Fonctionnement

L'enregistrement de la fusion a lieu avant l'instantiation du modèle :

  1. from_pretrained() utilise l'argument explicite fusion_config ou se rabat sur config.fusion_config.
  2. Le registre de fusion valide les noms de fusion demandés.
  3. Chaque fusion activée initialise métadonnées la classe de modèle cible, filtre éventuellement les modules candidats par nom et utilise is_fusable(...) pour découvrir les classes de modules compatibles.
  4. Les classes de remplacement fusionnées sont enregistrées via register_patch_mapping().
  5. Les règles ~WeightTransform correspondantes sont générées à partir de la configuration afin que le chargement du point de contrôle puisse mapper les poids vers la disposition de l'exécution fusionnée.
  6. Par défaut, save_pretrained() utilise le chemin de conversion inverse pour restaurer la structure d'origine du point de contrôle. Passez save_original_format=False pour conserver à la place la structure d'exécution convertie.

Cela permet à une fusion d'utiliser une structure de module d'exécution différente tout en chargeant toujours depuis le format de point de contrôle d'origine, et en y enregistrant par défaut.

Note : Avec le mécanisme de monkey-patching actuel, l’enregistrement de la fusion est au niveau de la classe : une classe de module compatible correspond à une classe de remplacement fusionnée.

Familles de fusion actuelles

Actuellement, fusion_config prend en charge une seule famille de fusion :

  • patch_embeddings Activer avec :

    fusion_config = {"patch_embeddings": True}

    Effet : Remplace les projections d'encodage de patch compatibles nn.Conv3d par des projections nn.Linear aplatis équivalentes à l'exécution.

Étendre la fusion de mappage

Pour ajouter une nouvelle famille de fusion :

  1. Ajouter un prédicat is_fusable. Celui-ci détermine si un module découvert est compatible avec la fusion.
  2. Ajoutez éventuellement target_modules_patterns. Cela rend l'étape de découverte plus explicite en pré-filtrant les noms de modules candidats avant is_fusable(...).
  3. Ajouter une fabrique make_fused_class. Celle-ci renvoie la classe de remplacement au moment de l’exécution pour une classe de module compatible.
  4. Ajoutez une fabrique make_transforms si la fusion des layouts nécessite une conversion de points de contrôle. Cela renvoie les règles ~WeightTransform qui mappent les poids entre les layouts d'origine et fusionnés pour une configuration donnée.
  5. Enregistrez le nouveau ModuleFusionSpec dans fusion_mapping.py.

Une fois enregistrée, la nouvelle fusion devient disponible via fusion_config.

API interne

classe transformers.fusion_mapping.ModuleFusionSpec

< >

( )

Recette de base pour une famille de fusion.

Une spécification de fusion détermine quels modules sont éligibles à une fusion, comment construire la classe de remplacement à l'exécution, et quelles transformations de poids sont nécessaires pour mapper les points de contrôle entre les dispositions d'origine et fusionnées.

get_empty_log

< >

( model_name: str )

Retourner le message de journal émis lorsqu'aucun module compatible n'est trouvé.

is_fusable

< >

( module: Module )

Indique si module est compatible avec cette famille de fusion.

make_fused_class

< >

( original_cls: type[torch.nn.Module] )

Construisez la classe de remplacement d'exécution pour une classe de module compatible.

make_transforms

< >

( config: PretrainedConfig )

Construisez les transformations de poids nécessaires pour charger et enregistrer la disposition de l'exécution fusionnée.

classe transformers.fusion_mapping.PatchEmbeddingsFusionSpec

< >

( )

Fusionner les embeddings de patch Conv3d compatibles en projections Linear aplatties.

transformers.fusion_mapping._register_module_fusion

< >

( config: PretrainedConfigfusion_name: strspec: ModuleFusionSpec )

Enregistrer une famille de fusion pour cls.

Cette fonction met à jour les deux registres globaux utilisés par le chargement fusionné :

  • le registre de monkey-patching, de sorte que les classes de modules compatibles sont remplacées avant l'initialisation
  • le mapping de conversion de checkpoint, afin que les modules de runtime fusionnés soient toujours chargés depuis la disposition du checkpoint d'origine

Remarques :

  • les transformations de points de contrôle en conflit échouent rapidement

transformers.fusion_mapping.register_fusion_patches

< >

( configfusion_config: collections.abc.Mapping[str, bool | collections.abc.Mapping[str, typing.Any]] | None = None )

Enregistrer les fusions de temps d’exécution demandées pour cls.

Cette fonction :

  • valide fusion_config par rapport à _FUSION_REGISTRY
  • résout les familles de fusion activées dans l'ordre de l'utilisateur
  • enregistre les correctifs singes et les transformations de points de contrôle avant l'instantiation du modèle
Update on GitHub