Hugging Face's logo

PEFT documentation

DEFT: Ajuste fino eficiente y decomposicional para modelos de texto a imagen

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.21.0).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

DEFT: Ajuste fino eficiente y decomposicional para modelos de texto a imagen

DEFT (Decompositional Efficient Fine-Tuning) es un método de ajuste fino eficiente en parámetros para modelos de texto a imagen. Descompone la actualización de una matriz de pesos congelada W en dos componentes entrenables: una proyección que elimina un subespacio de bajo rango de W, y una actualización de bajo rango que inyecta nuevo contenido en ese subespacio. Esta formulación está diseñada para equilibrar la alineación con una distribución objetivo, el aprendizaje de nuevos conceptos a partir de pocas imágenes (personalización) y la preservación de la capacidad del modelo preentrenado para seguir instrucciones y ser editable.

Concretamente, DEFT combina dos componentes de bajo rango entrenables: (1) una proyección sobre el complemento de un subespacio de bajo rango generado por una matriz de bajo rango, y (2) una actualización de bajo rango. La primera matriz de bajo rango define el subespacio, mientras que la segunda permite una adaptación flexible de los parámetros dentro de ese subespacio.

Cuándo usar DEFT: es más adecuado para adaptar un modelo a nuevos datos o conceptos mientras se conserva e incluso se mejora la capacidad de seguir instrucciones del modelo base y se mantiene al mínimo el olvido de sus capacidades anteriores.

Por cada capa objetivo, DEFT aprende una dirección de proyección P (forma out_features x r) y una matriz de inyección R (forma r x in_features). El peso efectivo es la proyección residual

W' = (I - P_proj) @ W + Q_P @ R

El proyector P_proj se deriva de P según decomposition_method:

  • "relu" (predeterminado): Q_P = P, P_proj = P @ relu(P).T — una proyección no ortogonal.
  • "qr": Q_P = qr(P), P_proj = Q_P @ Q_P.T — una proyección ortogonal.

El término (I - P_proj) @ W elimina un subespacio del peso preentrenado, mientras que Q_P @ R inyecta nuevo contenido en él. Por defecto (init_weights=True), R se inicializa de modo que la actualización sea una identidad exacta en la inicialización (W' == W), por lo que el entrenamiento comienza desde los pesos preentrenados y aprende la inyección. La actualización es equivalente a un delta aditivo de bajo rango Q_P @ (R - right.T @ W), que se calcula sin formar nunca la matriz de proyección out x out y puede fusionarse en los pesos base para una implementación sin inferencia.

Establecer para=True selecciona la variante PaRa (Reducción de Rango de Parámetros): una actualización de solo eliminación W' = (I - P_proj) @ W que conserva únicamente el término de eliminación del subespacio y descarta la inyección. Solo se entrena la proyección P (sin matriz de inyección R), por lo que el adaptador no es una identidad en la inicialización. PaRa se introdujo para personalizar modelos de difusión de texto a imagen y está disponible aquí como un caso especial de DEFT.

DEFT está implementado actualmente para capas torch.nn.Linear y Conv1D (p. ej. gpt-2, a través de fan_in_fan_out). La implementación original y los experimentos del artículo (Dreambooth, Dreambench Plus, InsDet, VisualCloze, en Stable Diffusion y un modelo unificado) están disponibles en github.com/MAXNORM8650/DEFT.

Si usas DEFT en tu trabajo, cita el artículo:

@article{kumar2026deft,
  title={DEFT: Decompositional Efficient Fine-Tuning for Text-to-Image Models},
  author={Kumar, Komal and Anwer, Rao and Shahbaz Khan, Fahad and Khan, Salman and Laptev, Ivan and Cholakkal, Hisham},
  journal={Advances in Neural Information Processing Systems},
  volume={38},
  pages={102009--102035},
  year={2026}
}

Si utiliza la variante PaRa (para=True, también cite:

@inproceedings{chen2025personalizing,
  title={Para: Personalizing text-to-image diffusion via parameter rank reduction},
  author={Chen, Shangyu and Pan, Zizheng and Cai, Jianfei and Phung, Dinh},
  booktitle={International Conference on Learning Representations},
  year={2025}
}

DeftConfig

clase peft.DeftConfig

< >

( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falser: int = 8target_modules: Optional[Union[list[str], str]] = Noneexclude_modules: Optional[Union[list[str], str]] = Nonedecomposition_method: Literal['relu', 'qr'] = 'relu'init_scale: float = 1.0alpha: Optional[int] = Nonepara: bool = Falsefan_in_fan_out: bool = Falsedeft_dropout: float = 0.0init_weights: bool = Truelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = Nonebias: str = 'none'modules_to_save: Optional[list[str]] = None )

Parámetros

  • r (int) — El rango de la proyección/inyección DEFT entre capas.
  • target_modules (Optional[Union[List[str], str]]) — Los nombres de los módulos a los que se aplicará el adaptador. Si se especifica, solo se reemplazarán los módulos con los nombres indicados. Al pasar una cadena de caracteres, se realizará una coincidencia mediante expresión regular. Al pasar una lista de cadenas de caracteres, se realizará una coincidencia exacta o se verificará si el nombre del módulo termina con alguna de las cadenas pasadas. Si se especifica como ‘all-linear’, se seleccionarán todos los módulos lineales, excluyendo la capa de salida. Si no se especifica, los módulos se elegirán según la arquitectura del modelo. Si la arquitectura no es conocida, se generará un error; en este caso, debe especificar los módulos objetivo manualmente.
  • exclude_modules (Optional[Union[List[str], str]]) — Los nombres de los módulos a los que no se aplicará el adaptador. Al pasar una cadena de caracteres, se realizará una coincidencia mediante expresión regular. Al pasar una lista de cadenas de caracteres, se realizará una coincidencia exacta o se comprobará si el nombre del módulo termina con alguna de las cadenas de caracteres pasadas.
  • decomposition_method (str) — Cómo se deriva el proyector P_proj a partir de P. Puede ser "relu" (predeterminado, P @ relu(P).T no ortogonal) o "qr" (Q_P @ Q_P.T ortogonal).
  • init_scale (float) — Escala aplicada a la desviación estándar utilizada para inicializar la matriz de inyección R (solo se usa cuando init_weights=False). Valores más pequeños mantienen la actualización inyectada más cerca de cero en la inicialización. El valor predeterminado es 1.0.
  • alpha (Optional[int]) — El factor de escala para el término de inyección, que se escala por alpha / r (análogo a la alpha de LoRA). Si None, no se aplica ninguna escala (factor 1.0). El término de eliminación del subespacio no se ve afectado.
  • para (bool) — Si se debe usar el método PaRa: eliminación pura de subespacio (delta = -P_proj @ W) sin término de inyección. Cuando True, R no se crea, P es la única matriz entrenable y el adaptador no puede ser una identidad en la inicialización. El valor predeterminado es False (DEFT completo).
  • fan_in_fan_out (bool) — Establezca este valor en True si la capa que se va a reemplazar almacena los pesos como (fan_in, fan_out). Por ejemplo, gpt-2 utiliza Conv1D, que almacena los pesos como (fan_in, fan_out), por lo que este valor debe establecerse en True.
  • deft_dropout (float) — La probabilidad de dropout aplicada a la entrada de la capa. El valor predeterminado es 0.0.
  • init_weights (bool) — Si se debe usar la inicialización predeterminada (identidad) de DEFT para los pesos del adaptador, de modo que el adaptador no tenga efecto al inicio del entrenamiento. No cambies esta configuración, a menos que sepas exactamente lo que estás haciendo. El valor predeterminado es True.
  • layers_to_transform (Union[List[int], int]) — Los índices de las capas a transformar. Si se pasa una lista de enteros, se aplicará el adaptador a los índices de capa especificados en esta lista. Si se pasa un solo entero, se aplicarán las transformaciones a la capa en este índice.
  • layers_pattern (Optional[Union[List[str], str]]) — El nombre del patrón de capas, utilizado solo si layers_to_transform es diferente de None. Esto debe apuntar al nn.ModuleList del modelo, que a menudo se llama 'layers' o 'h'.
  • bias (str) — Tipo de sesgo para DEFT. Puede ser 'none', 'all' o 'deft_only'.
  • modules_to_save (List[str]) — Lista de módulos, aparte de las capas de adaptador, que se configurarán como entrenables y se guardarán en el punto de control final.

Esta es la clase de configuración para almacenar la configuración de un DeftModel.

DEFT (Decompositional Efficient Fine-Tuning) realiza la inyección de conocimiento mediante una actualización de proyección residual. Para un peso base congelado W, se aprenden una dirección de proyección de bajo rango P (forma out_features x r) y una matriz de inyección R (forma r x in_features). El peso adaptado es W' = (I - P_proj) @ W + Q_P @ R, donde el proyector P_proj se deriva de P según decomposition_method:

  • "relu" (predeterminado): Q_P = P, P_proj = P @ relu(P).T (proyección no ortogonal)
  • "qr": Q_P = qr(P), P_proj = Q_P @ Q_P.T (proyección ortogonal)

Por defecto (init_weights=True), R se inicializa de modo que la actualización es una identidad exacta en la inicialización (el peso adaptado es igual a W), por lo que el entrenamiento comienza desde los pesos preentrenados y aprende la inyección.

DeftModel

clase peft.DeftModel

< >

( modelpeft_config: Union[PeftConfig, dict[str, PeftConfig]]adapter_name: strlow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None ) → torch.nn.Module

Parámetros

  • model (torch.nn.Module) — El modelo al que se adjuntarán las capas del afinador de adaptadores.
  • config (DeftConfig) — La configuración del modelo DEFT.
  • adapter_name (str) — El nombre del adaptador, por defecto es "default".
  • low_cpu_mem_usage (bool, optional, defaults to False) — Crea pesos de adaptador vacíos en el dispositivo meta. Útil para acelerar el proceso de carga.

Devuelve

torch.nn.Module

El modelo DEFT.

Crea un modelo DEFT (Decompositional Efficient Fine-Tuning) a partir de un modelo preentrenado.

DEFT congela los pesos base y aprende, para cada módulo objetivo, una dirección de proyección de bajo rango P y una matriz de inyección R. El peso efectivo se convierte en (I - P_proj) @ W + Q_P @ R, reemplazando un subespacio de W con contenido recién inyectado (consulte DeftConfig para las variantes disponibles de decomposition_method).

Atributos:

  • model (~torch.nn.Module) — El modelo que se va a adaptar.
  • peft_config (DeftConfig): La configuración del modelo DEFT.
Update on GitHub

←C3A DeLoRA→