Utilitários

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

numpy_to_pil

diffusers.utils.numpy_to_pil

< source >

( images )

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

pt_to_pil

diffusers.utils.pt_to_pil

< source >

( images )

Converte uma imagem do torch para uma imagem do PIL.

load_image

diffusers.utils.load_image

< source >

( 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

< source >

( 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

< source >

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

export_to_video

diffusers.utils.export_to_video

< source >

( 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

< source >

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

< source >

( images: list[PIL.Image.Image]rows: intcols: intresize: int = None )

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

randn_tensor

diffusers.utils.torch_utils.randn_tensor

< source >

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

< source >

( 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

< source >

( )

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

< source >

( )

Memória livre e total do dispositivo em bytes.

apply_layerwise_casting

diffusers.hooks.apply_layerwise_casting

< source >

( 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

< source >

( 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