# Fusion mapping (funcție experimentală)

Fusion mapping oferă o modalitate opțională de a înlocui sub-modulele modelului la momentul încărcării, păstrând în același timp formatul original al checkpoint-ului.

Se bazează pe:

- [Monkey patching](./monkey_patching) pentru a schimba clasele de module înainte de instanțierea modelului.
- [Încărcarea dinamică de weights](./weightconverter) pentru a mapa weights între layout-ul de rulare original și cel fuzionat.

> [!WARNING]
> Fusion mapping este o funcție experimentală de încărcare. Schimbă structura modulelor la rulare și poți afecta comportamentul modelului. Folosește-o doar când dorești explicit un layout de rulare fuzionat.

## Pornire rapidă

Fusion este activat prin `from_pretrained()` cu `fusion_config`:

```python
from transformers import AutoModelForImageTextToText

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

În mod implicit, nu se aplică niciun fusion.
Dacă `fusion_config` este stocat în configurația modelului, `from_pretrained()` îl va reutiliza automat.

## Cum funcționează

Înregistrarea fusion are loc înainte de instanțierea modelului:

1. `from_pretrained()` folosește argumentul explicit `fusion_config` sau recurge la `config.fusion_config`.
2. Registrul fusion validează numele fusion-urilor solicitate.
3. Fiecare fusion activat meta-inițializează clasa modelului țintă, filtrează opțional modulele candidate după nume și folosește `is_fusable(...)` pentru a descoperi clasele de module compatibile.
4. Clasele de înlocuire fuzionate sunt înregistrate prin [register_patch_mapping()](/docs/transformers/main/ro/monkey_patching#transformers.monkey_patching.register_patch_mapping).
5. Regulile `~WeightTransform` corespunzătoare sunt generate din configurație pentru ca încărcarea checkpoint-ului să poată mapa weights în layout-ul de runtime fuzionat.
6. În mod implicit, `save_pretrained()` folosește calea de conversie inversă pentru a restaura layout-ul original al checkpoint-ului. Pasează `save_original_format=False` pentru a păstra în schimb layout-ul de runtime convertit.

Aceasta permite unui fusion să folosească o structură de module de runtime diferită, încărcând în continuare din formatul original al checkpoint-ului și salvând înapoi în același format în mod implicit.

Notă: Cu mecanismul actual de monkey-patching, înregistrarea fusion este la nivel de clasă: o clasă de modul compatibilă se mapează la o clasă de înlocuire fuzionată.

## Familii de fusion curente

În prezent, `fusion_config` suportă o familie de fusion:

- `patch_embeddings`
  Activează cu:

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

  Efect:
  Înlocuiește proiecțiile de patch embedding `nn.Conv3d` compatibile cu proiecții `nn.Linear` aplatizate echivalente la runtime.

## Extinderea fusion mapping

Pentru a adăuga o nouă familie de fusion:

1. Adaugă un predicat `is_fusable`.
   Acesta determină dacă un modul descoperit este compatibil cu fusion-ul.
2. Adaugă opțional `target_modules_patterns`.
   Aceasta face pasul de descoperire mai explicit prin pre-filtrarea numelor modulelor candidate înainte de `is_fusable(...)`.
3. Adaugă un factory `make_fused_class`.
   Acesta returnează clasa de înlocuire de runtime pentru o clasă de modul compatibilă.
4. Adaugă un factory `make_transforms` dacă layout-ul fuzionat necesită conversia checkpoint-ului.
   Acesta returnează regulile `~WeightTransform` care mapează weights între layout-urile original și fuzionat pentru o configurație dată.
5. Înregistrează noul `ModuleFusionSpec` în [`fusion_mapping.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py).

Odată înregistrat, noul fusion devine disponibil prin `fusion_config`.

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

Base recipe for a fusion family.

A fusion spec decides which modules are eligible for a fusion, how to build
the runtime replacement class, and which weight transforms are needed to map
checkpoints between the original and fused layouts.

Return the log message emitted when no compatible modules are found.

Return whether `module` is compatible with this fusion family.

Build the runtime replacement class for a compatible module class.

Build the weight transforms needed to load and save the fused runtime layout.

Fuse compatible Conv3d patch embeddings into flattened Linear projections.

Register one fusion family for `cls`.

This function updates the two global registries used by fused loading:
- the monkey-patching registry, so compatible module classes are replaced before initialization
- the checkpoint conversion mapping, so fused runtime modules still load from the original checkpoint layout

Notes:
- conflicting checkpoint transforms fail fast

Register requested runtime fusions for `cls`.

This function:
- validates `fusion_config` against `_FUSION_REGISTRY`
- resolves the enabled fusion families in user order
- registers monkey patches and checkpoint transforms before model instantiation