# Mapeo de fusión (función experimental)

El mapeo de fusión ofrece una opción para reemplazar submódulos del modelo en el momento de la carga, preservando el formato original del punto de control.

Se basa en:

- [Monkey patching](./monkey_patching) para intercambiar las clases de los módulos antes de la instanciación del modelo.
- [Carga dinámica de pesos](./weightconverter) para mapear los pesos entre los diseños de tiempo de ejecución originales y fusionados.

> [!WARNING]
> El mapeo de fusión es una función de carga experimental. Modifica la estructura del módulo en tiempo de ejecución y puede afectar el comportamiento del modelo. Úsalo solo cuando desees explícitamente un diseño de tiempo de ejecución fusionado.

## Inicio rápido

La fusión se habilita a través de [from_pretrained()](/docs/transformers/main/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) con `fusion_config`:

```python
from transformers import AutoModelForImageTextToText

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

Por defecto, no se aplica ninguna fusión. Si `fusion_config` se encuentra en la configuración del modelo, `from_pretrained()` lo reutilizará automáticamente.

## Cómo funciona

El registro de fusión ocurre antes de que se instancie el modelo:

1. [from_pretrained()](/docs/transformers/main/es/main_classes/model#transformers.PreTrainedModel.from_pretrained) utiliza el argumento explícito `fusion_config` o recurre a `config.fusion_config`.
2. El registro de fusiones valida los nombres de fusión solicitados.
3. Cada fusión habilitada inicializa meta la clase de modelo objetivo, filtra opcionalmente los módulos candidatos por nombre y utiliza `is_fusable(...)` para descubrir las clases de módulos compatibles.
4. Las clases de reemplazo fusionadas se registran a través de [register_patch_mapping()](/docs/transformers/main/es/monkey_patching#transformers.monkey_patching.register_patch_mapping).
5. Se generan reglas de `~WeightTransform` a partir de la configuración para que la carga del checkpoint pueda mapear los pesos al diseño de tiempo de ejecución fusionado.
6. Por defecto, [save_pretrained()](/docs/transformers/main/es/main_classes/model#transformers.PreTrainedModel.save_pretrained) utiliza la ruta de conversión inversa para restaurar el diseño original del punto de control. Pasa `save_original_format=False` para mantener el diseño de tiempo de ejecución convertido.

Esto permite que una fusión utilice una estructura de módulo de tiempo de ejecución diferente, mientras sigue cargando desde el formato de punto de control original y, de forma predeterminada, guardando de nuevo en él.

Nota: Con el mecanismo de monkey-patching actual, el registro de fusión es a nivel de clase: una clase de módulo compatible se mapea a una clase de reemplazo fusionado.

## Familias de fusión actuales

Actualmente, `fusion_config` admite una familia de fusiones:

- `patch_embeddings` Actívalo con:

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

  Efecto: Reemplaza las proyecciones de incrustación de parches compatibles con `nn.Conv3d` por proyecciones `nn.Linear` equivalentes aplanadas en tiempo de ejecución.

## Extender el mapeo de fusión

Para añadir una nueva familia de fusiones:

1. Añada un predicado `is_fusable`. Este determina si un módulo descubierto es compatible con la fusión.
2. Opcionalmente, añade `target_modules_patterns`. Esto hace que el paso de detección sea más explícito al prefiltrar los nombres de módulos candidatos antes de `is_fusable(...)`.
3. Agregue una fábrica `make_fused_class`. Esta devuelve la clase de reemplazo en tiempo de ejecución para una clase de módulo compatible.
4. Agregue una fábrica `make_transforms` si el diseño fusionado requiere la conversión de puntos de control. Esto devuelve las reglas `~WeightTransform` que mapean los pesos entre el diseño original y el diseño fusionado para una configuración dada.
5. Registre el nuevo `ModuleFusionSpec` en [`fusion_mapping.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py).

Una vez registrada, la nueva fusión queda disponible a través de `fusion_config`.

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

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

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L47)

Receta base para una familia de fusión.

Una especificación de fusión determina qué módulos son elegibles para una fusión, cómo construir la clase de reemplazo en tiempo de ejecución y qué transformaciones de pesos son necesarias para mapear los puntos de control entre los diseños originales y fusionados.

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

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L57)

Devuelve el mensaje de registro emitido cuando no se encuentran módulos compatibles.

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

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L61)

Devuelve si `module` es compatible con esta familia de fusiones.

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

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L65)

Construya la clase de reemplazo en tiempo de ejecución para una clase de módulo compatible.

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

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L69)

Construya las transformaciones de pesos necesarias para cargar y guardar el diseño de tiempo de ejecución fusionado.

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

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

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L97)

Fusiona las incrustaciones de parches de Conv3d compatibles en proyecciones lineales aplanadas.

#### 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)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L193)

Registre una familia de fusión para `cls`.

Esta función actualiza los dos registros globales utilizados por la carga fusionada:
- el registro de monkey-patching, de modo que las clases de módulos compatibles se reemplazan antes de la inicialización
- el mapeo de conversión de puntos de control, para que los módulos de tiempo de ejecución fusionados sigan cargándose desde el diseño original del punto de control

Notas:
- las transformaciones de puntos de control en conflicto fallan rápidamente

#### 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)
```

[Fuente](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py#L269)

Registrar las fusiones de tiempo de ejecución solicitadas para `cls`.

Esta función:
- valida `fusion_config` contra `_FUSION_REGISTRY`
- resuelve las familias de fusión habilitadas en el orden del usuario
- registra parches de mono y transformaciones de puntos de control antes de la instanciación del modelo