diffusers/main/pt/api/models/overview.md

Modelos

🤗 O Diffusers fornece modelos pré-treinados para algoritmos populares e módulos para criar sistemas de difusão personalizados. A função principal dos modelos é desruidar uma amostra de entrada, conforme modelado pela distribuição $p_{\theta }(x_{t-1}\mathrm{\mid }{x}_t)p\_\{\backslash theta\}(x\_\{t-1\}|x\_\{t\})$.

Todos os modelos são construídos a partir da classe base ModelMixin, que é um torch.nn.Module que fornece funcionalidade básica para salvar e carregar modelos, localmente e do Hugging Face Hub.

ModelMixin[[diffusers.ModelMixin]]

diffusers.ModelMixin[[diffusers.ModelMixin]]

diffusers.ModelMixin()

Fonte

Classe base para todos os modelos.

ModelMixin cuida do armazenamento da configuração do modelo e fornece métodos para carregar, baixar e salvar modelos.

• config_name (str) -- Nome do arquivo para salvar um modelo ao chamar save_pretrained().

compile_repeated_blocks[[diffusers.ModelMixin.compile_repeated_blocks]]

compile_repeated_blocks(*args, **kwargs)

Fonte

Compila apenas os submódulos frequentemente repetidos de um modelo (por exemplo, as camadas Transformer), em vez de compilar o modelo inteiro. Essa técnica — frequentemente chamada de compilação regional (veja a receita do PyTorch https://docs.pytorch.org/tutorials/recipes/regional_compilation.html) — pode reduzir substancialmente o tempo de compilação de ponta a ponta, preservando as acelerações de tempo de execução que você esperaria de um torch.compile completo.

O conjunto de submódulos a serem compilados é descoberto pela presença do atributo _repeated_blocks na definição do modelo. Defina esse atributo na subclasse do seu modelo como uma lista/tupla de nomes de classes (strings). Todo módulo cujo nome de classe corresponder será compilado.

Uma vez descobertos, cada submódulo correspondente é compilado chamando submodule.compile(*args, **kwargs). Quaisquer argumentos posicionais ou por nome que você fornecer para compile_repeated_blocks são encaminhados literalmente para torch.compile.

cuda[[diffusers.ModelMixin.cuda]]

cuda(*args, **kwargs)

Um valor simulado para um caminho pontilhado (por exemplo, torch.float32): as cadeias de acesso a atributos e as chamadas se comportam como decoradores de passagem, o repr é o caminho pontilhado, e o uso como classe base substitui uma base de type simples (PEP 560 __mro_entries__), de modo que as subclasses reais mantêm um metaclass normal e o inspect.signature lê o __init__ real delas, em vez do de um mock.

dequantize[[diffusers.ModelMixin.dequantize]]

dequantize()

Fonte

Potencialmente desquantize o modelo, caso ele tenha sido quantizado por um método de quantização que suporte desquantização.

disable_gradient_checkpointing[[diffusers.ModelMixin.disable_gradient_checkpointing]]

disable_gradient_checkpointing()

Fonte

Desativa o checkpointing de gradientes para o modelo atual (pode ser referido como activation checkpointing ou checkpoint activations em outros frameworks).

disable_npu_flash_attention[[diffusers.ModelMixin.disable_npu_flash_attention]]

disable_npu_flash_attention()

Fonte

desativar npu flash attention do torch_npu

disable_xformers_memory_efficient_attention[[diffusers.ModelMixin.disable_xformers_memory_efficient_attention]]

disable_xformers_memory_efficient_attention()

Fonte

Desative a atenção eficiente em memória do xFormers.

disable_xla_flash_attention[[diffusers.ModelMixin.disable_xla_flash_attention]]

disable_xla_flash_attention()

Fonte

Desative o kernel pallals de flash attention para torch_xla.

enable_gradient_checkpointing[[diffusers.ModelMixin.enable_gradient_checkpointing]]

enable_gradient_checkpointing(gradient_checkpointing_func: typing.Optional[typing.Callable] = None)

Fonte

Parâmetros:

gradient_checkpointing_func (Callable, opcional) : A função a ser usada para checkpointing de gradiente. Se None, a função padrão de checkpointing do PyTorch é usada (torch.utils.checkpoint.checkpoint).

Ativa o checkpointing de gradiente para o modelo atual (pode ser referido como activation checkpointing ou checkpoint activations em outros frameworks).

enable_group_offload[[diffusers.ModelMixin.enable_group_offload]]

enable_group_offload(onload_device: device, offload_device: device = torch.device(), offload_type: str = 'block_level', num_blocks_per_group: int | None = None, non_blocking: bool = False, use_stream: bool = False, record_stream: bool = False, low_cpu_mem_usage = False, offload_to_disk_path: str | None = None, block_modules: str | None = None, exclude_kwargs: str | None = None)

Fonte

Ativa o offloading de grupo para o modelo atual.

Veja apply_group_offloading() para mais informações.

Exemplo:

>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> transformer.enable_group_offload(
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="leaf_level",
...     use_stream=True,
... )

enable_layerwise_casting[[diffusers.ModelMixin.enable_layerwise_casting]]

enable_layerwise_casting(storage_dtype: dtype = torch.float8_e4m3fn, compute_dtype: typing.Optional[torch.dtype] = None, skip_modules_pattern: tuple[str, ...] | None = None, skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = None, non_blocking: bool = False)

Fonte

Parâmetros:

storage_dtype (torch.dtype) : O dtype para o qual o modelo deve ser convertido para armazenamento.

compute_dtype (torch.dtype) : O dtype para o qual os pesos do modelo devem ser convertidos durante a passagem para frente.

skip_modules_pattern (tuple[str, ...], opcional) : Uma lista de padrões para corresponder aos nomes dos módulos a serem ignorados durante o processo de conversão por camada. Se definido como None, padrões de exclusão padrão são usados para ignorar certas camadas internas de módulos e camadas PEFT.

skip_modules_classes (tuple[Type[torch.nn.Module], ...], opcional) : Uma lista de classes de módulos para ignorar durante o processo de conversão por camada.

non_blocking (bool, opcional, padrão False) : Se True, as operações de conversão de pesos são não bloqueantes.

Ativa o casting por camada para o modelo atual.

O casting por camada é uma técnica que converte os pesos do modelo para um dtype de menor precisão para armazenamento, mas os converte dinamicamente para um dtype de maior precisão para o cálculo. Esse processo pode reduzir significativamente a pegada de memória dos pesos do modelo, mas pode levar a alguma degradação de qualidade nas saídas. A maioria das degradações é insignificante, decorrente principalmente do casting de pesos em camadas de normalização e modulação.

Por padrão, a maioria dos modelos em diffusers define o atributo _skip_layerwise_casting_patterns para ignorar as camadas de incorporação de patch, incorporação posicional e normalização. Isso ocorre porque essas camadas são provavelmente críticas em termos de precisão para a qualidade. Se você deseja alterar esse comportamento, pode definir o atributo _skip_layerwise_casting_patterns como None ou chamar apply_layerwise_casting() com argumentos personalizados.

Exemplo:

Usando enable_layerwise_casting():

>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> # Enable layerwise casting via the model, which ignores certain modules by default
>>> transformer.enable_layerwise_casting(storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16)

enable_npu_flash_attention[[diffusers.ModelMixin.enable_npu_flash_attention]]

enable_npu_flash_attention()

Fonte

Ativar npu flash attention do torch_npu

enable_xformers_memory_efficient_attention[[diffusers.ModelMixin.enable_xformers_memory_efficient_attention]]

enable_xformers_memory_efficient_attention(attention_op: typing.Optional[typing.Callable] = None)

Fonte

Parâmetros:

attention_op (Callable, opcional) : Substitui o operador padrão None para uso como argumento op da função memory_efficient_attention() do xFormers.

Ative a atenção eficiente em memória do xFormers.

Quando essa opção está habilitada, você deve observar um menor uso de memória de GPU e uma possível aceleração durante a inferência. A aceleração durante o treinamento não é garantida.

> ⚠️ Quando a atenção eficiente em memória e a atenção fatiada estão ambas habilitadas, a atenção eficiente attention tem > precedência.

Exemplos:

>>> import torch
>>> from diffusers import UNet2DConditionModel
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> model = UNet2DConditionModel.from_pretrained(
...     "stabilityai/stable-diffusion-2-1", subfolder="unet", torch_dtype=torch.float16
... )
>>> model = model.to("cuda")
>>> model.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)

enable_xla_flash_attention[[diffusers.ModelMixin.enable_xla_flash_attention]]

enable_xla_flash_attention(partition_spec: typing.Optional[typing.Callable] = None, **kwargs)

Fonte

Ative o kernel pallals de flash attention para torch_xla.

from_pretrained[[diffusers.ModelMixin.from_pretrained]]

from_pretrained(pretrained_model_name_or_path: str | os.PathLike | None, **kwargs)

Fonte

Parâmetros:

pretrained_model_name_or_path (str ou os.PathLike, opcional) : Pode ser: - Uma string, o id do modelo (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 save_pretrained().

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.

dtype (torch.dtype, opcional) : Substitui o torch.dtype padrão e carrega o modelo com outro dtype.

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.

output_loading_info (bool, opcional, padrão False) : Se deve ou não retornar também um dicionário contendo chaves ausentes, chaves inesperadas e mensagens de erro.

local_files_only(bool, opcional, padrão False) : Se deve carregar apenas os pesos e os arquivos de configuração do modelo localmente. 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.

mirror (str, opcional) : Espelho de origem para resolver problemas de acessibilidade se você estiver baixando um modelo na China. Não garantimos a pontualidade ou a segurança da origem, e você deve consultar o site do espelho para obter mais informações.

device_map (int | str | torch.device ou dict[str, int | str | torch.device], opcional) : Um mapa que especifica para onde cada submódulo deve ser enviado. Não precisa ser definido para cada nome de parâmetro/buffer; uma vez que um determinado nome de módulo esteja incluído, todos os seus submódulos serão enviados para o mesmo dispositivo. O padrão é None, o que significa que o modelo será carregado na CPU. Exemplos: py >>> from diffusers import AutoModel >>> import torch >>> # This works. >>> model = AutoModel.from_pretrained( ... "stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", device_map="cuda" ... ) >>> # This also works (integer accelerator device ID). >>> model = AutoModel.from_pretrained( ... "stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", device_map=0 ... ) >>> # Specifying a supported offloading strategy like "auto" also works. >>> model = AutoModel.from_pretrained( ... "stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", device_map="auto" ... ) >>> # Specifying a dictionary as `device_map` also works. >>> model = AutoModel.from_pretrained( ... "stabilityai/stable-diffusion-xl-base-1.0", ... subfolder="unet", ... device_map={"": torch.device("cuda")}, ... ) Defina device_map="auto" para que o 🤗 Accelerate calcule automaticamente o device_map mais otimizado. Para mais informações sobre cada opção, consulte projetando um mapa de dispositivos. Você também pode se referir à documentação específica do Diffusers para exemplos mais concretos.

max_memory (Dict, opcional) : Um dicionário com o identificador de dispositivo para a memória máxima. Se não for definido, o padrão será a memória máxima disponível para cada GPU e a RAM disponível na CPU.

offload_folder (str ou os.PathLike, opcional) : O caminho para descarregar os pesos se device_map contiver o valor "disk".

offload_state_dict (bool, opcional) : Se True, descarrega temporariamente o state dict da CPU para o disco rígido para evitar a falta de RAM na CPU caso o peso do state dict da CPU + o maior shard do checkpoint não caiba. O padrão é True quando há algum offload para o disco.

low_cpu_mem_usage (bool, opcional, padrão é True se a versão do torch >= 1.9.0, caso contrário False) : Acelera o carregamento do modelo carregando apenas os pesos pré-treinados e não inicializando os pesos. Isso também tenta não usar mais do que 1x o tamanho do modelo na memória de CPU (incluindo a memória de pico) durante o carregamento do modelo. Suportado apenas para PyTorch >= 1.9.0. Se você estiver usando uma versão mais antiga do PyTorch, definir este argumento como True causará um erro.

variant (str, opcional) : Carrega os pesos de um nome de arquivo variant especificado, como "fp16" ou "ema".

use_safetensors (bool, opcional, padrão None) : Se definido como None, os pesos safetensors são baixados se estiverem disponíveis e se a biblioteca safetensors estiver instalada. Se definido como True, o modelo é carregado forçadamente a partir dos pesos safetensors. Se definido como False, os pesos safetensors não são carregados.

disable_mmap ('bool', opcional, padrão 'False') : Se deve desabilitar o mmap ao carregar um modelo Safetensors. Essa opção pode ter um desempenho melhor quando o modelo está em uma montagem de rede ou em um disco rígido, que podem não lidar bem com a natureza de buscas do mmap.

use_flashpack (bool, opcional, padrão False) : Se definido como True, o modelo é carregado a partir dos pesos do flashpack.

flashpack_kwargs(dict[str, Any], opcional, padrão {}) : Kwargs passados para flashpack.deserialization.assign_from_file

Instanciar um modelo PyTorch pré-treinado a partir de uma configuração de modelo pré-treinado.

O modelo é definido no modo de avaliação - model.eval() - por padrão, e os módulos de dropout são desativados. Para treinar o modelo, defina-o novamente no modo de treinamento com model.train().

> Para usar modelos privados ou gated models, faça login com hf > auth login. Você também pode ativar o modo especial > "offline-mode" para usar este método em um > ambiente com firewall.

Exemplo:

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5", subfolder="unet")

Se você receber a mensagem de erro abaixo, é necessário ajustar os pesos para sua tarefa de destino:

Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.

get_memory_footprint[[diffusers.ModelMixin.get_memory_footprint]]

get_memory_footprint(return_buffers = True)

Fonte

Parâmetros:

return_buffers (bool, opcional, padrão True) : Se deve retornar o tamanho dos buffers de tensors no cálculo da pegada de memória. Buffers são tensors que não exigem gradientes e não estão registrados como parâmetros. Por exemplo, a média e o desvio padrão em camadas de batch norm. Consulte: https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

Obtenha a pegada de memória de um modelo. Isso retornará a pegada de memória do modelo atual em bytes. Útil para fazer o benchmark da pegada de memória do modelo atual e projetar alguns testes. Solução inspirada nas discussões do PyTorch: https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

num_parameters[[diffusers.ModelMixin.num_parameters]]

num_parameters(only_trainable: bool = False, exclude_embeddings: bool = False)

Fonte

Parâmetros:

only_trainable (bool, opcional, padrão False) : Se deve retornar apenas o número de parâmetros treináveis.

exclude_embeddings (bool, opcional, padrão False) : Se deve retornar apenas o número de parâmetros que não são de incorporação.

Retorna: int

O número de parâmetros.

Obtém o número de (parâmetros treináveis ou não de incorporação) no módulo.

Exemplo:

from diffusers import UNet2DConditionModel

model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
unet = UNet2DConditionModel.from_pretrained(model_id, subfolder="unet")
unet.num_parameters(only_trainable=True)
859520964

reset_attention_backend[[diffusers.ModelMixin.reset_attention_backend]]

reset_attention_backend()

Fonte

Redefine o backend de atenção para o modelo. As chamadas subsequentes a forward usarão o padrão do ambiente, se definido, ou a atenção de produto escalar de pontos nativa do torch.

save_pretrained[[diffusers.ModelMixin.save_pretrained]]

save_pretrained(save_directory: str | os.PathLike, is_main_process: bool = True, save_function: typing.Optional[typing.Callable] = None, safe_serialization: bool = True, variant: str | None = None, max_shard_size: int | str = '10GB', push_to_hub: bool = False, use_flashpack: bool = False, **kwargs)

Fonte

Parâmetros:

save_directory (str ou os.PathLike) : Diretório para salvar um modelo e seu arquivo de configuração. Será criado se não existir.

is_main_process (bool, opcional, padrão True) : Indica se o processo que está chamando esta função é o processo principal ou não. Útil durante o treinamento distribuído, quando é necessário chamar esta função em todos os processos. Nesse caso, defina is_main_process=True apenas no processo principal para evitar condições de corrida.

save_function (Callable) : A função a ser usada para salvar o dicionário de estado. Útil durante o treinamento distribuído quando você precisa substituir torch.save por outro método. Pode ser configurado com a variável de ambiente DIFFUSERS_SAVE_MODE.

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

variant (str, opcional) : Se especificado, os pesos são salvos no formato pytorch_model.<variant>.bin.

max_shard_size (int ou str, padrão "10GB") : O tamanho máximo de um checkpoint antes de ser fragmentado. Os fragmentos do checkpoint terão, então, cada um um tamanho menor que esse valor. Se expresso como uma string, deve ser composto por dígitos seguidos por uma unidade (como "5GB"). Se expresso como um inteiro, a unidade é bytes. Observe que esse limite será reduzido após um certo período de tempo (a partir de outubro de 2024) para permitir que os usuários façam o upgrade para a versão mais recente do diffusers. Isso visa estabelecer um tamanho padrão comum para este argumento entre as diferentes bibliotecas do ecossistema Hugging Face (transformers e accelerate, por exemplo).

push_to_hub (bool, opcional, padrão False) : Se deve ou não enviar seu modelo para o Hugging Face Hub após salvá-lo. Você pode especificar o repositório para o qual deseja enviar com repo_id (o padrão será o nome de save_directory no seu namespace).

kwargs (dict[str, Any], opcional) : Argumentos de palavra-chave adicionais passados ao método push_to_hub().

Salve um modelo e seu arquivo de configuração em um diretório para que ele possa ser recarregado usando o método de classe from_pretrained().

set_attention_backend[[diffusers.ModelMixin.set_attention_backend]]

set_attention_backend(backend: str)

Fonte

Parâmetros:

backend (str) : O nome do backend a ser definido. Deve ser um dos backends disponíveis definidos em AttentionBackendName. Os backends disponíveis podem ser encontrados em diffusers.attention_dispatch.AttentionBackendName. O padrão é a atenção de produto escalar nativa do torch como backend.

Defina o backend de atenção para o modelo.

set_use_npu_flash_attention[[diffusers.ModelMixin.set_use_npu_flash_attention]]

set_use_npu_flash_attention(valid: bool)

Fonte

Defina o interruptor para a atenção flash do npu.

para[[diffusers.ModelMixin.to]]

to(*args, **kwargs)

Um valor simulado para um caminho pontilhado (por exemplo, torch.float32): as cadeias de acesso a atributos e as chamadas se comportam como decoradores de passagem, o repr é o caminho pontilhado, e o uso como classe base substitui uma base de type simples (PEP 560 __mro_entries__), de modo que as subclasses reais mantêm um metaclass normal e o inspect.signature lê o __init__ real delas, em vez do de um mock.

PushToHubMixin[[diffusers.utils.PushToHubMixin]]

diffusers.utils.PushToHubMixin[[diffusers.utils.PushToHubMixin]]

diffusers.utils.PushToHubMixin()

Fonte

Um Mixin para enviar um modelo, agendador ou pipeline para o Hugging Face Hub.

push_to_hub[[diffusers.utils.PushToHubMixin.push_to_hub]]

push_to_hub(repo_id: str, commit_message: str | None = None, private: bool | None = None, token: str | None = None, create_pr: bool = False, safe_serialization: bool = True, variant: str | None = None, subfolder: str | None = None)

Fonte

Parâmetros:

repo_id (str) : O nome do repositório para o qual você deseja enviar os arquivos do seu modelo, agendador ou pipeline. Deve conter o nome da sua organização ao enviar para uma organização. repo_id também pode ser um caminho para um diretório local.

commit_message (str, opcional) : Mensagem para commit ao fazer push. Padrão é "Upload {object}".

private (bool, opcional) : Se deve tornar o repositório privado. Se None (padrão), o repositório será público, a menos que o padrão da organização seja privado. Este valor é ignorado se o repositório já existir.

token (str, opcional) : O token a ser usado como autorização de bearer HTTP para arquivos remotos. O token gerado ao executar hf auth login (armazenado em ~/.huggingface).

create_pr (bool, opcional, padrão False) : Se deve ou não criar um PR com os arquivos enviados ou fazer o commit diretamente.

safe_serialization (bool, opcional, padrão True) : Se os pesos do modelo devem ou não ser convertidos para o formato safetensors.

variant (str, opcional) : Se especificado, os pesos são salvos no formato pytorch_model.<variant>.bin.

Envie arquivos de modelo, agendador ou pipeline para o 🤗 Hugging Face Hub.

Exemplos:

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-2", subfolder="unet")

# Push the `unet` to your namespace with the name "my-finetuned-unet".
unet.push_to_hub("my-finetuned-unet")

# Push the `unet` to an organization with the name "my-finetuned-unet".
unet.push_to_hub("your-org/my-finetuned-unet")