Hugging Face's logo

PEFT documentation

DEFT: Decompositional Efficient Fine-Tuning para Modelos de Texto para Imagem

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: Decompositional Efficient Fine-Tuning para Modelos de Texto para Imagem

DEFT (Decompositional Efficient Fine-Tuning) é um método de ajuste fino eficiente em parâmetros para modelos de texto para imagem. Ele decompõe a atualização de uma matriz de pesos congelada W em dois componentes treináveis: uma projeção que remove um subespaço de baixo posto de W e uma atualização de baixo posto que injeta novo conteúdo nesse subespaço. Essa formulação foi projetada para equilibrar o alinhamento com uma distribuição alvo, o aprendizado de novos conceitos a partir de poucas imagens (personalização) e a preservação da capacidade de seguir instruções e da editabilidade do modelo pré-treinado.

Concretamente, o DEFT combina dois componentes de baixo posto treináveis: (1) uma projeção no complemento de um subespaço de baixo posto gerado por uma matriz de baixo posto, e (2) uma atualização de baixo posto. A primeira matriz de baixo posto define o subespaço, enquanto a segunda permite a adaptação flexível dos parâmetros dentro desse subespaço.

Quando usar DEFT: é mais adequado para adaptar um modelo a novos dados ou conceitos, mantendo e até melhorando a capacidade do modelo base de seguir instruções e mantendo o esquecimento de suas capacidades anteriores ao mínimo.

Para cada camada de destino, o DEFT aprende uma direção de projeção P (forma out_features x r) e uma matriz de injeção R (forma r x in_features). O peso efetivo é a projeção residual

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

O projetor P_proj é derivado de P de acordo com decomposition_method:

  • "relu" (padrão): Q_P = P, P_proj = P @ relu(P).T — uma projeção não ortogonal.
  • "qr": Q_P = qr(P), P_proj = Q_P @ Q_P.T — uma projeção ortogonal.

O termo (I - P_proj) @ W remove um subespaço do peso pré-treinado, enquanto Q_P @ R injeta novo conteúdo nele. Por padrão (init_weights=True), R é inicializado de modo que a atualização seja uma identidade exata na inicialização (W' == W), de modo que o treinamento começa a partir dos pesos pré-treinados e aprende a injeção. A atualização é equivalente a um delta aditivo de baixo posto Q_P @ (R - right.T @ W), que é calculado sem nunca formar a matriz de projeção out x out e pode ser mesclada nos pesos base para implantação sem inferência.

Definir para=True seleciona a variante PaRa (Parameter Rank Reduction): uma atualização apenas de remoção W' = (I - P_proj) @ W que mantém apenas o termo de remoção do subespaço e descarta a injeção. Somente a projeção P é treinada (sem a matriz de injeção R), portanto o adaptador não é uma identidade na inicialização. O PaRa foi introduzido para personalizar modelos de difusão de texto para imagem e está disponível aqui como um caso especial do DEFT.

DEFT é atualmente implementado para camadas torch.nn.Linear e Conv1D (por exemplo, gpt-2, via fan_in_fan_out). A implementação original e os experimentos do artigo (Dreambooth, Dreambench Plus, InsDet, VisualCloze, em Stable Diffusion e um modelo unificado) estão disponíveis em github.com/MAXNORM8650/DEFT.

Se você usar DEFT em seu trabalho, por favor, cite o artigo:

@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}
}

Se você usar a variante PaRa (para=True), cite também:

@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

classe 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) — O rank da projeção/injeção DEFT entre as camadas.
  • target_modules (Optional[Union[List[str], str]]) — Os nomes dos módulos aos quais o adaptador será aplicado. Se especificado, apenas os módulos com os nomes especificados serão substituídos. Ao passar uma string, uma correspondência de regex será realizada. Ao passar uma lista de strings, uma correspondência exata será realizada ou será verificado se o nome do módulo termina com qualquer uma das strings passadas. Se especificado como ‘all-linear’, todos os módulos lineares serão escolhidos, excluindo a camada de saída. Se não especificado, os módulos serão escolhidos de acordo com a arquitetura do modelo. Se a arquitetura não for conhecida, um erro será lançado — nesse caso, você deve especificar os módulos alvo manualmente.
  • exclude_modules (Optional[Union[List[str], str]]) — Os nomes dos módulos para os quais o adaptador não deve ser aplicado. Ao passar uma string, será realizada uma correspondência por expressão regular. Ao passar uma lista de strings, será realizada uma correspondência exata ou será verificado se o nome do módulo termina com qualquer uma das strings passadas.
  • decomposition_method (str) — Como o projetor P_proj é derivado de P. Ou "relu" (padrão, P @ relu(P).T não ortogonal) ou "qr" (Q_P @ Q_P.T ortogonal).
  • init_scale (float) — Escala aplicada ao desvio padrão usado para inicializar a matriz de injeção R (usado apenas quando init_weights=False). Valores menores mantêm a atualização injetada mais próxima de zero na inicialização. O valor padrão é 1.0.
  • alpha (Optional[int]) — O fator de escala para o termo de injeção, que é escalado por alpha / r (análogo ao alpha do LoRA). Se None, nenhuma escala é aplicada (fator 1.0). O termo de remoção de subespaço não é afetado.
  • para (bool) — Se deve usar o método PaRa: remoção pura de subespaço (delta = -P_proj @ W) sem termo de injeção. Quando True, R não é criado, P é a única matriz treinável e o adaptador não pode ser uma identidade na inicialização. O padrão é False (DEFT completo).
  • fan_in_fan_out (bool) — Defina como True se a camada a ser substituída armazena pesos como (fan_in, fan_out). Por exemplo, o gpt-2 usa Conv1D, que armazena pesos como (fan_in, fan_out), e portanto isso deve ser definido como True.
  • deft_dropout (float) — A probabilidade de dropout aplicada à entrada da camada. O valor padrão é 0.0.
  • init_weights (bool) — Se deve usar a inicialização padrão (identidade) do DEFT para os pesos do adaptador, de modo que o adaptador seja um no-op no início do treinamento. Não altere esta configuração, exceto se você souber exatamente o que está fazendo. O padrão é True.
  • layers_to_transform (Union[List[int], int]) — Os índices das camadas a serem transformadas. Se uma lista de inteiros for passada, o adaptador será aplicado aos índices das camadas especificados nessa lista. Se um único inteiro for passado, as transformações serão aplicadas à camada nesse índice.
  • layers_pattern (Optional[Union[List[str], str]]) — O nome do padrão de camadas, usado apenas se layers_to_transform for diferente de None. Isso deve apontar para o nn.ModuleList do modelo, que frequentemente é chamado de 'layers' ou 'h'.
  • bias (str) — Tipo de viés para DEFT. Pode ser 'none', 'all' ou 'deft_only'.
  • modules_to_save (List[str]) — Lista de módulos, além das camadas de adaptador, que devem ser configurados como treináveis e salvos no checkpoint final.

Esta é a classe de configuração para armazenar a configuração de um DeftModel.

DEFT (Decompositional Efficient Fine-Tuning) realiza a injeção de conhecimento por meio de uma atualização de projeção residual. Para um peso base congelado W, uma direção de projeção de baixo rank P (forma out_features x r) e uma matriz de injeção R (forma r x in_features) são aprendidos. O peso adaptado é W' = (I - P_proj) @ W + Q_P @ R, onde o projetor P_proj é derivado de P de acordo com decomposition_method:

  • "relu" (padrão): Q_P = P, P_proj = P @ relu(P).T (projeção não ortogonal)
  • "qr": Q_P = qr(P), P_proj = Q_P @ Q_P.T (projeção ortogonal)

Por padrão (init_weights=True), R é inicializado de modo que a atualização seja uma identidade exata na inicialização (o peso adaptado é igual a W), de modo que o treinamento começa a partir dos pesos pré-treinados e aprende a injeção.

DeftModel

classe 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) — O modelo ao qual as camadas do adaptador tuner serão anexadas.
  • config (DeftConfig) — A configuração do modelo DEFT.
  • adapter_name (str) — O nome do adaptador, padrão é "default".
  • low_cpu_mem_usage (bool, optional, defaults to False) — Cria pesos de adaptador vazios no dispositivo meta. Útil para acelerar o processo de carregamento.

Retorna

torch.nn.Module

O modelo DEFT.

Cria um modelo DEFT (Decompositional Efficient Fine-Tuning) a partir de um modelo pré-treinado.

DEFT congela os pesos base e aprende, para cada módulo de destino, uma direção de projeção de baixo posto P e uma matriz de injeção R. O peso efetivo se torna (I - P_proj) @ W + Q_P @ R, substituindo um subespaço de W por conteúdo recém-injetado (veja DeftConfig para as variantes disponíveis de decomposition_method).

Atributos:

  • model (~torch.nn.Module) — O modelo a ser adaptado.
  • peft_config (DeftConfig): A configuração do modelo DEFT.
Update on GitHub

←C3A DeLoRA→