Hugging Face's logo

Diffusers documentation

Utilitários

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

Utilitários

Funções utilitárias e auxiliares para trabalhar com o 🤗 Diffusers.

numpy_to_pil

diffusers.utils.numpy_to_pil

< >

( images )

Converte uma imagem numpy ou um lote de imagens para uma imagem PIL.

pt_to_pil

diffusers.utils.pt_to_pil

< >

( images )

Converte uma imagem do torch para uma imagem do PIL.

load_image

diffusers.utils.load_image

< >

( image: str | PIL.Image.Imageconvert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None ) → PIL.Image.Image

Parâmetros

  • image (str ou PIL.Image.Image) — A imagem a ser convertida para o formato PIL Image.
  • convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], opcional) — Um método de conversão a ser aplicado à imagem após carregá-la. Quando definido como None, a imagem será convertida para “RGB”.

Retorna

PIL.Image.Image

Uma imagem PIL.

Carrega image para uma Imagem PIL.

load_video

diffusers.utils.load_video

< >

( video: strconvert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = Nonereturn_fps: bool = False ) → list[PIL.Image.Image] or tuple[list[PIL.Image.Image], float]

Parâmetros

  • video (str) — Uma URL ou Path para um vídeo a ser convertido em uma lista de imagens no formato PIL Image.
  • convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], opcional) — Um método de conversão a ser aplicado ao vídeo após carregá-lo. Quando definido como None, as imagens serão convertidas para “RGB”.
  • return_fps (bool, opcional, padrão False) — Se deve retornar também a taxa de quadros na qual o vídeo foi codificado. Necessário para pipelines que reamostram a entrada para a taxa de quadros em que seu modelo opera, pois uma lista de quadros não carrega essa informação.

Retorna

list[PIL.Image.Image] ou tuple[list[PIL.Image.Image], float]

O vídeo como uma lista de imagens PIL e sua taxa de quadros, se return_fps estiver definido.

Carrega video para uma lista de imagens PIL.

export_to_gif

diffusers.utils.export_to_gif

< >

( image: list[PIL.Image.Image]output_gif_path: str = Nonefps: int = 10 )

export_to_video

diffusers.utils.export_to_video

< >

( video_frames: list[np.ndarray] | list[PIL.Image.Image]output_video_path: str = Nonefps: int = 10quality: float = 5.0bitrate: int | None = Nonemacro_block_size: int | None = 16 )

quality: Qualidade da saída de vídeo. O padrão é 5. Usa taxa de bits variável. A qualidade mais alta é 10 e a mais baixa é 0. Defina como None para impedir que as flags de taxa de bits variável sejam enviadas ao FFMPEG, permitindo que você as especifique manualmente usando output_params. Especificar uma taxa de bits fixa usando bitrate desativa este parâmetro.

bitrate: Define uma taxa de bits constante para a codificação do vídeo. O padrão é None, fazendo com que o parâmetro quality seja usado no lugar. Vídeos com melhor qualidade e tamanhos de arquivo menores resultarão do uso do parâmetro de taxa de bits variável quality em vez de especificar uma taxa de bits fixa com este parâmetro.

macro_block_size: Restrição de tamanho para vídeo. Largura e altura, devem ser divisíveis por este número. Se não forem divisíveis por este número, o imageio instruirá o ffmpeg a redimensionar a imagem para o tamanho mais próximo divisível por este número. A maioria dos codecs é compatível com um tamanho de macroblock de 16 (padrão), alguns podem ser menores (4, 8). Para desativar este recurso automático, defina-o como None ou 1, no entanto, esteja ciente de que muitos players não conseguem decodificar vídeos com tamanho ímpar e alguns codecs produzirão resultados ruins ou falharão. Veja https://en.wikipedia.org/wiki/Macroblock.

encode_video

diffusers.utils.encode_video

< >

( video: list[PIL.Image.Image] | np.ndarray | 'torch.Tensor' | Iterator['torch.Tensor']fps: intoutput_path: straudio: 'torch.Tensor' | None = Noneaudio_sample_rate: int | None = Nonevideo_chunks_number: int = 1 )

Parâmetros

  • video (List[PIL.Image.Image] ou np.ndarray ou torch.Tensor) — Um tensor de vídeo com forma [frames, height, width, channels] e valores de pixels inteiros em [0, 255]. Se a entrada for um np.ndarray, espera-se que seja um array de float com valores em [0, 1] (o que os pipelines geralmente retornam com output_type="np").
  • fps (int) — Os quadros por segundo (FPS) do vídeo codificado.
  • output_path (str) — O caminho para salvar o vídeo codificado.
  • audio (torch.Tensor, opcional) — Uma forma de onda de áudio com a forma [audio_channels, samples].
  • audio_sample_rate — (int, opcional): A taxa de amostragem da forma de onda de áudio.
  • video_chunks_number (int, opcional, padrão 1) — O número de blocos para dividir o vídeo para codificação. Cada bloco será codificado separadamente. O número de blocos a serem usados frequentemente depende da configuração de tiling para o VAE de vídeo.

Codifica um vídeo com áudio opcional usando a biblioteca PyAV. Baseado no código do repositório original LTX-2: https://github.com/Lightricks/LTX-2/blob/4f410820b198e05074a1e92de793e3b59e9ab5a0/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py#L182

make_image_grid

diffusers.utils.make_image_grid

< >

( images: listrows: intcols: intresize: int = None )

Prepara uma única grade de imagens. Útil para fins de visualização.

randn_tensor

diffusers.utils.torch_utils.randn_tensor

< >

( shape: tuple | listgenerator: list['torch.Generator'] | 'torch.Generator' | None = Nonedevice: str | 'torch.device' | None = Nonedtype: 'torch.dtype' | None = Nonelayout: 'torch.layout' | None = None )

Uma função auxiliar para criar tensores aleatórios no device desejado com o dtype desejado. Ao passar uma lista de geradores, você pode definir a semente de cada tamanho de lote individualmente. Se geradores de CPU forem passados, o tensor é sempre criado na CPU.

TorchDeviceBackend

classe diffusers.utils.torch_utils.TorchDeviceBackend

< >

( device: str | torch.device | None = None )

Um proxy para o namespace torch.<backend> (torch.cuda, torch.xpu, torch.mps, …) de um dispositivo. Os atributos que a classe não define são os próprios do módulo (synchronize, device_count, Stream, current_stream, …); os métodos definidos aqui substituem as operações cuja disponibilidade difere entre backends e que precisam de um fallback: limpeza de cache, definição de seed e consultas de memória. Sem um device, detecta o acelerador do host por meio de torch.accelerator. Levanta uma exceção se o torch não tiver um módulo para o backend, em vez de fazer fallback silenciosamente para torch.cuda.

max_memory_allocated

< >

( )

Memória de pico alocada no dispositivo em bytes desde o último reset; 0 onde o backend não mantém estatísticas.

mem_get_info

< >

( )

Memória livre e total do dispositivo em bytes.

apply_layerwise_casting

diffusers.hooks.apply_layerwise_casting

< >

( module: Modulestorage_dtype: dtypecompute_dtype: dtypeskip_modules_pattern: str | tuple[str, ...] = 'auto'skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )

Parâmetros

  • module (torch.nn.Module) — O módulo cujos módulos folha serão convertidos para um dtype de alta precisão para computação e para um dtype de baixa precisão para armazenamento.
  • storage_dtype (torch.dtype) — O dtype para o qual o módulo deve ser convertido antes/depois da passagem de frente para armazenamento.
  • compute_dtype (torch.dtype) — O dtype para o qual o módulo deve ser convertido durante a passagem de frente para a computação.
  • skip_modules_pattern (tuple[str, ...], padrão "auto") — 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 "auto", os padrões padrão são usados. Se definido como None, nenhum módulo é ignorado. Se definido como None juntamente com skip_modules_classes sendo None, a conversão por camada é aplicada diretamente ao módulo em vez de seus submódulos internos.
  • skip_modules_classes (tuple[Type[torch.nn.Module], ...], padrão None) — Uma lista de classes de módulos a serem ignoradas durante o processo de conversão por camada.
  • non_blocking (bool, padrão False) — Se True, as operações de conversão de pesos são não bloqueantes.

Aplica o casting por camada a um módulo específico. O módulo esperado aqui é um ModelMixin do Diffusers, mas pode ser qualquer nn.Module que utilize camadas do diffusers ou primitivas do pytorch.

Exemplo:

>>> import torch
>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     model_id, subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> apply_layerwise_casting(
...     transformer,
...     storage_dtype=torch.float8_e4m3fn,
...     compute_dtype=torch.bfloat16,
...     skip_modules_pattern=["patch_embed", "norm", "proj_out"],
...     non_blocking=True,
... )

apply_group_offloading

diffusers.hooks.apply_group_offloading

< >

( module: Moduleonload_device: typing.Union[str, torch.device]offload_device: typing.Union[str, torch.device] = torch.device()offload_type: str | diffusers.hooks.group_offloading.GroupOffloadingType = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage: bool = Falseoffload_to_disk_path: str | None = Noneblock_modules: list[str] | None = Noneexclude_kwargs: list[str] | None = None )

Parâmetros

  • module (torch.nn.Module) — O módulo ao qual o offloading de grupo é aplicado.
  • 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. Normalmente, deve ser 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. Essa 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.
  • block_modules (list[str], opcional) — Lista de nomes de módulos que devem ser tratados como blocos para offloading. Se fornecida, apenas esses módulos serão considerados para offloading em nível de bloco. Se não fornecida, a lógica padrão de detecção de blocos será utilizada.
  • exclude_kwargs (list[str], opcional) — Lista de chaves de kwarg que não devem ser processadas por send_to_device. Isso é útil para estados mutáveis, como listas de cache que precisam manter sua identidade de objeto entre as passadas de forward. Se não for fornecida, será inferida do atributo _skip_keys do módulo, se ele existir.

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 ativado usando o método ModelMixin::enable_model_cpu_offload(). Ele funciona transferindo cada componente de um pipeline para a CPU para armazenamento e carregando para o 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 + 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 transferindo apenas as folhas para o 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 inicia o 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 CogVideoXTransformer3DModel
>>> from diffusers.hooks import apply_group_offloading

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

>>> apply_group_offloading(
...     transformer,
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="block_level",
...     num_blocks_per_group=2,
...     use_stream=True,
... )
Update on GitHub

←Camadas de normalização personalizadas Processador de Imagem VAE→