# WaveFT: Wavelet Fine-Tuning

[WaveFT](https://huggingface.co/papers/2505.12532) é um novo método de ajuste fino eficiente em parâmetros (PEFT) que introduz atualizações esparsas no **domínio de wavelets** das matrizes residuais. Diferentemente do LoRA, que é limitado por escolhas discretas de baixo posto, o WaveFT permite um controle fino sobre o número de parâmetros treináveis ao aprender diretamente um conjunto esparsos de coeficientes no espaço transformado. Esses coeficientes são então mapeados de volta para o domínio dos pesos por meio da Transformada Inversa Discreta de Wavelets (IDWT), produzindo atualizações de alto posto sem incorrer em sobrecarga de inferência.

O WaveFT possui atualmente a seguinte restrição:

- Apenas camadas `nn.Linear` são suportadas.

O resumo do artigo é:

>Adaptar eficientemente grandes modelos de fundação é crítico, especialmente com orçamentos apertados de computação e memória. Os métodos de Fine-Tuning Eficiente em Parâmetros (PEFT), como o LoRA, oferecem granularidade e eficácia limitadas em regimes de poucos parâmetros. Propomos o Wavelet Fine-Tuning (WaveFT), um novo método de PEFT que aprende atualizações altamente esparsas no domínio wavelet de matrizes residuais. O WaveFT permite controle preciso dos parâmetros treináveis, oferecendo ajuste fino de capacidade e se destacando com contagem de parâmetros notavelmente baixa, potencialmente muito menor que o mínimo do LoRA — ideal para cenários de eficiência extrema em parâmetros. Avaliado na geração personalizada de texto para imagem usando o Stable Diffusion XL como linha de base, o WaveFT supera significativamente o LoRA e outros métodos de PEFT, especialmente com contagens baixas de parâmetros; alcançando superioridade em fidelidade do sujeito, alinhamento com o prompt e diversidade de imagem.

## Visão geral do benchmark

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=WAVEFT" frameborder="0" width="850" height="1000"
>

# API

## WaveFTConfig[[peft.WaveFTConfig]]

#### peft.WaveFTConfig[[peft.WaveFTConfig]]

```python
peft.WaveFTConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, n_frequency: int = 2592, scaling: float = 25.0, wavelet_family: str = 'db1', use_idwt: bool = True, random_loc_seed: int = 777, fan_in_fan_out: bool = False, target_modules: Optional[Union[list[str], str]] = None, exclude_modules: Optional[Union[list[str], str]] = None, bias: str = 'none', modules_to_save: Optional[list[str]] = None, layers_to_transform: Optional[Union[list[int], int]] = None, layers_pattern: Optional[Union[list[str], str]] = None, n_frequency_pattern: Optional[dict] = <factory>, proportional_parameters: bool = False, init_weights: bool = True)
```

[Fonte](https://github.com/huggingface/peft/blob/main/src/peft/tuners/waveft/config.py#L27)

**Parâmetros:**

n_frequency (`int`) : Número de coeficientes de wavelet aprendíveis para a Transformada Wavelet Discreta (DWT). 'n_frequency' é um inteiro maior que 0 e menor ou igual ao número total de elementos na matriz de pesos original (d_out * d_in). Este parâmetro controla diretamente o número de parâmetros treináveis para cada camada adaptada. Um 'n_frequency' mais alto geralmente leva a um melhor desempenho, mas também aumenta o uso de memória da GPU, com um impacto menor na velocidade de treinamento.

scaling (`float`) : O fator de escala aplicado à matriz delta W reconstruída. Este é um hiperparâmetro crucial, análogo a `lora_alpha` no LoRA. Ele pode ser ajustado durante a busca de hiperparâmetros. Nosso valor padrão para personalização do SDXL é 25.

wavelet_family (`str`) : A família de wavelets (por exemplo, 'db1', 'sym2', 'coif1') a ser usada para a DWT e a DWT Inversa (IDWT). O padrão é 'db1' (wavelet Haar). Diferentes famílias de wavelets possuem comprimentos de filtro variados, o que afeta substancialmente o tempo de treinamento

use_idwt (`bool`) : Defina como False para adaptação eficiente. Indica se a Transformada Inversa da Onda Discreta (IDWT) deve ser usada para reconstruir os pesos delta a partir dos coeficientes de onda aprendidos. Se `True` (padrão), a IDWT é aplicada. Se `False`, os coeficientes aprendidos são usados diretamente para formar uma matriz de pesos delta esparsa, o que é mais rápido, porém tem desempenho inferior para a tarefa de personalização do SDXL.

random_loc_seed (`int`) : Semente para determinar as localizações aleatórias dos `n_frequency` coeficientes de wavelet aprendíveis dentro da matriz completa de coeficientes de wavelet.

target_modules (`Union[list[str],str]`) : Lista de nomes de módulos ou uma expressão regular que identifica os módulos a serem adaptados com WaveFT. Por exemplo, `['q_proj', 'v_proj']` ou `'.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$'`. Atualmente, apenas camadas lineares (`torch.nn.Linear`) são suportadas.

exclude_modules (`Optional[Union[List[str], str]]`) : Lista de nomes de módulos ou uma expressão regular para módulos a serem excluídos da adaptação WaveFT.

fan_in_fan_out (`bool`) : Defina como `True` se os pesos da camada a ser substituída estiverem armazenados no formato `(fan_in, fan_out)`. O padrão é `False`.

bias (`str`) : Tipo de viés para WaveFT. Pode ser 'none', 'all' ou 'waveft_only'. ('fourier_only' provavelmente era um erro de digitação e foi corrigido para 'waveft_only' se implicar viés apenas nos parâmetros adaptados) Se 'waveft_only', os vieses são adicionados apenas aos componentes do WaveFT. Se 'all', os vieses são adicionados tanto aos componentes base quanto aos do WaveFT. Se 'none', nenhum novo viés é adicionado.

modules_to_save (`list[str]`) : Lista de módulos, além das camadas do WaveFT, que devem ser marcados como treináveis e salvos no checkpoint final. Útil para camadas como classificadores em tarefas de classificação de sequência ou de token que são inicializadas aleatoriamente e precisam de treinamento.

layers_to_transform (`Union[list[int],int]`) : Índices específicos de camadas a serem transformadas. Se fornecido, o PEFT adaptará apenas as camadas nesses índices. Se um único inteiro for fornecido, apenas essa camada será transformada.

layers_pattern (`Optional[Union[List[str], str]]`) : Padrão para nomes de camadas, usado quando `layers_to_transform` é especificado e o padrão da camada não é padrão (por exemplo, não é 'layers' ou 'h'). Isso deve apontar para o atributo `nn.ModuleList` no modelo.

n_frequency_pattern (`dict`) : Um dicionário que mapeia nomes de camadas (ou regex) para valores específicos de `n_frequency`, sobrescrevendo o `n_frequency` global. Exemplo: `{"model.decoder.layers.0.encoder_attn.k_proj": 1000}`.

init_weights (`bool`) : Estratégia de inicialização para os coeficientes de wavelet aprendíveis (espectro). Se `True` (padrão), os coeficientes são inicializados com zeros. Se `False`, os coeficientes são inicializados a partir de uma distribuição normal padrão escalada por um pequeno fator.

proportional_parameters (`bool`) : Se `True`, `n_frequency` é alocado proporcionalmente ao `input_dim * output_dim` de cada camada. O padrão é `False`. Observação: esta opção está incluída para exaustividade experimental, permitindo que pesquisadores reproduzam os resultados do artigo, em vez de por utilidade prática, já que nenhum cenário benéfico foi identificado.

Esta é a classe de configuração para armazenar a configuração de um [WaveFTModel](/docs/peft/main/pt/package_reference/waveft#peft.WaveFTModel). Ela é usada para definir os parâmetros para o Fine-Tuning baseado em Wavelets (WaveFT), uma abordagem que aproveita a esparsidade das transformadas wavelet para o fine-tuning eficiente em parâmetros de modelos pré-treinados.

## WaveFTModel[[peft.WaveFTModel]]

#### peft.WaveFTModel[[peft.WaveFTModel]]

```python
peft.WaveFTModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[Fonte](https://github.com/huggingface/peft/blob/main/src/peft/tuners/waveft/model.py#L30)

