# Mapeamento de fusão (recurso experimental)

O mapeamento de fusão oferece uma opção para substituir submódulos do modelo no momento do carregamento, preservando o formato original do checkpoint.

Ele se baseia em:

- [Monkey patching](./monkey_patching) para substituir as classes de módulos antes da instanciação do modelo.
- [Carregamento dinâmico de pesos](./weightconverter) para mapear os pesos entre os layouts de runtime originais e fundidos.

> [!WARNING]
> O mapeamento de fusão é um recurso experimental de carregamento. Ele altera a estrutura de módulos em tempo de execução e pode afetar o comportamento do modelo. Use-o apenas quando você desejar explicitamente um layout de tempo de execução fundido.

## Início rápido

A fusão é habilitada por meio de [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) com `fusion_config`:

```python
from transformers import AutoModelForImageTextToText

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

Por padrão, nenhuma fusão é aplicada. Se `fusion_config` estiver armazenado na configuração do modelo, `from_pretrained()` o reutilizará automaticamente.

## Como funciona

O registro de fusão ocorre antes da instanciação do modelo:

1. [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) usa o argumento explícito `fusion_config` ou recorre a `config.fusion_config`.
2. O registro de fusão valida os nomes de fusão solicitados.
3. Cada fusão habilitada inicializa meta a classe de modelo de destino, filtra opcionalmente os módulos candidatos por nome e usa `is_fusable(...)` para descobrir as classes de módulos compatíveis.
4. As classes de substituição fundidas são registradas por meio de [register_patch_mapping()](/docs/transformers/main/pt/monkey_patching#transformers.monkey_patching.register_patch_mapping).
5. As regras `~WeightTransform` correspondentes são geradas a partir da configuração para que o carregamento do checkpoint possa mapear os pesos para o layout de runtime fundido.
6. Por padrão, [save_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.save_pretrained) usa o caminho de conversão reversa para restaurar o layout original do checkpoint. Passe `save_original_format=False` para manter o layout de runtime convertido.

Isso permite que uma fusão utilize uma estrutura de módulo de runtime diferente, carregando ainda assim do formato de checkpoint original e, por padrão, salvando de volta para ele.

Nota: Com o mecanismo atual de monkey-patching, o registro de fusão é de nível de classe: uma classe de módulo compatível mapeia para uma classe de substituição fundida.

## Famílias de fusão atuais

Atualmente, `fusion_config` suporta uma família de fusão:

- `patch_embeddings` Ative com:

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

  Efeito: substitui as projeções de incorporação de patches compatíveis com `nn.Conv3d` por projeções equivalentes achatadas `nn.Linear` em tempo de execução.

## Estendendo o mapeamento de fusão

Para adicionar uma nova família de fusão:

1. Adicione um predicado `is_fusable`. Ele decide se um módulo descoberto é compatível com a fusão.
2. Adicione opcionalmente `target_modules_patterns`. Isso torna a etapa de descoberta mais explícita, pré-filtrando os nomes de módulos candidatos antes de `is_fusable(...)`.
3. Adicione uma fábrica `make_fused_class`. Ela retorna a classe de substituição em tempo de execução para uma classe de módulo compatível.
4. Adicione uma fábrica `make_transforms` se o layout fundido precisar de conversão de checkpoint. Isso retorna as regras `~WeightTransform` que mapeiam os pesos entre os layouts original e fundido para uma configuração dada.
5. Registre o novo `ModuleFusionSpec` em [`fusion_mapping.py`](https://github.com/huggingface/transformers/blob/main/src/transformers/fusion_mapping.py).

Uma vez registrada, a nova fusão fica disponível por meio de `fusion_config`.

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

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

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

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

Receita base para uma família de fusão.

Uma especificação de fusão determina quais módulos são elegíveis para fusão, como construir a classe de substituição em tempo de execução e quais transformações de pesos são necessárias para mapear checkpoints entre os layouts original e fundido.

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

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

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

Retorna a mensagem de log emitida quando nenhum módulo compatível é encontrado.

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

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

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

Retorna se `module` é compatível com esta família de fusão.

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

```python
make_fused_class(original_cls: type)
```

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

Crie a classe de substituição em tempo de execução para uma classe de módulo compatível.

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

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

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

Construa as transformações de pesos necessárias para carregar e salvar o layout de runtime fundido.

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

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

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

Fusos compatíveis de incorporações de patches Conv3d em projeções Linear achatadas.

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

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

Registre uma família de fusão para `cls`.

Esta função atualiza os dois registros globais usados pelo carregamento fundido:
- o registro de monkey-patching, para que as classes de módulos compatíveis sejam substituídas antes da inicialização
- o mapeamento de conversão de checkpoint, para que os módulos de runtime fundidos ainda sejam carregados do layout original do checkpoint

Observações:
- transformações de checkpoint conflitantes falham rapidamente

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

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

Registre as fusões de tempo de execução solicitadas para `cls`.

Esta função:
- valida `fusion_config` em relação a `_FUSION_REGISTRY`
- resolve as famílias de fusão habilitadas na ordem do usuário
- registra monkey patches e transformações de checkpoint antes da instanciação do modelo