Hugging Face's logo

Diffusers documentation

Pipelines

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

Pipelines

Los pipelines ofrecen una forma sencilla de ejecutar modelos de difusión de vanguardia en inferencia al agrupar todos los componentes necesarios (varios modelos entrenados de forma independiente, programadores y procesadores) en una única clase de extremo a extremo. Los pipelines son flexibles y se pueden adaptar para utilizar programadores o incluso componentes de modelo diferentes.

Todas las pipelines se construyen a partir de la clase base DiffusionPipeline, que proporciona la funcionalidad básica para cargar, descargar y guardar todos los componentes. Los tipos de pipeline específicos (por ejemplo, StableDiffusionPipeline) cargados con from_pretrained() se detectan automáticamente y los componentes del pipeline se cargan y se pasan a la función __init__ del pipeline.

No debe usar la clase DiffusionPipeline para el entrenamiento. Los componentes individuales (por ejemplo, UNet2DModel y UNet2DConditionModel) de los pipelines de difusión suelen entrenarse de forma individual, por lo que sugerimos trabajar directamente con ellos.


Los pipelines no ofrecen ninguna funcionalidad de entrenamiento. Notarás que el autograd de PyTorch está deshabilitado al decorar el método __call__() con el decorador torch.no_grad, ya que los pipelines no deben usarse para entrenamiento. Si te interesa el entrenamiento, ¡consulta en su lugar las guías de Training!

Use API > Pipelines en la barra lateral para consultar todas las referencias de pipelines por modalidad. Para flujos de trabajo orientados a tareas, comience con el Quickstart o con una guía como text-to-image, image-to-image, inpainting o video generation.

DiffusionPipeline

clase diffusers.DiffusionPipeline

< >

( )

Clase base para todas las tuberías.

DiffusionPipeline almacena todos los componentes (modelos, programadores y procesadores) de los pipelines de difusión y proporciona métodos para cargar, descargar y guardar modelos. También incluye métodos para:

  • mover todos los módulos de PyTorch al dispositivo de su elección
  • activar/desactivar la barra de progreso para la iteración de desruido

Atributos de clase:

  • config_name (str) — El nombre del archivo de configuración que almacena los nombres de las clases y los módulos de todos los componentes del pipeline de difusión.
  • _optional_components (List[str]) — Lista de todos los componentes opcionales que no es necesario pasar a la pipeline para que funcione (debe ser sobrescrito por las subclases).

__call__

( *args**kwargs )

Llamar a self como una función.

dispositivo

< >

( ) → torch.device

Devuelve

torch.device

El dispositivo torch en el que se encuentra el pipeline. Cuando los componentes se distribuyen entre dispositivos (por ejemplo, los codificadores de texto en la CPU mientras que el backbone de desruido se ejecuta en un acelerador), se devuelve el dispositivo del acelerador.

hasta

< >

( *args**kwargs ) → DiffusionPipeline

Parámetros

  • dtype (torch.dtype, opcional) — Devuelve un pipeline con el dtype especificado
  • device (torch.Device, opcional) — Devuelve un pipeline con el device especificado
  • silence_dtype_warnings (str, opcional, valor predeterminado False) — Si se omiten las advertencias cuando el dtype de destino no es compatible con el device de destino.

Devuelve

DiffusionPipeline

El pipeline se convirtió al dtype y/o dtype especificado.

Realiza la conversión de dtype y/o device de Pipeline. Se infieren un torch.dtype y un torch.device a partir de los argumentos de self.to(*args, **kwargs).

> Si el pipeline ya tiene el torch.dtype y el torch.device correctos, se devuelve tal cual. En caso contrario, > el pipeline devuelto es una copia de self con el torch.dtype y el torch.device deseados.

Estas son las formas de llamar a to:

  • to(dtype, silence_dtype_warnings=False) → DiffusionPipeline para devolver un pipeline con el dtype especificado
  • to(device, silence_dtype_warnings=False) → DiffusionPipeline para devolver un pipeline con el device especificado
  • to(device=None, dtype=None, silence_dtype_warnings=False) → DiffusionPipeline para devolver un pipeline con el device y el dtype especificados

componentes

< >

( )

La propiedad self.components puede ser útil para ejecutar diferentes pipelines con los mismos pesos y configuraciones sin reasignar memoria adicional.

Devuelve (dict): Un diccionario que contiene todos los módulos necesarios para inicializar la pipeline.

Ejemplos:

>>> from diffusers import (
...     StableDiffusionPipeline,
...     StableDiffusionImg2ImgPipeline,
...     StableDiffusionInpaintPipeline,
... )

>>> text2img = StableDiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> img2img = StableDiffusionImg2ImgPipeline(**text2img.components)
>>> inpaint = StableDiffusionInpaintPipeline(**text2img.components)

disable_attention_slicing

< >

( )

Desactiva el cálculo de atención segmentada. Si enable_attention_slicing se llamó previamente, la atención se calcula en un solo paso.

disable_xformers_memory_efficient_attention

< >

( )

Desactivar la atención eficiente en memoria de xFormers.

descargar

< >

( pretrained_model_name**kwargs ) → os.PathLike

Parámetros

  • pretrained_model_name (str o os.PathLike, opcional) — Una cadena, el id del repositorio (por ejemplo, CompVis/ldm-text2im-large-256) de un pipeline preentrenado alojado en el Hub.
  • custom_pipeline (str, opcional) — Puede ser:

    • Una cadena, el id del repositorio (por ejemplo, CompVis/ldm-text2im-large-256) de un pipeline preentrenado alojado en el Hub. El repositorio debe contener un archivo llamado pipeline.py que defina el pipeline personalizado.

    • Una cadena, el nombre de archivo de un pipeline de la comunidad alojado en GitHub bajo Community. Los nombres de archivo válidos deben coincidir con el nombre del archivo y no con el script del pipeline (clip_guided_stable_diffusion en lugar de clip_guided_stable_diffusion.py). Los pipelines de la comunidad siempre se cargan desde la rama main actual de GitHub.

    • Una ruta a un directorio (./my_pipeline_directory/) que contiene un pipeline personalizado. El directorio debe contener un archivo llamado pipeline.py que defina el pipeline personalizado.

    > 🧪 Esta es una función experimental y puede cambiar en el futuro.

    Para obtener más información sobre cómo cargar y crear pipelines personalizados, consulte Cómo contribuir con un pipeline de la comunidad.

  • force_download (bool, opcional, valor predeterminado False) — Indica si se debe forzar la (re)descarga de los pesos del modelo y los archivos de configuración, ignorando las versiones en caché si existen.
  • proxies (Dict[str, str], opcional) — Un diccionario de servidores proxy a utilizar por protocolo o punto de acceso, por ejemplo, {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Los proxies se utilizan en cada solicitud.
  • output_loading_info(bool, opcional, por defecto False) — Indica si se debe devolver también un diccionario que contenga las claves faltantes, las claves inesperadas y los mensajes de error.
  • local_files_only (bool, opcional, valor predeterminado False) — Indica si se deben cargar únicamente los pesos y archivos de configuración del modelo locales. Si se establece en True, el modelo no se descargará desde el Hub.
  • token (str o bool, opcional) — El token que se usará como autorización HTTP bearer para los archivos remotos. Si True, se utiliza el token generado desde diffusers-cli login (almacenado en ~/.huggingface).
  • revision (str, opcional, valor predeterminado "main") — La versión específica del modelo que se va a utilizar. Puede ser el nombre de una rama, el nombre de una etiqueta, un id de commit o cualquier identificador permitido por Git.
  • custom_revision (str, opcional, valor predeterminado "main") — La versión específica del modelo que se va a utilizar. Puede ser un nombre de rama, un nombre de etiqueta o un id de commit, similar a revision al cargar un pipeline personalizado desde el Hub. Puede ser una versión de 🤗 Diffusers al cargar un pipeline personalizado desde GitHub; de lo contrario, el valor predeterminado es "main" al cargar desde el Hub.
  • mirror (str, opcional) — Origen de espejo para resolver problemas de accesibilidad si estás descargando un modelo en China. No garantizamos la oportunidad ni la seguridad de la fuente, y debes consultar el sitio del espejo para obtener más información.
  • variant (str, opcional) — Carga los pesos desde un nombre de archivo de variante especificado, como "fp16" o "ema".
  • use_safetensors (bool, opcional, valor predeterminado None) — Si se establece en None, se descargan los pesos de safetensors si están disponibles y si la biblioteca safetensors está instalada. Si se establece en True, el modelo se carga forzosamente desde los pesos de safetensors. Si se establece en False, no se cargan los pesos de safetensors.
  • use_onnx (bool, opcional, valor predeterminado False) — Si se establece en True, los pesos de ONNX siempre se descargarán si están presentes. Si se establece en False, los pesos de ONNX nunca se descargarán. De forma predeterminada, use_onnx toma el valor del atributo de clase _is_onnx, que es False para los pipelines que no son de ONNX y True para los pipelines de ONNX. Los pesos de ONNX incluyen tanto los archivos que terminan en .onnx como en .pb.
  • trust_remote_code (bool, opcional, valor predeterminado False) — Indica si se permiten o no pipelines y componentes personalizados definidos en el Hub en sus propios archivos. Esta opción solo debe establecerse en True para repositorios de confianza en los que hayas leído el código, ya que ejecutará el código presente en el Hub en tu máquina local.
  • use_flashpack (bool, opcional, valor predeterminado False) — Si se establece en True, los pesos de FlashPack siempre se descargarán si están presentes. Si se establece en False, los pesos de FlashPack nunca se descargarán.

Devuelve

os.PathLike

Una ruta al pipeline descargado.

Descarga y almacena en caché un pipeline de difusión de PyTorch a partir de pesos de pipeline preentrenados.

> Para usar modelos privados o con acceso restringido, inicia sesión con `hf > auth login

enable_attention_slicing

< >

( slice_size: str | int = 'auto' )

Parámetros

  • slice_size (str o int, opcional, valor predeterminado "auto") — Cuando es "auto", se divide a la mitad la entrada de las cabezas de atención, de modo que la atención se calcula en dos pasos. Si es "max", se ahorra la máxima cantidad de memoria al ejecutar solo una porción a la vez. Si se proporciona un número, se usan tantas porciones como attention_head_dim // slice_size. En este caso, attention_head_dim debe ser un múltiplo de slice_size.

Habilita el cálculo de atención segmentada. Cuando esta opción está habilitada, el módulo de atención divide el tensor de entrada en fragmentos para calcular la atención en varios pasos. Para más de una cabeza de atención, el cálculo se realiza secuencialmente sobre cada cabeza. Esto es útil para ahorrar algo de memoria a cambio de una pequeña disminución en la velocidad.

> ⚠️ No actives el *slicing* de atención si ya estás usando scaled_dot_product_attention (SDPA) de PyTorch > 2.0 o xFormers. Estos cálculos de atención ya son muy eficientes en memoria, por lo que no necesitarás activar > esta función. Si activas el *slicing* de atención con SDPA o xFormers, ¡puede provocar ralentizamientos significativos!

Ejemplos:

>>> import torch
>>> from diffusers import StableDiffusionPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained(
...     "stable-diffusion-v1-5/stable-diffusion-v1-5",
...     dtype=torch.float16,
...     use_safetensors=True,
... )

>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> pipe.enable_attention_slicing()
>>> image = pipe(prompt).images[0]

enable_group_offload

< >

( onload_device: deviceoffload_device: device = torch.device()offload_type: str = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage = Falseoffload_to_disk_path: str | None = Noneexclude_modules: str | list[str] | None = None )

Parámetros

  • 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 los documentos oficiales 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.
  • exclude_modules (Union[str, List[str]], por defecto None) — Lista de módulos que se excluirán del offloading.

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 en el 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 aceleración 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 DiffusionPipeline
>>> import torch

>>> pipe = DiffusionPipeline.from_pretrained("Qwen/Qwen-Image", dtype=torch.bfloat16)

>>> pipe.enable_group_offload(
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="leaf_level",
...     use_stream=True,
... )
>>> image = pipe("a beautiful sunset").images[0]

enable_model_cpu_offload

< >

( gpu_id: int | None = Nonedevice: typing.Union[torch.device, str] = None )

Parámetros

  • gpu_id (int, opcional) — El ID del acelerador que se utilizará en la inferencia. Si no se especifica, el valor predeterminado será 0.
  • device (torch.Device o str, opcional, valor predeterminado None) — El tipo de dispositivo de PyTorch del acelerador que se utilizará en la inferencia. Si no se especifica, se detectará automáticamente el acelerador disponible y se utilizará.

Descarga todos los modelos a la CPU usando accelerate, reduciendo el uso de memoria con un bajo impacto en el rendimiento. En comparación con enable_sequential_cpu_offload, este método mueve un modelo completo a la aceleradora cuando se llama a su método forward, y el modelo permanece en la aceleradora hasta que se ejecuta el siguiente modelo. El ahorro de memoria es menor que con enable_sequential_cpu_offload, pero el rendimiento es mucho mejor debido a la ejecución iterativa de unet.

enable_sequential_cpu_offload

< >

( gpu_id: int | None = Nonedevice: typing.Union[torch.device, str] = None )

Parámetros

  • gpu_id (int, opcional) — El ID del acelerador que se utilizará en la inferencia. Si no se especifica, el valor predeterminado será 0.
  • device (torch.Device o str, opcional, valor predeterminado None) — El tipo de dispositivo de PyTorch del acelerador que se utilizará en la inferencia. Si no se especifica, se detectará automáticamente el acelerador disponible y se utilizará.

Descarga todos los modelos a la CPU usando 🤗 Accelerate, reduciendo significativamente el uso de memoria. Al llamarse, los state dicts de todos los componentes torch.nn.Module (excepto los que están en self._exclude_from_cpu_offload) se guardan en la CPU y luego se mueven a torch.device('meta') y se cargan en el acelerador solo cuando se llama al método forward de su submódulo específico. El offloading se realiza a nivel de submódulo. El ahorro de memoria es mayor que con enable_model_cpu_offload, pero el rendimiento es menor.

enable_xformers_memory_efficient_attention

< >

( attention_op: typing.Optional[typing.Callable] = None )

Parámetros

  • attention_op (Callable, opcional) — Sustituye el operador predeterminado None para usarlo como argumento op de la función memory_efficient_attention() de xFormers.

Habilita la atención eficiente en memoria desde xFormers. Cuando esta opción está habilitada, debería observar un menor uso de memoria de GPU y una posible aceleración durante la inferencia. No se garantiza una aceleración durante el entrenamiento.

> ⚠️ Cuando la atención eficiente en memoria y la atención segmentada están ambas habilitadas, la atención eficiente en memoria tiene > precedencia.

Ejemplos:

>>> import torch
>>> from diffusers import DiffusionPipeline
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> pipe = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1", dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> pipe.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)
>>> # Workaround for not accepting attention shape using VAE for Flash Attention
>>> pipe.vae.enable_xformers_memory_efficient_attention(attention_op=None)

from_pipe

< >

( pipeline**kwargs ) → DiffusionPipeline

Parámetros

  • pipeline (DiffusionPipeline) — El pipeline a partir del cual se creará un nuevo pipeline.

Devuelve

DiffusionPipeline

Un nuevo pipeline con los mismos pesos y configuraciones que pipeline.

Crea un nuevo pipeline a partir de un pipeline dado. Este método es útil para crear un nuevo pipeline a partir de los componentes existentes del pipeline sin reasignar memoria adicional.

Ejemplos:

>>> from diffusers import StableDiffusionPipeline, StableDiffusionSAGPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> new_pipe = StableDiffusionSAGPipeline.from_pipe(pipe)

from_pretrained

< >

( pretrained_model_name_or_path: str | os.PathLike**kwargs )

Parámetros

  • pretrained_model_name_or_path (str o os.PathLike, opcional) — Puede ser:
    • Una cadena de caracteres, el repo id (por ejemplo, CompVis/ldm-text2im-large-256) de un pipeline preentrenado alojado en el Hub.
    • Una ruta a un directorio (por ejemplo, ./my_pipeline_directory/) que contiene los pesos de la pipeline guardados con save_pretrained().
  • dtype (torch.dtype o dict[str, Union[str, torch.dtype]], opcional) — Sobrescribe el torch.dtype predeterminado y carga el modelo con otro dtype. Para cargar submodelos con un dtype diferente, pasa un dict (por ejemplo, {'transformer': torch.bfloat16, 'vae': torch.float16}). Establece el dtype predeterminado para los componentes no especificados con default (por ejemplo, {'transformer': torch.bfloat16, 'default': torch.float16}). Si un componente no está especificado y no se establece un valor predeterminado, se utiliza torch.float32.
  • custom_pipeline (str, opcional) —

    > 🧪 Esta es una función experimental y puede cambiar en el futuro.

    Puede ser:

    • Una cadena de caracteres, el repo id (por ejemplo hf-internal-testing/diffusers-dummy-pipeline) de un pipeline personalizado alojado en el Hub. El repositorio debe contener un archivo llamado pipeline.py que defina el pipeline personalizado.
    • Una cadena, el nombre de archivo de un pipeline de la comunidad alojado en GitHub bajo Community. Los nombres de archivo válidos deben coincidir con el nombre del archivo y no con el script del pipeline (clip_guided_stable_diffusion en lugar de clip_guided_stable_diffusion.py). Los pipelines de la comunidad siempre se cargan desde la rama principal actual de GitHub.
    • Una ruta a un directorio (./my_pipeline_directory/) que contiene un pipeline personalizado. El directorio debe contener un archivo llamado pipeline.py que defina el pipeline personalizado.

    Para obtener más información sobre cómo cargar y crear pipelines personalizados, consulte Carga y adición de pipelines personalizados

  • force_download (bool, opcional, valor predeterminado False) — Indica si se debe forzar la (re)descarga de los pesos del modelo y los archivos de configuración, ignorando las versiones en caché si existen.
  • cache_dir (Union[str, os.PathLike], opcional) — Ruta a un directorio donde se almacena en caché la configuración de un modelo preentrenado descargado si no se utiliza la caché estándar.
  • proxies (Dict[str, str], opcional) — Un diccionario de servidores proxy a utilizar por protocolo o punto de acceso, por ejemplo, {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Los proxies se utilizan en cada solicitud.
  • output_loading_info(bool, opcional, por defecto False) — Indica si se debe devolver también un diccionario que contenga las claves faltantes, las claves inesperadas y los mensajes de error.
  • local_files_only (bool, opcional, valor predeterminado False) — Indica si se deben cargar únicamente los pesos y archivos de configuración del modelo locales. Si se establece en True, el modelo no se descargará desde el Hub.
  • token (str o bool, opcional) — El token que se usará como autorización HTTP bearer para los archivos remotos. Si True, se utiliza el token generado desde diffusers-cli login (almacenado en ~/.huggingface).
  • revision (str, opcional, valor predeterminado "main") — La versión específica del modelo que se va a utilizar. Puede ser el nombre de una rama, el nombre de una etiqueta, un id de commit o cualquier identificador permitido por Git.
  • custom_revision (str, opcional) — La versión específica del modelo que se va a usar. Puede ser el nombre de una rama, el nombre de una etiqueta o un id de commit similar a revision al cargar un pipeline personalizado desde el Hub. El valor predeterminado es la última versión estable de 🤗 Diffusers.
  • mirror (str, opcional) — Origen de espejo para resolver problemas de accesibilidad si estás descargando un modelo en China. No garantizamos la oportunidad ni la seguridad de la fuente, y debes consultar el sitio del espejo para obtener más información.
  • device_map (str, opcional) — Estrategia que determina cómo deben colocarse los distintos componentes de un pipeline en los dispositivos disponibles. Actualmente, solo se admite device_map “balanced”. Consulta esto para obtener más información.
  • max_memory (Dict, opcional) — Un diccionario con el identificador de dispositivo para la memoria máxima. Si no se establece, se usará la memoria máxima disponible para cada GPU y la RAM de CPU disponible.
  • offload_folder (str o os.PathLike, opcional) — La ruta para descargar los pesos si device_map contiene el valor "disk".
  • offload_state_dict (bool, opcional) — Si es True, descarga temporalmente el state dict de CPU al disco duro para evitar quedarse sin RAM de CPU si el peso del state dict de CPU + el shard más grande del checkpoint no cabe. El valor predeterminado es True cuando hay alguna descarga a disco.
  • low_cpu_mem_usage (bool, opcional, por defecto True si la versión de torch >= 1.9.0, en caso contrario False) — Acelera la carga del modelo cargando solo los pesos preentrenados y sin inicializar los pesos. Esto también intenta no usar más de 1x el tamaño del modelo en memoria de CPU (incluida la memoria pico) durante la carga del modelo. Solo compatible con PyTorch >= 1.9.0. Si estás usando una versión anterior de PyTorch, establecer este argumento en True generará un error.
  • use_safetensors (bool, opcional, valor predeterminado None) — Si se establece en None, se descargan los pesos de safetensors si están disponibles y si la biblioteca safetensors está instalada. Si se establece en True, el modelo se carga forzosamente desde los pesos de safetensors. Si se establece en False, no se cargan los pesos de safetensors.
  • use_onnx (bool, opcional, valor predeterminado None) — Si se establece en True, los pesos de ONNX siempre se descargarán si están presentes. Si se establece en False, los pesos de ONNX nunca se descargarán. De forma predeterminada, use_onnx toma el valor del atributo de clase _is_onnx, que es False para los pipelines que no son de ONNX y True para los pipelines de ONNX. Los pesos de ONNX incluyen tanto los archivos que terminan en .onnx como en .pb.
  • kwargs (diccionario restante de argumentos de palabra clave, opcional) — Se puede usar para sobrescribir las variables de carga y guardado (los componentes de pipeline de la clase de pipeline específica). Los componentes sobrescritos se pasan directamente al método __init__ de los pipelines. Consulte el ejemplo siguiente para obtener más información.
  • variant (str, opcional) — Carga los pesos desde un nombre de archivo de variante especificado, como "fp16" o "ema".
  • disable_mmap (‘bool’, opcional, valor predeterminado ‘False’) — Si se deshabilita mmap al cargar un modelo de Safetensors. Esta opción puede ofrecer un mejor rendimiento cuando el modelo está en una unidad de red o en un disco duro, que pueden no manejar bien la naturaleza de búsquedas aleatorias de mmap.

Instanciar un pipeline de difusión de PyTorch a partir de pesos de pipeline preentrenados.

El pipeline se configura en modo de evaluación (model.eval()) de forma predeterminada.

Si obtienes el siguiente mensaje de error, necesitas ajustar los pesos para tu tarea de destino:

Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.

> Para usar modelos privados o con acceso restringido, inicia sesión con hf > auth login.

Ejemplos:

>>> from diffusers import DiffusionPipeline

>>> # Download pipeline from huggingface.co and cache.
>>> pipeline = DiffusionPipeline.from_pretrained("CompVis/ldm-text2im-large-256")

>>> # Download pipeline that requires an authorization token
>>> # For more information on access tokens, please refer to this section
>>> # of the documentation](https://huggingface.co/docs/hub/security-tokens)
>>> pipeline = DiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")

>>> # Use a different scheduler
>>> from diffusers import LMSDiscreteScheduler

>>> scheduler = LMSDiscreteScheduler.from_config(pipeline.scheduler.config)
>>> pipeline.scheduler = scheduler

maybe_free_model_hooks

< >

( )

Método que realiza lo siguiente:

  • Descarga todos los componentes.
  • Elimina todos los hooks del modelo que se añadieron al usar enable_model_cpu_offload y luego los aplica de nuevo. En caso de que el modelo no haya sido descargado, esta función no realiza ninguna acción.
  • Restablece los hooks con estado de los componentes denoiser de diffusers si se añadieron con register_hook().

Asegúrate de añadir esta función al final de la función __call__ de tu pipeline para que funcione correctamente al aplicar enable_model_cpu_offload.

numpy_to_pil

< >

( images )

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

remove_all_hooks

< >

( )

Elimina todos los hooks que se añadieron al usar enable_sequential_cpu_offload o enable_model_cpu_offload.

reset_device_map

< >

( )

Restablece los mapas de dispositivos (si los hay) a None.

save_pretrained

< >

( save_directory: str | os.PathLikesafe_serialization: bool = Truevariant: str | None = Nonemax_shard_size: int | str | None = Nonepush_to_hub: bool = Falseuse_flashpack: bool = False**kwargs )

Parámetros

  • save_directory (str o os.PathLike) — Directorio donde se guardará el pipeline. Se creará si no existe.
  • safe_serialization (bool, opcional, valor predeterminado True) — Si se guarda el modelo usando safetensors o de la forma tradicional de PyTorch con pickle.
  • variant (str, opcional) — Si se especifica, los pesos se guardan en el formato pytorch_model.<variant>.bin.
  • max_shard_size (int o str, por defecto None) — El tamaño máximo de un checkpoint antes de ser fragmentado. Los fragmentos del checkpoint tendrán cada uno un tamaño inferior a este valor. Si se expresa como una cadena de caracteres, debe consistir en dígitos seguidos de una unidad (como "5GB"). Si se expresa como un entero, la unidad es bytes. Tenga en cuenta que este límite se reducirá después de un cierto período de tiempo (a partir de octubre de 2024) para permitir a los usuarios actualizar a la última versión de diffusers. Esto se hace para establecer un tamaño predeterminado común para este argumento en diferentes bibliotecas del ecosistema de Hugging Face (transformers y accelerate, por ejemplo).
  • push_to_hub (bool, opcional, valor predeterminado False) — Indica si se debe subir el modelo al hub de modelos de Hugging Face después de guardarlo. Puedes especificar el repositorio al que deseas subirlo con repo_id (por defecto, usará el nombre de save_directory en tu espacio de nombres).
  • kwargs (Dict[str, Any], opcional) — Argumentos de palabra clave adicionales que se pasan al método push_to_hub().

Guarda todas las variables guardables del pipeline en un directorio. Una variable del pipeline se puede guardar y cargar si su clase implementa tanto un método de guardado como uno de carga. El pipeline se puede recargar fácilmente mediante el método de clase from_pretrained().

diffusers.StableDiffusionMixin.enable_freeu

< >

( s1: floats2: floatb1: floatb2: float )

Parámetros

  • s1 (float) — Factor de escala para la etapa 1 para atenuar las contribuciones de las características de salto. Esto se hace para mitigar el “efecto de sobre-almohadillado” en el proceso de desruido mejorado.
  • s2 (float) — Factor de escala para la etapa 2 para atenuar las contribuciones de las características de salto. Esto se hace para mitigar el “efecto de sobre-almohadillado” en el proceso de desruido mejorado.
  • b1 (float) — Factor de escala para la etapa 1 para amplificar las contribuciones de las características del backbone.
  • b2 (float) — Factor de escala para la etapa 2 para amplificar las contribuciones de las características del backbone.

Habilita el mecanismo FreeU tal como se describe en https://huggingface.co/papers/2309.11497.

Los sufijos después de los factores de escalado representan las etapas en las que se están aplicando.

Consulte el repositorio oficial para conocer las combinaciones de valores que funcionan bien en diferentes pipelines, como Stable Diffusion v1, v2 y Stable Diffusion XL.

diffusers.StableDiffusionMixin.disable_freeu

< >

( )

Desactiva el mecanismo FreeU si está habilitado.

PushToHubMixin

clase diffusers.utils.PushToHubMixin

< >

( )

Un Mixin para subir un modelo, un programador o un pipeline al Hugging Face Hub.

push_to_hub

< >

( repo_id: strcommit_message: str | None = Noneprivate: bool | None = Nonetoken: str | None = Nonecreate_pr: bool = Falsesafe_serialization: bool = Truevariant: str | None = Nonesubfolder: str | None = None )

Parámetros

  • repo_id (str) — El nombre del repositorio al que deseas subir tus archivos de modelo, programador o pipeline. Debe contener el nombre de tu organización cuando subas a una organización. repo_id también puede ser una ruta a un directorio local.
  • commit_message (str, opcional) — Mensaje para el commit al hacer push. Por defecto, "Upload {object}".
  • private (bool, opcional) — Si se debe hacer el repositorio privado. Si es None (predeterminado), el repositorio será público a menos que el valor predeterminado de la organización sea privado. Este valor se ignora si el repositorio ya existe.
  • token (str, opcional) — El token que se usará como autorización HTTP bearer para archivos remotos. El token generado al ejecutar hf auth login (guardado en ~/.huggingface).
  • create_pr (bool, opcional, valor predeterminado False) — Si se debe crear una PR con los archivos subidos o realizar el commit directamente.
  • safe_serialization (bool, opcional, valor predeterminado True) — Indica si se deben convertir los pesos del modelo al formato safetensors.
  • variant (str, opcional) — Si se especifica, los pesos se guardan en el formato pytorch_model.<variant>.bin.

Sube archivos de modelo, programador o pipeline al 🤗 Hugging Face Hub.

Ejemplos:

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-2", subfolder="unet")

# Push the `unet` to your namespace with the name "my-finetuned-unet".
unet.push_to_hub("my-finetuned-unet")

# Push the `unet` to an organization with the name "my-finetuned-unet".
unet.push_to_hub("your-org/my-finetuned-unet")

Callbacks

clase diffusers.callbacks.PipelineCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Clase base para todos los callbacks oficiales utilizados en un pipeline. Esta clase proporciona una estructura para implementar callbacks personalizados y garantiza que todos los callbacks tengan una interfaz coherente.

Implemente lo siguiente: tensor_inputs: debe devolver una lista de entradas de tensor específicas para su callback. Solo podrá incluir variables enumeradas en el atributo ._callback_tensor_inputs de su clase de pipeline. callback_fn: este método define la funcionalidad principal de su callback.

clase diffusers.callbacks.SDCFGCutoffCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Función de callback para las pipelines de Stable Diffusion. Después de un número determinado de pasos (establecido por cutoff_step_ratio o cutoff_step_index), este callback desactivará el CFG.

Nota: Este callback modifica el pipeline cambiando el atributo _guidance_scale a 0.0 después del paso de corte.

clase diffusers.callbacks.SDXLCFGCutoffCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Función de callback para las Pipelines base de Stable Diffusion XL. Después de un número determinado de pasos (establecido por cutoff_step_ratio o cutoff_step_index), este callback desactivará el CFG.

Nota: Este callback modifica el pipeline cambiando el atributo _guidance_scale a 0.0 después del paso de corte.

clase diffusers.callbacks.SDXLControlnetCFGCutoffCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Función de callback para las pipelines de Controlnet Stable Diffusion XL. Después de un número determinado de pasos (establecido por cutoff_step_ratio o cutoff_step_index), esta callback deshabilitará el CFG.

Nota: Este callback modifica el pipeline cambiando el atributo _guidance_scale a 0.0 después del paso de corte.

clase diffusers.callbacks.IPAdapterScaleCutoffCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Función de callback para cualquier pipeline que herede de IPAdapterMixin. Después de un número determinado de pasos (establecido por cutoff_step_ratio o cutoff_step_index), este callback establecerá la escala del IP Adapter en 0.0.

Nota: Este callback modifica los procesadores de atención del IP Adapter estableciendo la escala en 0.0 después del paso de corte.

clase diffusers.callbacks.SD3CFGCutoffCallback

< >

( cutoff_step_ratio = 1.0cutoff_step_index = None )

Función de callback para los pipelines de Stable Diffusion 3. Después de un número determinado de pasos (establecido por cutoff_step_ratio o cutoff_step_index), este callback desactivará el CFG.

Nota: Este callback modifica el pipeline cambiando el atributo _guidance_scale a 0.0 después del paso de corte.

Update on GitHub

←VQModel AutoPipeline→