diffusers/v0.43.0/pt/api/loaders/peft.md

PEFT

O Diffusers suporta o carregamento de adaptadores, como LoRA, com a biblioteca PEFT por meio da classe PeftAdapterMixin. Isso permite que as classes de modelagem do Diffusers, como UNet2DConditionModel e SD3Transformer2DModel, operem com um adaptador.

Consulte o tutorial Inference with PEFT para uma visão geral de como usar PEFT no Diffusers para inferência.

PeftAdapterMixin[[diffusers.loaders.PeftAdapterMixin]]

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

diffusers.loaders.PeftAdapterMixin()

Fonte

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 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]]

active_adapters()

Fonte

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 do PEFT.

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

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

Fonte

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 do PEFT.

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

delete_adapters(adapter_names: list[str] | str)

Fonte

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:

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]]

disable_adapters()

Fonte

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 do PEFT.

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

disable_lora()

Fonte

Desativa as camadas LoRA ativas do modelo subjacente.

Exemplo:

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]]

enable_adapters()

Fonte

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 do PEFT.

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

enable_lora()

Fonte

Ativa as camadas LoRA ativas do modelo subjacente.

Exemplo:

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]]

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

Fonte

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]]

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

Fonte

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(). - Um torch 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.

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]]

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

Fonte

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]]

set_adapter(adapter_name: str | list[str])

Fonte

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 do PEFT.

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

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

Fonte

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:

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])