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 para substituir as classes de módulos antes da instanciação do modelo.
• Carregamento dinâmico de pesos para mapear os pesos entre os layouts de runtime originais e fundidos.

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() com fusion_config:

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() 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().
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() 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:

  Copiado

  fusion_config = {"patch_embeddings": True}

  Efeito: Substitui as projeções de incorporação de patches compatíveis com nn.Conv3d por projeções nn.Linear equivalentes e achatadas 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.

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

API interna