Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /pt /api /utilities.md

mishig

3 days ago

preview code

download

raw

18.5 kB

# 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,
... )
```

Xet Storage Details

Size:: 18.5 kB
Xet hash:: 375cfb3148440b46b13f5e3350ca24cbf493bc036ea4745946da33ea0e65320e

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# 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,
	... )
	```