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 para intercambiar las clases de los módulos antes de la instanciación del modelo.
• Carga dinámica de pesos para mapear los pesos entre los diseños de tiempo de ejecución originales y fusionados.

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

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

  Copiado

  fusion_config = {"patch_embeddings": True}

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

Extender el mapeo de fusión

Para añadir una nueva familia de fusiones:

1. Añade un predicado is_fusable. Este decide si un módulo descubierto es compatible con la fusión.
2. Opcionalmente, añade target_modules_patterns. Esto hace que el paso de descubrimiento 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. Esto 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 los diseños original y fusionado para una configuración dada.
5. Registre el nuevo ModuleFusionSpec en fusion_mapping.py.

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

API interna