DiffusionPipeline

Los modelos de difusión constan de varios componentes, como UNets o transformadores de difusión (DiTs), codificadores de texto, autoencoders variacionales (VAEs) y programadores. El DiffusionPipeline agrupa todos estos componentes en una única API fácil de usar, sin renunciar a la flexibilidad de modificar sus componentes.

Esta guía te mostrará cómo cargar un DiffusionPipeline.

Cargar un pipeline

DiffusionPipeline es una clase de pipeline base que selecciona y devuelve automáticamente una instancia de una subclase de pipeline del modelo, como QwenImagePipeline, al buscar el nombre de la clase en el archivo model_index.json.

Pase un id de modelo a from_pretrained() para cargar un pipeline.

import torch
from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

Cada modelo tiene una subclase de pipeline específica que hereda de DiffusionPipeline. Una subclase suele tener un enfoque estrecho y ser específica de la tarea. Consulte la tabla siguiente para ver un ejemplo.

Podrías usar la subclase directamente pasando un id de modelo a from_pretrained().

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

Consulte la documentación de Single file format para aprender a cargar modelos de archivo único.

Pipelines locales

Los pipelines también se pueden ejecutar localmente. Utilice snapshot_download para descargar un repositorio de modelos.

from huggingface_hub import snapshot_download

local_dir = snapshot_download(repo_id="Qwen/Qwen-Image")

Pasa esa ruta a from_pretrained() para cargarla.

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  local_dir, dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

El método from_pretrained() no descargará archivos del Hub cuando detecte una ruta local. Pero esto también significa que no descargará ni almacenará en caché ninguna actualización que se haya realizado en el modelo.

Tipos de datos de Pipeline

Use el argumento dtype en from_pretrained() para cargar un modelo con un tipo de datos específico. Esto permite cargar diferentes modelos en distintas precisiones. Por ejemplo, cargar un modelo de transformer grande en media precisión reduce la memoria requerida.

Pase el tipo de datos de cada modelo como un diccionario a dtype. Use la clave default para establecer el tipo de datos predeterminado. Si un modelo no está en el diccionario y no se proporciona default, se cargará en precisión completa (torch.float32).

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype={"transformer": torch.bfloat16, "default": torch.float16},
)
print(pipeline.transformer.dtype, pipeline.vae.dtype)

No es necesario usar un diccionario si estás cargando todos los modelos en el mismo tipo de datos.

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16
)
print(pipeline.transformer.dtype, pipeline.vae.dtype)

Colocación de dispositivos

El argumento device_map coloca un pipeline en dispositivos. En tiempo de ejecución, Diffusers acepta "balanced", "cpu" y la cadena del acelerador de la máquina en la que te encuentres (típicamente "cuda", "mps" o "xpu").

Use el argumento max_memory en from_pretrained() para asignar una cantidad máxima de memoria a utilizar en cada dispositivo. De forma predeterminada, Diffusers utiliza la cantidad máxima disponible.

import torch
from diffusers import DiffusionPipeline

max_memory = {0: "16GB", 1: "16GB"}
pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype=torch.bfloat16,
  device_map="balanced",
  max_memory=max_memory,
)

El atributo hf_device_map le permite acceder y ver el device_map.

print(pipeline.hf_device_map)
# {'transformer': 1, 'vae': 1, 'text_encoder': 0}

Restablezca el device_map de un pipeline con el método reset_device_map(). Esto es necesario si desea utilizar métodos como .to(), enable_sequential_cpu_offload() y enable_model_cpu_offload().

pipeline.reset_device_map()

Carga en paralelo

Los modelos grandes suelen dividirse en archivos más pequeños para facilitar su carga. Diffusers admite la carga de fragmentos en paralelo para acelerar el proceso de carga.

Establezca HF_ENABLE_PARALLEL_LOADING en "YES" para habilitar la carga paralela de fragmentos.

El argumento device_map debe establecerse en "cuda" para preasignar un gran bloque de memoria en función del tamaño del modelo. Esto reduce considerablemente el tiempo de carga del modelo, ya que la inicialización del asignador de memoria evita muchas llamadas más pequeñas al asignador en etapas posteriores.

import os
import torch
from diffusers import DiffusionPipeline

os.environ["HF_ENABLE_PARALLEL_LOADING"] = "YES"

pipeline = DiffusionPipeline.from_pretrained(
  "Wan-AI/Wan2.2-I2V-A14B-Diffusers", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

Reemplazo de modelos en un pipeline

DiffusionPipeline es flexible y permite cargar otros modelos o programadores. Puedes experimentar con diferentes programadores para optimizar la velocidad o la calidad de la generación, y puedes reemplazar los modelos por otros más eficientes.

El ejemplo siguiente utiliza una versión más estable de VAE.

import torch
from diffusers import DiffusionPipeline, AutoModel

vae = AutoModel.from_pretrained(
  "madebyollin/sdxl-vae-fp16-fix", dtype=torch.float16
)

pipeline = DiffusionPipeline.from_pretrained(
  "stabilityai/stable-diffusion-xl-base-1.0",
  vae=vae,
  dtype=torch.float16,
  device_map="cuda"  # or "mps", "xpu", "cpu"
)

Reutilización de modelos en varios pipelines

Al trabajar con varios pipelines que utilizan el mismo modelo, el método from_pipe() permite reutilizar el modelo en lugar de recargarlo cada vez. Esto permite usar múltiples pipelines sin aumentar el uso de memoria.

El uso de memoria lo determina la canalización con el mayor requisito de memoria, independientemente del número de canalizaciones.

El siguiente ejemplo carga un pipeline y luego carga un segundo pipeline con from_pipe() para usar perturbed-attention guidance (PAG) para mejorar la calidad de la generación.

Usa AutoPipelineForText2Image porque DiffusionPipeline no admite PAG. Consulta la documentación de AutoPipeline para obtener más información.

import torch
from diffusers import AutoPipelineForText2Image

pipeline_sdxl = AutoPipelineForText2Image.from_pretrained(
  "stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
image = pipeline_sdxl(prompt).images[0]
print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB")
# Max memory reserved: 10.47 GB

Establezca enable_pag=True en el segundo pipeline para habilitar PAG. El segundo pipeline utiliza la misma cantidad de memoria porque comparte los pesos del modelo con el primero.

pipeline = AutoPipelineForText2Image.from_pipe(
  pipeline_sdxl, enable_pag=True
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
image = pipeline(prompt).images[0]
print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB")
# Max memory reserved: 10.47 GB

Los pipelines creados por from_pipe() comparten los mismos modelos y state. Modificar el estado de un modelo en un pipeline afecta a todos los demás pipelines que comparten el mismo modelo.

Algunos métodos pueden no funcionar correctamente en pipelines creados con from_pipe(). Por ejemplo, enable_model_cpu_offload() depende de un orden de ejecución del modelo único, que puede diferir en el nuevo pipeline. Para garantizar un funcionamiento adecuado, reaplique estos métodos en el nuevo pipeline.

Próximos pasos

Una vez que se carga un pipeline, normalmente se ajusta el programa de desruido, se cambia el formato de los pesos o se adjuntan adaptadores.

• Schedulers cubre el intercambio y la configuración del algoritmo de eliminación de ruido.
• Formatos de modelo cubre GGUF, puntos de control de archivo único y otros diseños de pesos.
• Reducir el uso de memoria cubre el descargado y otras herramientas de memoria.
• LoRA cubre la carga de adaptadores en un pipeline.
• Puntos de control antiguos cubre el verificador de seguridad para puntos de control antiguos de Stable Diffusion.