Hugging Face's logo

Diffusers documentation

Pipelines

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Pipelines

Pipelines oferecem uma maneira simples de executar modelos de difusão de ponta em inferência, agrupando todos os componentes necessários (múltiplos modelos treinados independentemente, agendadores e processadores) em uma única classe de ponta a ponta. Pipelines são flexíveis e podem ser adaptados para usar diferentes agendadores ou até mesmo componentes de modelo.

Todos os pipelines são construídos a partir da classe base DiffusionPipeline, que fornece a funcionalidade básica para carregar, baixar e salvar todos os componentes. Os tipos específicos de pipeline (por exemplo, StableDiffusionPipeline) carregados com from_pretrained() são detectados automaticamente e os componentes do pipeline são carregados e passados para a função __init__ do pipeline.

Você não deve usar a classe DiffusionPipeline para treinamento. Os componentes individuais (por exemplo, UNet2DModel e UNet2DConditionModel) dos pipelines de difusão geralmente são treinados individualmente, então sugerimos trabalhar diretamente com eles.


Os Pipelines não oferecem nenhuma funcionalidade de treinamento. Você notará que o autograd do PyTorch é desativado decorando o método __call__() com o decorador torch.no_grad, pois os pipelines não devem ser usados para treinamento. Se você estiver interessado em treinamento, consulte os guias de Training!

Use API > Pipelines na barra lateral para navegar por todas as referências de pipelines por modalidade. Para fluxos de trabalho orientados a tarefas, comece pelo Quickstart ou por um guia como text-to-image, image-to-image, inpainting ou video generation.

DiffusionPipeline

classe diffusers.DiffusionPipeline

< >

( )

Classe base para todos os pipelines.

DiffusionPipeline armazena todos os componentes (modelos, agendadores e processadores) para pipelines de difusão e fornece métodos para carregar, baixar e salvar modelos. Ele também inclui métodos para:

  • move todos os módulos do PyTorch para o dispositivo de sua escolha
  • ativar/desativar a barra de progresso para a iteração de desruidamento

Atributos de classe:

  • config_name (str) — O nome do arquivo de configuração que armazena os nomes de classe e módulo de todos os componentes do pipeline de difusão.
  • _optional_components (List[str]) — Lista de todos os componentes opcionais que não precisam ser passados para o pipeline para que ele funcione (deve ser sobrescrito pelas subclasses).

__call__

( *args**kwargs )

Chame self como uma função.

dispositivo

< >

( ) → torch.device

Retorna

torch.device

O dispositivo torch no qual o pipeline está localizado. Quando os componentes são divididos entre dispositivos (por exemplo, codificadores de texto na CPU enquanto o backbone de desruidização é executado em um acelerador), o dispositivo do acelerador é retornado.

para

< >

( *args**kwargs ) → DiffusionPipeline

Parâmetros

  • dtype (torch.dtype, opcional) — Retorna um pipeline com o dtype especificado
  • device (torch.Device, opcional) — Retorna um pipeline com o device especificado
  • silence_dtype_warnings (str, opcional, padrão False) — Se deve omitir avisos quando o dtype de destino não é compatível com o device de destino.

Retorna

DiffusionPipeline

O pipeline foi convertido para o dtype e/ou dtype especificado.

Executa a conversão de dtype e/ou device do Pipeline. Um torch.dtype e um torch.device são inferidos a partir dos argumentos de self.to(*args, **kwargs).

> Se o pipeline já tiver o torch.dtype e o torch.device corretos, ele é retornado como está. Caso contrário, > o pipeline retornado é uma cópia de self com o torch.dtype e o torch.device desejados.

Aqui estão as formas de chamar to:

  • to(dtype, silence_dtype_warnings=False) → DiffusionPipeline para retornar um pipeline com o dtype especificado
  • to(device, silence_dtype_warnings=False) → DiffusionPipeline para retornar um pipeline com o device especificado
  • to(device=None, dtype=None, silence_dtype_warnings=False) → DiffusionPipeline para retornar um pipeline com o device e o dtype especificados

componentes de

< >

( )

A propriedade self.components pode ser útil para executar diferentes pipelines com os mesmos pesos e configurações sem alocar memória adicional.

Retorna (dict): Um dicionário contendo todos os módulos necessários para inicializar o pipeline.

Exemplos:

>>> from diffusers import (
...     StableDiffusionPipeline,
...     StableDiffusionImg2ImgPipeline,
...     StableDiffusionInpaintPipeline,
... )

>>> text2img = StableDiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> img2img = StableDiffusionImg2ImgPipeline(**text2img.components)
>>> inpaint = StableDiffusionInpaintPipeline(**text2img.components)

disable_attention_slicing

< >

( )

Desativa o cálculo de atenção fatiado. Se enable_attention_slicing foi chamado anteriormente, a atenção é calculada em uma única etapa.

disable_xformers_memory_efficient_attention

< >

( )

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

download

< >

( pretrained_model_name**kwargs ) → os.PathLike

Parâmetros

  • pretrained_model_name (str ou os.PathLike, opcional) — Uma string, o id do repositório (por exemplo, CompVis/ldm-text2im-large-256) de um pipeline pré-treinado hospedado no Hub.
  • custom_pipeline (str, opcional) — Pode ser:

    • Uma string, o id do repositório (por exemplo, CompVis/ldm-text2im-large-256) de um pipeline pré-treinado hospedado no Hub. O repositório deve conter um arquivo chamado pipeline.py que define o pipeline personalizado.

    • Uma string, o nome do arquivo de um pipeline da comunidade hospedado no GitHub sob Community. Os nomes de arquivo válidos devem corresponder ao nome do arquivo e não ao script do pipeline (clip_guided_stable_diffusion em vez de clip_guided_stable_diffusion.py). Os pipelines da comunidade são sempre carregados da branch main atual do GitHub.

    • Um caminho para um diretório (./my_pipeline_directory/) contendo um pipeline personalizado. O diretório deve conter um arquivo chamado pipeline.py que define o pipeline personalizado.

    > 🧪 Este é um recurso experimental e pode mudar no futuro.

    Para mais informações sobre como carregar e criar pipelines personalizados, consulte Como contribuir com um pipeline da comunidade.

  • 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) — Indica 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 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 de bearer HTTP 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.
  • custom_revision (str, opcional, padrão "main") — A versão específica do modelo a ser usada. Pode ser um nome de branch, um nome de tag ou um id de commit, semelhante a revision ao carregar um pipeline personalizado do Hub. Pode ser uma versão do 🤗 Diffusers ao carregar um pipeline personalizado do GitHub; caso contrário, o padrão é "main" ao carregar do Hub.
  • mirror (str, opcional) — Espelho de origem para resolver problemas de acessibilidade se você estiver baixando um modelo na China. Não garantimos a atualidade ou a segurança da origem, e você deve consultar o site do espelho para obter mais informações.
  • variant (str, opcional) — Carrega os pesos de um nome de arquivo de variante especificado, como "fp16" ou "ema".
  • use_safetensors (bool, opcional, padrão None) — Se definido como None, os pesos em 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 em safetensors. Se definido como False, os pesos em safetensors não são carregados.
  • use_onnx (bool, opcional, padrão False) — Se definido como True, os pesos ONNX sempre serão baixados, se presentes. Se definido como False, os pesos ONNX nunca serão baixados. Por padrão, use_onnx assume o valor do atributo de classe _is_onnx, que é False para pipelines não-ONNX e True para pipelines ONNX. Os pesos ONNX incluem tanto arquivos que terminam em .onnx quanto .pb.
  • trust_remote_code (bool, opcional, padrão False) — Se permite ou não pipelines e componentes personalizados definidos no Hub em seus próprios arquivos. Essa opção deve ser definida como True apenas para repositórios nos quais você confia e cujo código você leu, pois ela executará o código presente no Hub na sua máquina local.
  • use_flashpack (bool, opcional, padrão False) — Se definido como True, os pesos do FlashPack sempre serão baixados, caso estejam presentes. Se definido como False, os pesos do FlashPack nunca serão baixados.

Retorna

os.PathLike

Um caminho para o pipeline baixado.

Baixe e faça o cache de um pipeline de difusão do PyTorch a partir de pesos de pipeline pré-treinados.

> Para usar modelos privados ou com acesso restrito, faça login com `hf > auth login

enable_attention_slicing

< >

( slice_size: str | int = 'auto' )

Parâmetros

  • slice_size (str ou int, opcional, padrão "auto") — Quando "auto", divide a entrada dos cabeçalhos de atenção ao meio, de modo que a atenção será calculada em duas etapas. Se "max", a quantidade máxima de memória será economizada executando apenas uma fatia por vez. Se um número for fornecido, usa tantas fatias quanto attention_head_dim // slice_size. Nesse caso, attention_head_dim deve ser um múltiplo de slice_size.

Ativa o cálculo de atenção fatiado. Quando esta opção está ativada, o módulo de atenção divide o tensor de entrada em fatias para calcular a atenção em várias etapas. Para mais de uma cabeça de atenção, o cálculo é realizado sequencialmente em cada cabeça. Isso é útil para economizar memória em troca de uma pequena diminuição na velocidade.

> ⚠️ Não ative o fatiamento de atenção se você já estiver usando scaled_dot_product_attention (SDPA) do PyTorch > 2.0 ou xFormers. Esses cálculos de atenção já são muito eficientes em termos de memória, então você não precisa ativar > essa função. Se você ativar o fatiamento de atenção com SDPA ou xFormers, isso pode levar a desempenhos significativamente mais lentos!

Exemplos:

>>> import torch
>>> from diffusers import StableDiffusionPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained(
...     "stable-diffusion-v1-5/stable-diffusion-v1-5",
...     dtype=torch.float16,
...     use_safetensors=True,
... )

>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> pipe.enable_attention_slicing()
>>> image = pipe(prompt).images[0]

enable_group_offload

< >

( onload_device: deviceoffload_device: device = torch.device()offload_type: str = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage = Falseoffload_to_disk_path: str | None = Noneexclude_modules: str | list[str] | None = None )

Parâmetros

  • onload_device (torch.device) — O dispositivo para o qual o grupo de módulos é carregado.
  • offload_device (torch.device, padrão torch.device("cpu")) — O dispositivo para o qual o grupo de módulos é descarregado. Isso deve ser tipicamente a CPU. O padrão é a CPU.
  • offload_type (str ou GroupOffloadingType, padrão “block_level”) — O tipo de offloading a ser aplicado. Pode ser “block_level” ou “leaf_level”. O padrão é “block_level”.
  • offload_to_disk_path (str, opcional, padrão None) — O caminho do diretório para onde os parâmetros serão descarregados. Definir esta opção pode ser útil em ambientes com RAM limitada, onde se deseja um equilíbrio razoável entre velocidade e memória.
  • num_blocks_per_group (int, opcional) — O número de blocos por grupo ao usar offload_type=“block_level”. Isso é obrigatório ao usar offload_type=“block_level”.
  • non_blocking (bool, padrão False) — Se True, o offloading e o onloading são realizados com transferência de dados não bloqueante.
  • use_stream (bool, padrão False) — Se True, o offloading e o onloading são feitos de forma assíncrona usando um stream CUDA. Isso pode ser útil para sobrepor o cálculo e a transferência de dados.
  • record_stream (bool, padrão False) — Quando habilitado com use_stream, marca o tensor atual como tendo sido usado por este stream. É mais rápido, à custa de um uso ligeiramente maior de memória. Consulte os documentos oficiais do PyTorch para mais detalhes.
  • low_cpu_mem_usage (bool, padrão False) — Se True, o uso de memória da CPU é minimizado ao fixar os tensors em tempo de execução, em vez de fixá-los previamente. Esta opção só é relevante ao usar offloading de CPU em streaming (ou seja, use_stream=True). Isso pode ser útil quando a memória da CPU é um gargalo, mas pode anular os benefícios do uso de streams.
  • exclude_modules (Union[str, List[str]], padrão None) — Lista de módulos a serem excluídos do offloading.

Aplica o group offloading às camadas internas de um torch.nn.Module. Para entender o que é o group offloading e onde ele é vantajoso, precisamos primeiro fornecer algum contexto sobre como funcionam os outros métodos de offloading suportados.

Normalmente, o offloading é feito em dois níveis:

  • Nível de módulo: No Diffusers, isso pode ser habilitado usando o método ModelMixin::enable_model_cpu_offload(). Ele funciona transferindo cada componente de um pipeline para a CPU para armazenamento e carregando-o no dispositivo de acelerador quando necessário para o cálculo. Este método é mais eficiente em termos de memória do que manter todos os componentes no acelerador, mas os requisitos de memória ainda são bastante altos. Para que este método funcione, é necessário ter memória equivalente ao tamanho do modelo no dtype de tempo de execução + ao tamanho dos maiores tensores de ativação intermediários para poder completar a passagem para frente.
  • Nível de folha: No Diffusers, isso pode ser ativado usando o método ModelMixin::enable_sequential_cpu_offload(). Ele funciona transferindo os parâmetros de nível de folha mais baixos do grafo de computação para a CPU para armazenamento e carregando apenas as folhas no dispositivo de acelerador para a computação. Isso usa a menor quantidade de memória do acelerador, mas pode ser mais lento devido ao número excessivo de sincronizações de dispositivo.

O offloading por grupos é um meio-termo entre os dois métodos. Ele funciona transferindo grupos de camadas internas (seja torch.nn.ModuleList ou torch.nn.Sequential). Este método usa menos memória que o offloading em nível de módulo. Ele também é mais rápido que o offloading em nível de folha/sequencial, pois o número de sincronizações de dispositivo é reduzido.

Outro recurso suportado (para dispositivos CUDA com suporte a streams de transferência de dados assíncrona) é a capacidade de sobrepor a transferência de dados e o cálculo para reduzir o tempo de execução total em comparação com o offloading sequencial. Isso é habilitado usando prefetching de camadas com streams, ou seja, a camada que será executada a seguir começa a onloading para o dispositivo de acelerador enquanto a camada atual está sendo executada - isso aumenta ligeiramente os requisitos de memória. Observe que esta implementação também suporta offloading em nível de folha, mas pode ser muito mais rápida ao usar streams.

Exemplo:

>>> from diffusers import DiffusionPipeline
>>> import torch

>>> pipe = DiffusionPipeline.from_pretrained("Qwen/Qwen-Image", dtype=torch.bfloat16)

>>> pipe.enable_group_offload(
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="leaf_level",
...     use_stream=True,
... )
>>> image = pipe("a beautiful sunset").images[0]

enable_model_cpu_offload

< >

( gpu_id: int | None = Nonedevice: typing.Union[torch.device, str] = None )

Parâmetros

  • gpu_id (int, opcional) — O ID do acelerador que deve ser usado na inferência. Se não for especificado, o valor padrão será 0.
  • device (torch.Device ou str, opcional, padrão None) — O tipo de dispositivo PyTorch do acelerador que será usado na inferência. Se não for especificado, ele detectará automaticamente o acelerador disponível e o usará.

Desloca todos os modelos para a CPU usando accelerate, reduzindo o uso de memória com baixo impacto no desempenho. Em comparação com enable_sequential_cpu_offload, este método move um modelo inteiro de cada vez para o acelerador quando seu método forward é chamado, e o modelo permanece no acelerador até que o próximo modelo seja executado. As economias de memória são menores do que com enable_sequential_cpu_offload, mas o desempenho é muito melhor devido à execução iterativa do unet.

enable_sequential_cpu_offload

< >

( gpu_id: int | None = Nonedevice: typing.Union[torch.device, str] = None )

Parâmetros

  • gpu_id (int, opcional) — O ID do acelerador que deve ser usado na inferência. Se não for especificado, o valor padrão será 0.
  • device (torch.Device ou str, opcional, padrão None) — O tipo de dispositivo PyTorch do acelerador que será usado na inferência. Se não for especificado, ele detectará automaticamente o acelerador disponível e o usará.

Desloca todos os modelos para a CPU usando 🤗 Accelerate, reduzindo significativamente o uso de memória. Quando chamado, os state dicts de todos os componentes torch.nn.Module (exceto aqueles em self._exclude_from_cpu_offload) são salvos na CPU e, em seguida, movidos para torch.device('meta') e carregados no acelerador apenas quando o método forward do submódulo específico é chamado. O offloading ocorre com base em submódulos. As economias de memória são maiores do que com enable_model_cpu_offload, mas o desempenho é menor.

enable_xformers_memory_efficient_attention

< >

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

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 estiver ativada, 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 memória eficiente de atenção e a atenção fatiada estão ambas habilitadas, a memória eficiente de atenção tem > precedência.

Exemplos:

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

>>> pipe = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1", dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> pipe.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)
>>> # Workaround for not accepting attention shape using VAE for Flash Attention
>>> pipe.vae.enable_xformers_memory_efficient_attention(attention_op=None)

from_pipe

< >

( pipeline**kwargs ) → DiffusionPipeline

Parâmetros

  • pipeline (DiffusionPipeline) — O pipeline a partir do qual criar um novo pipeline.

Retorna

DiffusionPipeline

Um novo pipeline com os mesmos pesos e configurações que pipeline.

Cria um novo pipeline a partir de um pipeline dado. Este método é útil para criar um novo pipeline a partir dos componentes existentes do pipeline sem alocar memória adicional.

Exemplos:

>>> from diffusers import StableDiffusionPipeline, StableDiffusionSAGPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> new_pipe = StableDiffusionSAGPipeline.from_pipe(pipe)

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLike**kwargs )

Parâmetros

  • pretrained_model_name_or_path (str ou os.PathLike, opcional) — Pode ser:
    • Uma string, o repo id (por exemplo, CompVis/ldm-text2im-large-256) de um pipeline pré-treinado hospedado no Hub.
    • Um caminho para um diretório (por exemplo, ./my_pipeline_directory/) contendo pesos de pipeline salvos usando save_pretrained().
  • dtype (torch.dtype ou dict[str, Union[str, torch.dtype]], opcional) — Substitui o torch.dtype padrão e carrega o modelo com outro dtype. Para carregar submodelos com diferentes dtypes, passe um dict (por exemplo, {'transformer': torch.bfloat16, 'vae': torch.float16}). Defina o dtype padrão para componentes não especificados com default (por exemplo, {'transformer': torch.bfloat16, 'default': torch.float16}). Se um componente não for especificado e nenhum padrão for definido, torch.float32 será usado.
  • custom_pipeline (str, opcional) —

    > 🧪 Este é um recurso experimental e pode mudar no futuro.

    Pode ser:

    • Uma string, o repo id (por exemplo hf-internal-testing/diffusers-dummy-pipeline) de um pipeline personalizado hospedado no Hub. O repositório deve conter um arquivo chamado pipeline.py que define o pipeline personalizado.
    • Uma string, o nome do arquivo de um pipeline da comunidade hospedado no GitHub sob Community. Os nomes de arquivo válidos devem corresponder ao nome do arquivo e não ao script do pipeline (clip_guided_stable_diffusion em vez de clip_guided_stable_diffusion.py). Os pipelines da comunidade são sempre carregados da branch main atual do GitHub.
    • Um caminho para um diretório (./my_pipeline_directory/) contendo um pipeline personalizado. O diretório deve conter um arquivo chamado pipeline.py que define o pipeline personalizado.

    Para mais informações sobre como carregar e criar pipelines personalizados, consulte Carregamento e Adição de Pipelines Personalizados

  • 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.
  • cache_dir (Union[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.
  • 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) — Indica 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 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 de bearer HTTP 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.
  • custom_revision (str, opcional) — A versão específica do modelo a ser usada. Pode ser um nome de branch, um nome de tag ou um id de commit, semelhante a revision ao carregar um pipeline personalizado do Hub. O padrão é a versão estável mais recente do 🤗 Diffusers.
  • mirror (str, opcional) — Espelho de origem para resolver problemas de acessibilidade se você estiver baixando um modelo na China. Não garantimos a atualidade ou a segurança da origem, e você deve consultar o site do espelho para obter mais informações.
  • device_map (str, opcional) — Estratégia que determina como os diferentes componentes de um pipeline devem ser alocados nos dispositivos disponíveis. Atualmente, apenas o device_map “balanced” é suportado. Consulte este para saber mais.
  • max_memory (Dict, opcional) — Um dicionário com o identificador do 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 da 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 de 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.
  • use_safetensors (bool, opcional, padrão None) — Se definido como None, os pesos em 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 em safetensors. Se definido como False, os pesos em safetensors não são carregados.
  • use_onnx (bool, opcional, padrão None) — Se definido como True, os pesos ONNX sempre serão baixados, se presentes. Se definido como False, os pesos ONNX nunca serão baixados. Por padrão, use_onnx assume o valor do atributo de classe _is_onnx, que é False para pipelines não-ONNX e True para pipelines ONNX. Os pesos ONNX incluem tanto arquivos que terminam em .onnx quanto .pb.
  • kwargs (dicionário restante de argumentos de palavra-chave, opcional) — Pode ser usado para sobrescrever variáveis de carregamento e salvamento (os componentes do pipeline da classe de pipeline específica). Os componentes sobrescritos são passados diretamente para o método __init__ dos pipelines. Veja o exemplo abaixo para mais informações.
  • variant (str, opcional) — Carrega os pesos de um nome de arquivo de variante especificado, como "fp16" ou "ema".
  • 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 aleatórias (seek) do mmap.

Instanciar um pipeline de difusão do PyTorch a partir de pesos de pipeline pré-treinados.

O pipeline é definido no modo de avaliação (model.eval()) por padrão.

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.

> Para usar modelos privados ou com acesso restrito, faça login com hf > auth login.

Exemplos:

>>> from diffusers import DiffusionPipeline

>>> # Download pipeline from huggingface.co and cache.
>>> pipeline = DiffusionPipeline.from_pretrained("CompVis/ldm-text2im-large-256")

>>> # Download pipeline that requires an authorization token
>>> # For more information on access tokens, please refer to this section
>>> # of the documentation](https://huggingface.co/docs/hub/security-tokens)
>>> pipeline = DiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")

>>> # Use a different scheduler
>>> from diffusers import LMSDiscreteScheduler

>>> scheduler = LMSDiscreteScheduler.from_config(pipeline.scheduler.config)
>>> pipeline.scheduler = scheduler

talvez_liberar_ganchos_do_modelo

< >

( )

Método que executa o seguinte:

  • Desloca todos os componentes.
  • Remove todos os hooks do modelo que foram adicionados ao usar enable_model_cpu_offload e, em seguida, os aplica novamente. Caso o modelo não tenha sido offloaded, esta função é um no-op.
  • Redefine os hooks com estado dos componentes de denoiser do diffusers, caso tenham sido adicionados com register_hook().

Certifique-se de adicionar esta função ao final da função __call__ do seu pipeline para que ela funcione corretamente ao aplicar enable_model_cpu_offload.

numpy_to_pil

< >

( images )

Converte uma imagem NumPy ou um lote de imagens em uma imagem PIL.

remove_all_hooks

< >

( )

Remove todos os hooks que foram adicionados ao usar enable_sequential_cpu_offload ou enable_model_cpu_offload.

reset_device_map

< >

( )

Redefine os mapas de dispositivos (se houver) para None.

save_pretrained

< >

( save_directory: str | os.PathLikesafe_serialization: bool = Truevariant: str | None = Nonemax_shard_size: int | str | None = Nonepush_to_hub: bool = Falseuse_flashpack: bool = False**kwargs )

Parâmetros

  • save_directory (str ou os.PathLike) — Diretório para salvar um pipeline. Será criado se não existir.
  • 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 None) — O tamanho máximo de um checkpoint antes de ser dividido em shards. Os shards do checkpoint terão, então, cada um um tamanho inferior a esse valor. Se expresso como string, deve ser composto por dígitos seguidos de uma unidade (como "5GB"). Se expresso como 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 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 hub de modelos do Hugging Face 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().

Salva todas as variáveis salveis do pipeline em um diretório. Uma variável do pipeline pode ser salva e carregada se sua classe implementar tanto um método de salvamento quanto um método de carregamento. O pipeline é facilmente recarregado usando o método de classe from_pretrained().

diffusers.StableDiffusionMixin.enable_freeu

< >

( s1: floats2: floatb1: floatb2: float )

Parâmetros

  • s1 (float) — Fator de escala para a etapa 1 para atenuar as contribuições dos recursos de skip. Isso é feito para mitigar o “efeito de suavização excessiva” no processo aprimorado de remoção de ruído.
  • s2 (float) — Fator de escala para o estágio 2 para atenuar as contribuições dos recursos de skip. Isso é feito para mitigar o “efeito de suavização excessiva” no processo aprimorado de remoção de ruído.
  • b1 (float) — Fator de escala para o estágio 1 para amplificar as contribuições dos recursos do backbone.
  • b2 (float) — Fator de escala para o estágio 2 para amplificar as contribuições dos recursos do backbone.

Ativa o mecanismo FreeU, conforme descrito em https://huggingface.co/papers/2309.11497.

Os sufixos após os fatores de escala representam as etapas em que eles estão sendo aplicados.

Consulte o repositório oficial para as combinações de valores que são conhecidas por funcionar bem em diferentes pipelines, como Stable Diffusion v1, v2 e Stable Diffusion XL.

diffusers.StableDiffusionMixin.disable_freeu

< >

( )

Desativa o mecanismo FreeU, se estiver ativado.

PushToHubMixin

classe diffusers.utils.PushToHubMixin

< >

( )

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

push_to_hub

< >

( repo_id: strcommit_message: str | None = Noneprivate: bool | None = Nonetoken: str | None = Nonecreate_pr: bool = Falsesafe_serialization: bool = Truevariant: str | None = Nonesubfolder: str | None = None )

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 a ser commitada durante o 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 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")

Callbacks

classe diffusers.callbacks.PipelineCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Classe base para todos os callbacks oficiais usados em um pipeline. Esta classe fornece uma estrutura para implementar callbacks personalizados e garante que todos os callbacks tenham uma interface consistente.

Implemente o seguinte: tensor_inputs: isso deve retornar uma lista de entradas de tensor específicas para o seu callback. Você só poderá incluir variáveis listadas no atributo ._callback_tensor_inputs da sua classe de pipeline. callback_fn: este método define a funcionalidade central do seu callback.

classe diffusers.callbacks.SDCFGCutoffCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Função de callback para Pipelines de Stable Diffusion. Após um determinado número de etapas (definido por cutoff_step_ratio ou cutoff_step_index), este callback desativará o CFG.

Nota: Este callback altera o pipeline, mudando o atributo _guidance_scale para 0.0 após o passo de corte.

classe diffusers.callbacks.SDXLCFGCutoffCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Função de callback para os Pipelines base do Stable Diffusion XL. Após um determinado número de etapas (definido por cutoff_step_ratio ou cutoff_step_index), este callback desativará o CFG.

Nota: Este callback altera o pipeline, mudando o atributo _guidance_scale para 0.0 após o passo de corte.

classe diffusers.callbacks.SDXLControlnetCFGCutoffCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Função de callback para os Pipelines do Controlnet Stable Diffusion XL. Após um determinado número de etapas (definido por cutoff_step_ratio ou cutoff_step_index), este callback desativará o CFG.

Nota: Este callback altera o pipeline, mudando o atributo _guidance_scale para 0.0 após o passo de corte.

classe diffusers.callbacks.IPAdapterScaleCutoffCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Função de callback para qualquer pipeline que herda de IPAdapterMixin. Após um determinado número de etapas (definido por cutoff_step_ratio ou cutoff_step_index), este callback definirá a escala do IP Adapter como 0.0.

Nota: Este callback altera os processadores de atenção do IP Adapter definindo a escala como 0.0 após o passo de corte.

classe diffusers.callbacks.SD3CFGCutoffCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Função de callback para os pipelines do Stable Diffusion 3. Após um determinado número de etapas (definido por cutoff_step_ratio ou cutoff_step_index), este callback desativará o CFG.

Nota: Este callback altera o pipeline, mudando o atributo _guidance_scale para 0.0 após o passo de corte.

Update on GitHub

←VQModel AutoPipeline→