Utilidades

Funciones de utilidad y auxiliares para trabajar con 🤗 Diffusers.

numpy_to_pil

diffusers.utils.numpy_to_pil

< source >

( images )

Convierte una imagen de numpy o un lote de imágenes en una imagen de PIL.

pt_to_pil

diffusers.utils.pt_to_pil

< source >

( images )

Convierte una imagen de torch en una imagen de 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 o PIL.Image.Image) — La imagen que se convertirá al formato PIL Image.
convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], opcional) — Un método de conversión para aplicar a la imagen después de cargarla. Cuando se establece en None, la imagen se convertirá a “RGB”.

Devuelve

PIL.Image.Image

Una imagen PIL.

Loads image to a PIL Image.

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) — Una URL o Path a un video para convertirlo en una lista de imágenes en formato PIL Image.
convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], opcional) — Un método de conversión para aplicar al video después de cargarlo. Cuando se establece en None, las imágenes se convertirán a “RGB”.
return_fps (bool, opcional, valor predeterminado False) — Indica si se debe devolver también la tasa de fotogramas a la que se codificó el vídeo. Es necesario para los pipelines que re-muestrean la entrada a la tasa de fotogramas en la que funciona su modelo, ya que una lista de fotogramas no contiene esa información.

Devuelve

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

El video como una lista de imágenes PIL y su tasa de fotogramas si return_fps está establecido.

Carga video en una lista de imágenes 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: Calidad de la salida de video. El valor predeterminado es 5. Utiliza una tasa de bits variable. La calidad más alta es 10 y la más baja es 0. Establezca None para evitar las banderas de tasa de bits variable en FFMPEG, de modo que pueda especificarlas manualmente usando output_params en su lugar. Especificar una tasa de bits fija usando bitrate deshabilita este parámetro.

bitrate: Establece una tasa de bits constante para la codificación del vídeo. El valor predeterminado es None, lo que provoca que se utilice el parámetro quality en su lugar. Se obtendrán vídeos de mejor calidad con tamaños de archivo más pequeños al utilizar el parámetro de tasa de bits variable quality en lugar de especificar una tasa de bits fija con este parámetro.

macro_block_size: Restricción de tamaño para el vídeo. El ancho y la altura deben ser divisibles por este número. Si no son divisibles por este número, imageio indicará a ffmpeg que escale la imagen al tamaño más cercano divisible por este número. La mayoría de los códecs son compatibles con un tamaño de macrobloque de 16 (predeterminado), algunos pueden ser más pequeños (4, 8). Para deshabilitar esta función automática, establézcalo en None o 1; sin embargo, tenga en cuenta que muchos reproductores no pueden decodificar vídeos de tamaño impar y algunos códecs producirán resultados deficientes o fallarán. Consulte https://en.wikipedia.org/wiki/Macroblock.

encode_video

diffusers.utils.encode_video

< source >

Parámetros

video (List[PIL.Image.Image] o np.ndarray o torch.Tensor) — Un tensor de video de forma [frames, height, width, channels] con valores de píxeles enteros en [0, 255]. Si la entrada es un np.ndarray, se espera que sea un array de flotantes con valores en [0, 1] (lo que los pipelines suelen devolver con output_type="np").
fps (int) — Los fotogramas por segundo (FPS) del video codificado.
output_path (str) — La ruta donde se guardará el video codificado.
audio (torch.Tensor, opcional) — Una forma de onda de audio de forma [audio_channels, samples].
audio_sample_rate — (int, opcional): La tasa de muestreo de la forma de onda de audio.
video_chunks_number (int, opcional, valor predeterminado 1) — El número de fragmentos en los que dividir el video para la codificación. Cada fragmento se codificará por separado. El número de fragmentos a utilizar suele depender de la configuración de mosaico para el VAE de video.

Codifica un video con audio opcional usando la biblioteca PyAV. Basado en el código del repositorio original de 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: listrows: intcols: intresize: int = None )

Prepara una cuadrícula única de imágenes. Útil con fines de visualización.

randn_tensor

diffusers.utils.torch_utils.randn_tensor

< source >

Función auxiliar para crear tensores aleatorios en el device deseado con el dtype deseado. Al pasar una lista de generadores, puede establecer la semilla de cada tamaño de lote de forma individual. Si se pasan generadores de CPU, el tensor siempre se crea en la CPU.

TorchDeviceBackend

clase diffusers.utils.torch_utils.TorchDeviceBackend

< source >

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

Un proxy para el espacio de nombres torch.<backend> (torch.cuda, torch.xpu, torch.mps, …) de un dispositivo. Los atributos que la clase no define son los propios del módulo (synchronize, device_count, Stream, current_stream, …); los métodos definidos aquí reemplazan las operaciones cuya disponibilidad varía entre backends y requieren una alternativa: limpieza de caché, inicialización de la semilla y consultas de memoria. Sin device, detecta el acelerador del host a través de torch.accelerator. Lanza una excepción si torch no tiene un módulo para el backend, en lugar de recurrir silenciosamente a torch.cuda.

max_memory_allocated

< source >

( )

Memoria máxima asignada en el dispositivo en bytes desde el último reinicio; 0 donde el backend no mantiene estadísticas.

mem_get_info

< source >

( )

Memoria libre y total del dispositivo en 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) — El módulo cuyos módulos hoja se convertirán a un dtype de alta precisión para el cálculo y a un dtype de baja precisión para el almacenamiento.
storage_dtype (torch.dtype) — El dtype al que se debe convertir el módulo antes/después de la pasada hacia adelante para el almacenamiento.
compute_dtype (torch.dtype) — El dtype al que se debe convertir el módulo durante la pasada hacia adelante para el cálculo.
skip_modules_pattern (tuple[str, ...], por defecto "auto") — Una lista de patrones para coincidir con los nombres de los módulos que se deben omitir durante el proceso de conversión por capas. Si se establece en "auto", se utilizan los patrones predeterminados. Si se establece en None, no se omiten módulos. Si se establece en None junto con skip_modules_classes siendo None, la conversión por capas se aplica directamente al módulo en lugar de a sus submódulos internos.
skip_modules_classes (tuple[Type[torch.nn.Module], ...], por defecto None) — Una lista de clases de módulos que se deben omitir durante el proceso de conversión por capas.
non_blocking (bool, por defecto False) — Si es True, las operaciones de conversión de pesos son no bloqueantes.

Aplica el casteo por capa a un módulo dado. El módulo esperado aquí es un ModelMixin de Diffusers, pero puede ser cualquier nn.Module que utilice capas de diffusers o primitivas de pytorch.

Ejemplo:

>>> 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) — El módulo al que se aplica el descargado de grupos.
onload_device (torch.device) — El dispositivo al que se cargan los módulos del grupo.
offload_device (torch.device, por defecto torch.device("cpu")) — El dispositivo al que se descargan los módulos del grupo. Normalmente, debe ser la CPU. El valor predeterminado es la CPU.
offload_type (str o GroupOffloadingType, por defecto “block_level”) — El tipo de offloading que se aplicará. Puede ser “block_level” o “leaf_level”. El valor por defecto es “block_level”.
offload_to_disk_path (str, opcional, valor predeterminado None) — La ruta al directorio donde se descargarán los parámetros. Establecer esta opción puede ser útil en entornos con RAM limitada donde se desea un equilibrio razonable entre velocidad y memoria.
num_blocks_per_group (int, opcional) — El número de bloques por grupo al usar offload_type=“block_level”. Es obligatorio al usar offload_type=“block_level”.
non_blocking (bool, por defecto False) — Si es True, la descarga y carga de datos se realiza con transferencia de datos no bloqueante.
use_stream (bool, por defecto False) — Si es True, el offloading y el onloading se realizan de forma asíncrona mediante un stream de CUDA. Esto puede ser útil para superponer el cálculo y la transferencia de datos.
record_stream (bool, por defecto False) — Cuando se habilita junto con use_stream, marca el tensor actual como utilizado por este stream. Es más rápido a costa de un uso ligeramente mayor de memoria. Consulte la documentación oficial de PyTorch para más detalles.
low_cpu_mem_usage (bool, por defecto False) — Si es True, se minimiza el uso de memoria de CPU fijando los tensores sobre la marcha en lugar de fijarlos previamente. Esta opción solo es relevante al usar el descargado de CPU por streaming (es decir, use_stream=True). Puede ser útil cuando la memoria de CPU es un cuello de botella, pero puede contrarrestar los beneficios de usar streams.
block_modules (list[str], opcional) — Lista de nombres de módulos que deben tratarse como bloques para el offloading. Si se proporciona, solo estos módulos se considerarán para el offloading a nivel de bloque. Si no se proporciona, se utilizará la lógica de detección de bloques predeterminada.
exclude_kwargs (list[str], opcional) — Lista de claves de kwarg que no deben ser procesadas por send_to_device. Esto es útil para estados mutables como listas de caché que necesitan mantener su identidad de objeto entre pases de forward. Si no se proporciona, se inferirá del atributo _skip_keys del módulo si este existe.

Aplica el descargado por grupos a las capas internas de un torch.nn.Module. Para entender qué es el descargado por grupos y en qué casos resulta beneficioso, primero debemos proporcionar algo de contexto sobre cómo funcionan otros métodos de descargado admitidos.

Por lo general, el offloading se realiza en dos niveles:

A nivel de módulo: en Diffusers, esto se puede habilitar usando el método ModelMixin::enable_model_cpu_offload(). Funciona descargando cada componente de un pipeline a la CPU para su almacenamiento y cargándolo en el dispositivo de aceleración cuando se necesita para el cálculo. Este método es más eficiente en memoria que mantener todos los componentes en el acelerador, pero los requisitos de memoria siguen siendo bastante altos. Para que este método funcione, se necesita una memoria equivalente al tamaño del modelo en el tipo de datos de tiempo de ejecución + el tamaño de los tensores de activación intermedia más grandes para poder completar la pasada hacia adelante.
Nivel de hoja: En Diffusers, esto se puede habilitar usando el método ModelMixin::enable_sequential_cpu_offload(). Funciona descargando los parámetros de nivel de hoja más bajos del grafo de cómputo a la CPU para su almacenamiento, y cargando solo las hojas al dispositivo de aceleración para el cómputo. Esto utiliza la menor cantidad de memoria de acelerador, pero puede ser más lento debido al exceso de sincronizaciones de dispositivos.

El offloading por grupos es un punto intermedio entre los dos métodos. Funciona descargando grupos de capas internas (ya sea torch.nn.ModuleList o torch.nn.Sequential). Este método utiliza menos memoria que el offloading a nivel de módulo. También es más rápido que el offloading a nivel de hoja/secuencial, ya que se reduce el número de sincronizaciones de dispositivos.

Otra característica admitida (para dispositivos CUDA con soporte para flujos de transferencia de datos asíncronos) es la capacidad de superponer la transferencia de datos y el cálculo para reducir el tiempo de ejecución total en comparación con el offloading secuencial. Esto se habilita mediante la preobtención de capas con flujos, es decir, la capa que se ejecutará a continuación comienza a cargarse en el dispositivo de acelerador mientras se está ejecutando la capa actual; esto aumenta ligeramente los requisitos de memoria. Tenga en cuenta que esta implementación también admite el offloading a nivel de hoja, pero puede hacerse mucho más rápido al utilizar flujos.

Ejemplo:

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