# PEFT

O Diffusers suporta o carregamento de adaptadores, como [LoRA](../../tutorials/using_peft_for_inference), com a biblioteca [PEFT](https://huggingface.co/docs/peft/index) por meio da classe [PeftAdapterMixin](/docs/diffusers/v0.43.0/pt/api/loaders/peft#diffusers.loaders.PeftAdapterMixin). Isso permite que as classes de modelagem do Diffusers, como [UNet2DConditionModel](/docs/diffusers/v0.43.0/pt/api/models/unet2d-cond#diffusers.UNet2DConditionModel) e [SD3Transformer2DModel](/docs/diffusers/v0.43.0/pt/api/models/sd3_transformer2d#diffusers.SD3Transformer2DModel), operem com um adaptador.

> [!TIP]
> Consulte o tutorial [Inference with PEFT](../../tutorials/using_peft_for_inference) para uma visão geral de como usar PEFT no Diffusers para inferência.

## PeftAdapterMixin[[diffusers.loaders.PeftAdapterMixin]]

#### diffusers.loaders.PeftAdapterMixin[[diffusers.loaders.PeftAdapterMixin]]

```python
diffusers.loaders.PeftAdapterMixin()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L62)

Uma classe que contém todas as funções para carregar e usar pesos de adaptadores suportados na biblioteca PEFT. Para mais detalhes sobre adaptadores e como injetá-los em um modelo base, consulte a [documentação](https://huggingface.co/docs/peft/index) do PEFT.

Instale a versão mais recente do PEFT e use este mixin para:

- Anexe novos adaptadores no modelo.
- Anexe vários adaptadores e ative/desative-os iterativamente.
- Ativar/desativar todos os adaptadores do modelo.
- Obtenha uma lista dos adaptadores ativos.

#### active_adapters[[diffusers.loaders.PeftAdapterMixin.active_adapters]]

```python
active_adapters()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L652)

Obtém a lista atual de adaptadores ativos do modelo.

Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na [documentação](https://huggingface.co/docs/peft) do PEFT.

#### add_adapter[[diffusers.loaders.PeftAdapterMixin.add_adapter]]

```python
add_adapter(adapter_config, adapter_name: str = 'default')
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L518)

**Parâmetros:**

adapter_config (`[~peft.PeftConfig]`) : A configuração do adaptador a ser adicionado; os adaptadores suportados são os métodos de non-prefix tuning e adaption prompt.

adapter_name (`str`, *opcional*, padrão `"default"`) : O nome do adaptador a ser adicionado. Se nenhum nome for passado, um nome padrão será atribuído ao adaptador.

Adiciona um novo adaptador ao modelo atual para treinamento. Se nenhum nome de adaptador for passado, um nome padrão será atribuído ao adaptador para seguir a convenção da biblioteca PEFT.

Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na [documentação](https://huggingface.co/docs/peft) do PEFT.

#### delete_adapters[[diffusers.loaders.PeftAdapterMixin.delete_adapters]]

```python
delete_adapters(adapter_names: list[str] | str)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L777)

**Parâmetros:**

adapter_names (`list[str, str]`) : Os nomes (string única ou lista de strings) do adaptador a ser excluído.

Exclui as camadas LoRA de um adaptador do modelo subjacente.

Exemplo:

```py
from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_names="cinematic"
)
pipeline.unet.delete_adapters("cinematic")
```

#### disable_adapters[[diffusers.loaders.PeftAdapterMixin.disable_adapters]]

```python
disable_adapters()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L607)

Desative todos os adaptadores anexados ao modelo e volte a fazer inferência apenas com o modelo base.

Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na [documentação](https://huggingface.co/docs/peft) do PEFT.

#### disable_lora[[diffusers.loaders.PeftAdapterMixin.disable_lora]]

```python
disable_lora()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L731)

Desativa as camadas LoRA ativas do modelo subjacente.

Exemplo:

```py
from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.unet.disable_lora()
```

#### enable_adapters[[diffusers.loaders.PeftAdapterMixin.enable_adapters]]

```python
enable_adapters()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L629)

Ative os adaptadores que estão anexados ao modelo. O modelo usa `self.active_adapters()` para recuperar a lista de adaptadores a serem ativados.

Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na [documentação](https://huggingface.co/docs/peft) do PEFT.

#### enable_lora[[diffusers.loaders.PeftAdapterMixin.enable_lora]]

```python
enable_lora()
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L754)

Ativa as camadas LoRA ativas do modelo subjacente.

Exemplo:

```py
from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.unet.enable_lora()
```

#### enable_lora_hotswap[[diffusers.loaders.PeftAdapterMixin.enable_lora_hotswap]]

```python
enable_lora_hotswap(target_rank: int = 128, check_compiled: typing.Literal['error', 'warn', 'ignore'] = 'error')
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L815)

**Parâmetros:**

target_rank (`int`, *opcional*, padrão `128`) : O maior rank entre todos os adaptadores que serão carregados.

check_compiled (`str`, *opcional*, padrão `"error"`) : Como lidar com o caso em que o modelo já está compilado, o que geralmente deve ser evitado. As opções são: - "error" (padrão): levantar um erro - "warn": emitir um aviso - "ignore": não fazer nada

Permite a possibilidade de trocar adaptadores LoRA em tempo de execução.

A chamada deste método é necessária apenas ao trocar adaptadores dinamicamente e se o modelo estiver compilado ou se os ranks dos adaptadores carregados forem diferentes.

#### load_lora_adapter[[diffusers.loaders.PeftAdapterMixin.load_lora_adapter]]

```python
load_lora_adapter(pretrained_model_name_or_path_or_dict, prefix = 'transformer', hotswap: bool = False, **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L85)

**Parâmetros:**

pretrained_model_name_or_path_or_dict (`str` ou `os.PathLike` ou `dict`) : Pode ser:  - Uma string, o *model id* (por exemplo `google/ddpm-celebahq-256`) de um modelo pré-treinado hospedado no Hub. - Um caminho para um *diretório* (por exemplo `./my_model_directory`) contendo os pesos do modelo salvos com [ModelMixin.save_pretrained()](/docs/diffusers/v0.43.0/pt/api/models/overview#diffusers.ModelMixin.save_pretrained). - Um [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

prefix (`str`, *opcional*) : Prefixo para filtrar o state dict.

cache_dir (`str | os.PathLike`, *opcional*) : Caminho para um diretório onde a configuração de um modelo pré-treinado baixado é armazenada em cache, caso o cache padrão não seja utilizado.

force_download (`bool`, *opcional*, padrão `False`) : Se deve forçar o (re-)download dos pesos do modelo e dos arquivos de configuração, sobrescrevendo as versões em cache, caso existam.

proxies (`dict[str, str]`, *opcional*) : Um dicionário de servidores proxy a serem usados por protocolo ou endpoint, por exemplo, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Os proxies são usados em cada solicitação.

local_files_only (`bool`, *opcional*, padrão `False`) : Se deve carregar apenas os pesos e os arquivos de configuração do modelo localmente ou não. Se definido como `True`, o modelo não será baixado do Hub.

token (`str` ou *bool*, *opcional*) : O token a ser usado como autorização HTTP bearer para arquivos remotos. Se `True`, o token gerado por `diffusers-cli login` (armazenado em `~/.huggingface`) é utilizado.

revision (`str`, *opcional*, padrão `"main"`) : A versão específica do modelo a ser usada. Pode ser o nome de um branch, o nome de uma tag, um id de commit ou qualquer identificador permitido pelo Git.

subfolder (`str`, *opcional*, padrão `""`) : A localização da subpasta de um arquivo de modelo dentro de um repositório de modelo maior no Hub ou localmente.

network_alphas (`dict[str, float]`) : O valor do alfa da rede usado para aprendizado estável e prevenção de underflow. Este valor tem o mesmo significado que a opção `--network_alpha` no script de treinamento do kohya-ss. Consulte [este link](https://github.com/darkstorm2150/sd-scripts/blob/main/docs/train_network_README-en.md#execute-learning).

low_cpu_mem_usage (`bool`, *opcional*) : Acelera o carregamento do modelo carregando apenas os pesos LoRA pré-treinados e não inicializando os pesos aleatórios.

hotswap : (`bool`, *opcional*) O valor padrão é `False`. Se deve substituir um adaptador (LoRA) existente pelo adaptador recém-carregado no local. Isso significa que, em vez de carregar um adaptador adicional, isso pegará os pesos do adaptador existente e os substituirá pelos pesos do novo adaptador. Isso pode ser mais rápido e eficiente em termos de memória. No entanto, a principal vantagem do hotswap é que, quando o modelo é compilado com torch.compile, o carregamento do novo adaptador não requer a recompilação do modelo. Ao usar hotswap, o `adapter_name` passado deve ser o nome de um adaptador já carregado. Se o novo adaptador e o antigo tiverem ranks e/ou alfas LoRA (ou seja, escalonamento) diferentes, você precisa chamar um método adicional antes de carregar o adaptador: ```py pipeline = ...  # load diffusers pipeline max_rank = ...  # the highest rank among all LoRAs that you want to load # call *before* compiling and loading the LoRA adapter pipeline.enable_lora_hotswap(target_rank=max_rank) pipeline.load_lora_weights(file_name) # optionally compile the model now ``` Observe que o hotswap de adaptadores do codificador de texto ainda não é suportado. Existem algumas limitações adicionais a essa técnica, que estão documentadas aqui: https://huggingface.co/docs/peft/main/en/package_reference/hotswap

metadata : Metadados do adaptador LoRA. Quando fornecidos, os metadados inferidos através do state dict não são usados para inicializar `LoraConfig`.

Carrega um adaptador LoRA no modelo subjacente.

#### save_lora_adapter[[diffusers.loaders.PeftAdapterMixin.save_lora_adapter]]

```python
save_lora_adapter(save_directory, adapter_name: str = 'default', upcast_before_saving: bool = False, safe_serialization: bool = True, weight_name: str | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L394)

**Parâmetros:**

save_directory (`str` ou `os.PathLike`) : Diretório para salvar os parâmetros LoRA. Será criado se não existir.

adapter_name : (`str`, padrão "default"): O nome do adaptador a ser serializado. Útil quando o modelo subjacente tem vários adaptadores carregados.

upcast_before_saving (`bool`, padrão `False`) : Se deve converter o modelo subjacente para `torch.float32` antes da serialização.

safe_serialization (`bool`, *opcional*, padrão `True`) : Se o modelo deve ser salvo usando `safetensors` ou da maneira tradicional do PyTorch com `pickle`.

weight_name : (`str`, *opcional*, padrão `None`): Nome do arquivo para serializar o state dict.

Salve os parâmetros do LoRA correspondentes ao modelo subjacente.

#### set_adapter[[diffusers.loaders.PeftAdapterMixin.set_adapter]]

```python
set_adapter(adapter_name: str | list[str])
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L558)

**Parâmetros:**

adapter_name (str | list[str])) : A lista de adaptadores a serem definidos ou o nome do adaptador, no caso de um único adaptador.

Define um adaptador específico, forçando o modelo a usar apenas esse adaptador e desativando os outros adaptadores.

Se você não está familiarizado com adaptadores e métodos PEFT, convidamos você a ler mais sobre eles na [documentação](https://huggingface.co/docs/peft) do PEFT.

#### set_adapters[[diffusers.loaders.PeftAdapterMixin.set_adapters]]

```python
set_adapters(adapter_names: list[str] | str, weights: float | dict | list[float] | list[dict] | list[None] | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/peft.py#L462)

**Parâmetros:**

adapter_names (`list[str]` ou `str`) : Os nomes dos adaptadores a serem usados.

weights (`Union[List[float], float]`, *opcional*) : Os pesos do(s) adaptador(es) a serem usados com o UNet. Se `None`, os pesos são definidos como `1.0` para todos os adaptadores.

Defina os adaptadores atualmente ativos para uso na rede de difusão (por exemplo, unet, transformer, etc.).

Exemplo:

```py
from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.load_lora_weights("nerijs/pixel-art-xl", weight_name="pixel-art-xl.safetensors", adapter_name="pixel")
pipeline.unet.set_adapters(["cinematic", "pixel"], weights=[0.5, 0.5])
```