# 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](./monkey_patching) pour remplacer les classes de modules avant l'instantiation du modèle.
- [Chargement dynamique des poids](./weightconverter) pour mapper les poids entre les dispositions d’exécution d’origine et fusionnées.

> [!WARNING]
> 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()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.from_pretrained) avec `fusion_config` :

```python
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 présent 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()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.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()](/docs/transformers/v5.23.0/fr/monkey_patching#transformers.monkey_patching.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()](/docs/transformers/v5.23.0/fr/main_classes/model#transformers.PreTrainedModel.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 :

  ```python
  fusion_config = {"patch_embeddings": True}
  ```

  Effet : remplace les projections d’encodage de patch compatibles `nn.Conv3d` par des projections `nn.Linear` équivalentes aplaties à l’exécution.

## Étendre la fusion de mappage

Pour ajouter une nouvelle famille de fusion :

1. Ajouter un prédicat `is_fusable`. Il 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`. Elle 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. Elle 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`](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py).

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

## API interne[[transformers.fusion_mapping.ModuleFusionSpec]]

#### transformers.fusion_mapping.ModuleFusionSpec[[transformers.fusion_mapping.ModuleFusionSpec]]

```python
transformers.fusion_mapping.ModuleFusionSpec()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L47)

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[[transformers.fusion_mapping.ModuleFusionSpec.get_empty_log]]

```python
get_empty_log(model_name: str)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L57)

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

#### is_fusable[[transformers.fusion_mapping.ModuleFusionSpec.is_fusable]]

```python
is_fusable(module: Module)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L61)

Indique si `module` est compatible avec cette famille de fusion.

#### make_fused_class[[transformers.fusion_mapping.ModuleFusionSpec.make_fused_class]]

```python
make_fused_class(original_cls: type[torch.nn.Module])
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L65)

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

#### make_transforms[[transformers.fusion_mapping.ModuleFusionSpec.make_transforms]]

```python
make_transforms(config: PretrainedConfig)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L69)

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

#### transformers.fusion_mapping.PatchEmbeddingsFusionSpec[[transformers.fusion_mapping.PatchEmbeddingsFusionSpec]]

```python
transformers.fusion_mapping.PatchEmbeddingsFusionSpec()
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L97)

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

#### transformers.fusion_mapping._register_module_fusion[[transformers.fusion_mapping._register_module_fusion]]

```python
transformers.fusion_mapping._register_module_fusion(config: PretrainedConfig, fusion_name: str, spec: ModuleFusionSpec)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L193)

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[[transformers.fusion_mapping.register_fusion_patches]]

```python
transformers.fusion_mapping.register_fusion_patches(config, fusion_config: collections.abc.Mapping[str, bool | collections.abc.Mapping[str, typing.Any]] | None = None)
```

[Source](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/fusion_mapping.py#L269)

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

