Transformers documentation
Cartographie de fusion (fonctionnalité expérimentale)
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 :
- Monkey patching pour remplacer les classes de modules avant l'instantiation du modèle.
- Chargement dynamique des poids pour mapper les poids entre les dispositions d’exécution d’origine et fusionnées.
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 :
- from_pretrained() utilise l'argument explicite
fusion_configou se rabat surconfig.fusion_config. - Le registre de fusion valide les noms de fusion demandés.
- 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. - Les classes de remplacement fusionnées sont enregistrées via register_patch_mapping().
- Les règles
~WeightTransformcorrespondantes 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. - 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=Falsepour 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_embeddingsActiver avec :fusion_config = {"patch_embeddings": True}Effet : Remplace les projections d'encodage de patch compatibles
nn.Conv3dpar des projectionsnn.Linearaplatis équivalentes à l'exécution.
Étendre la fusion de mappage
Pour ajouter une nouvelle famille de fusion :
- Ajouter un prédicat
is_fusable. Celui-ci détermine si un module découvert est compatible avec la fusion. - Ajoutez éventuellement
target_modules_patterns. Cela rend l'étape de découverte plus explicite en pré-filtrant les noms de modules candidats avantis_fusable(...). - 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. - Ajoutez une fabrique
make_transformssi la fusion des layouts nécessite une conversion de points de contrôle. Cela renvoie les règles~WeightTransformqui mappent les poids entre les layouts d'origine et fusionnés pour une configuration donnée. - Enregistrez le nouveau
ModuleFusionSpecdansfusion_mapping.py.
Une fois enregistrée, la nouvelle fusion devient disponible via fusion_config.
API interne
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.
Retourner le message de journal émis lorsqu'aucun module compatible n'est trouvé.
Indique si module est compatible avec cette famille de fusion.
Construisez la classe de remplacement d'exécution pour une classe de module compatible.
Construisez les transformations de poids nécessaires pour charger et enregistrer la disposition de l'exécution fusionnée.
Fusionner les embeddings de patch Conv3d compatibles en projections Linear aplatties.
transformers.fusion_mapping._register_module_fusion
< source >( 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
< source >( 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_configpar 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