# Utilitários

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

## numpy_to_pil[[diffusers.utils.numpy_to_pil]]

#### diffusers.utils.numpy_to_pil[[diffusers.utils.numpy_to_pil]]

```python
diffusers.utils.numpy_to_pil(images)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L35)

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

## pt_to_pil[[diffusers.utils.pt_to_pil]]

#### diffusers.utils.pt_to_pil[[diffusers.utils.pt_to_pil]]

```python
diffusers.utils.pt_to_pil(images)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L25)

Converte uma imagem do torch para uma imagem do PIL.

## load_image[[diffusers.utils.load_image]]

#### diffusers.utils.load_image[[diffusers.utils.load_image]]

```python
diffusers.utils.load_image(image: str | PIL.Image.Image, convert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/loading_utils.py#L14)

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

#### diffusers.utils.load_video[[diffusers.utils.load_video]]

```python
diffusers.utils.load_video(video: str, convert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = None, return_fps: bool = False)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/loading_utils.py#L57)

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

#### diffusers.utils.export_to_gif[[diffusers.utils.export_to_gif]]

```python
diffusers.utils.export_to_gif(image: list[PIL.Image.Image], output_gif_path: str = None, fps: int = 10)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L37)

## export_to_video[[diffusers.utils.export_to_video]]

#### diffusers.utils.export_to_video[[diffusers.utils.export_to_video]]

```python
diffusers.utils.export_to_video(video_frames: list[np.ndarray] | list[PIL.Image.Image], output_video_path: str = None, fps: int = 10, quality: float = 5.0, bitrate: int | None = None, macro_block_size: int | None = 16)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L150)

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 de melhor qualidade com 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]]

#### diffusers.utils.encode_video[[diffusers.utils.encode_video]]

```python
diffusers.utils.encode_video(video: list[PIL.Image.Image] | np.ndarray | 'torch.Tensor' | Iterator['torch.Tensor'], fps: int, output_path: str, audio: 'torch.Tensor' | None = None, audio_sample_rate: int | None = None, video_chunks_number: int = 1)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/export_utils.py#L304)

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

#### diffusers.utils.make_image_grid[[diffusers.utils.make_image_grid]]

```python
diffusers.utils.make_image_grid(images: list[PIL.Image.Image], rows: int, cols: int, resize: int = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/pil_utils.py#L51)

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

## randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]

#### diffusers.utils.torch_utils.randn_tensor[[diffusers.utils.torch_utils.randn_tensor]]

```python
diffusers.utils.torch_utils.randn_tensor(shape: tuple | list, generator: list['torch.Generator'] | 'torch.Generator' | None = None, device: str | 'torch.device' | None = None, dtype: 'torch.dtype' | None = None, layout: 'torch.layout' | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L61)

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[[diffusers.utils.torch_utils.TorchDeviceBackend]]

#### diffusers.utils.torch_utils.TorchDeviceBackend[[diffusers.utils.torch_utils.TorchDeviceBackend]]

```python
diffusers.utils.torch_utils.TorchDeviceBackend(device: str | torch.device | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L228)

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`. Lança 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[[diffusers.utils.torch_utils.TorchDeviceBackend.max_memory_allocated]]

```python
max_memory_allocated()
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L291)

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[[diffusers.utils.torch_utils.TorchDeviceBackend.mem_get_info]]

```python
mem_get_info()
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/torch_utils.py#L279)

Memória livre e total do dispositivo em bytes.

## apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

#### diffusers.hooks.apply_layerwise_casting[[diffusers.hooks.apply_layerwise_casting]]

```python
diffusers.hooks.apply_layerwise_casting(module: Module, storage_dtype: dtype, compute_dtype: dtype, skip_modules_pattern: str | tuple[str, ...] = 'auto', skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = None, non_blocking: bool = False)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/layerwise_casting.py#L101)

**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` junto 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 para ignorar 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:

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

#### diffusers.hooks.apply_group_offloading[[diffusers.hooks.apply_group_offloading]]

```python
diffusers.hooks.apply_group_offloading(module: Module, onload_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 = None, non_blocking: bool = False, use_stream: bool = False, record_stream: bool = False, low_cpu_mem_usage: bool = False, offload_to_disk_path: str | None = None, block_modules: list[str] | None = None, exclude_kwargs: list[str] | None = None)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/hooks/group_offloading.py#L567)

**Parâmetros:**

module (`torch.nn.Module`) : O módulo ao qual o group offloading é 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. Isso deve ser tipicamente a CPU. O padrão é 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 para o diretório 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](https://pytorch.org/docs/stable/generated/torch.Tensor.record_stream.html) para mais detalhes.

low_cpu_mem_usage (`bool`, padrão `False`) : Se True, o uso de memória da CPU é minimizado ao fixar os tensores 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 contrariar 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 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 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 geral 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:
```python
>>> 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,
... )
```