Formatos de modelo

Los modelos de difusión suelen almacenarse en el formato Diffusers o en el formato de archivo único. Los archivos de modelo pueden guardarse en varios tipos de archivo, como safetensors o ckpt.

Format se refiere a si los pesos se almacenan en una estructura de directorios. File type se refiere a cómo se serializan esos pesos, como safetensors o ckpt.

Diffusers format                    Single-file format
model/                              model.safetensors   (or .ckpt)
├─ model_index.json                 └─ all components in one file
├─ unet/  (or transformer/)
├─ text_encoder/
├─ vae/
└─ scheduler/

Esta guía te mostrará cómo cargar pipelines y modelos desde estos formatos y archivos.

Formato de Diffusers

El formato de Diffusers almacena cada modelo (UNet, transformer, text encoder) en una subcarpeta separada. Hay varias ventajas en almacenar los modelos por separado.

La inicialización general del pipeline es más rápida porque puedes cargar el modelo individual que necesitas o cargarlos todos en paralelo.
Menor uso de memoria porque no necesitas cargar todos los componentes del pipeline si solo necesitas un modelo. Reutiliza un modelo que se comparte entre varios pipelines.
Requisitos de almacenamiento más bajos, ya que los modelos comunes compartidos entre varios pipelines solo se descargan una vez.
Flexibilidad para utilizar modelos nuevos o mejorados en un pipeline.

Formato de archivo único

El formato de archivo único almacena todos los pesos del modelo (UNet, transformer, text encoder) en un solo archivo. Entre las ventajas de los formatos de archivo único se incluyen:

Mayor compatibilidad con ComfyUI o Automatic1111.
Más fácil de descargar y compartir un único archivo.

Use from_single_file() para cargar un solo archivo.

import torch
from diffusers import StableDiffusionXLPipeline

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
    dtype=torch.float16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)

El método from_single_file() también permite pasar nuevos modelos o programadores.

import torch
from diffusers import FluxPipeline, FluxTransformer2DModel

transformer = FluxTransformer2DModel.from_single_file(
    "https://huggingface.co/Kijai/flux-fp8/blob/main/flux1-dev-fp8.safetensors", dtype=torch.bfloat16
)
pipeline = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev",
    transformer=transformer,
    dtype=torch.bfloat16,
    device_map="cuda"  # or "mps", "xpu", "cpu"
)

Opciones de configuración

Los modelos en formato Diffusers tienen un archivo config.json en sus repositorios con atributos importantes, como el número de capas y cabezas de atención. El método from_single_file() determina automáticamente la configuración adecuada a partir de config.json. Sin embargo, esto puede fallar en algunas instancias raras, en cuyo caso debes usar el argumento config.

También debe usar el argumento config si los modelos de un pipeline son diferentes de la implementación original o si no tienen los metadatos necesarios para determinar la configuración correcta.

from diffusers import StableDiffusionXLPipeline

ckpt_path = "https://huggingface.co/segmind/SSD-1B/blob/main/SSD-1B.safetensors"

pipeline = StableDiffusionXLPipeline.from_single_file(ckpt_path, config="segmind/SSD-1B")

Cuando pasas original_config con local_files_only=True, Diffusers infiere los componentes del pipeline a partir de la firma de la clase del pipeline. No descarga archivos de configuración desde el Hub, lo que evita cambios que rompan la compatibilidad cuando estás sin conexión. Esa ruta es menos fiable que proporcionar a config una ruta local de un modelo, y puede generar un error. Ejecuta una vez con local_files_only=False para que las configuraciones se guarden en la caché local por si las necesitas sin conexión más adelante.

Sobrescriba las configuraciones predeterminadas pasando los argumentos directamente a from_single_file(). Los ejemplos a continuación demuestran cómo sobrescribir las configuraciones en un pipeline o modelo.

pipeline

model

Archivos locales

El método from_single_file() intenta configurar un pipeline o modelo inferiendo el tipo de modelo a partir de las claves del archivo de checkpoint. Por ejemplo, cualquier checkpoint de archivo único basado en el modelo base de Stable Diffusion XL se configura desde stabilityai/stable-diffusion-xl-base-1.0.

Si estás trabajando con archivos locales, descarga los archivos de configuración con el método snapshot_download y el punto de control del modelo con hf_hub_download. Estos archivos se descargan en tu directorio de caché, pero puedes descargarlos en un directorio específico con el argumento local_dir.

from huggingface_hub import hf_hub_download, snapshot_download
from diffusers import StableDiffusionXLPipeline

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors"
)

my_local_config_path = snapshot_download(
    repo_id="segmind/SSD-1B",
    allow_patterns=["*.json", "**/*.json", "*.txt", "**/*.txt"]
)

pipeline = StableDiffusionXLPipeline.from_single_file(
    my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)

Enlace simbólico

Si estás trabajando con un sistema de archivos que no admite enlaces simbólicos, descarga primero el archivo de punto de control en un directorio local mediante el parámetro local_dir. El uso del parámetro local_dir desactiva automáticamente los enlaces simbólicos.

from huggingface_hub import hf_hub_download, snapshot_download
from diffusers import StableDiffusionXLPipeline

my_local_checkpoint_path = hf_hub_download(
    repo_id="segmind/SSD-1B",
    filename="SSD-1B.safetensors",
    local_dir="my_local_checkpoints",
)
print("My local checkpoint: ", my_local_checkpoint_path)

my_local_config_path = snapshot_download(
    repo_id="segmind/SSD-1B",
    allow_patterns=["*.json", "**/*.json", "*.txt", "**/*.txt"]
)
print("My local config: ", my_local_config_path)

Pase estas rutas a from_single_file().

pipeline = StableDiffusionXLPipeline.from_single_file(
    my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)

Tipos de archivo

Los modelos se pueden almacenar en varios tipos de archivo. Safetensors es el tipo de archivo más común, pero es posible que encuentres otros tipos de archivo en el Hub o en la comunidad de difusión.

safetensors

Safetensors es un tipo de archivo seguro y rápido para almacenar y cargar tensors de forma segura. Limita el tamaño de la cabecera para restringir ciertos tipos de ataques, admite la carga diferida (útil en configuraciones distribuidas) y, en general, se carga más rápido.

Diffusers carga el archivo safetensors de forma predeterminada (una dependencia requerida) si está disponible y la biblioteca Safetensors está instalada.

Use from_pretrained() or from_single_file() to load safetensor files.

import torch
from diffusers import DiffusionPipeline, StableDiffusionXLPipeline

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

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
    dtype=torch.float16,
)

Si estás utilizando un checkpoint entrenado con un script de entrenamiento de Diffusers, los metadatos, como la configuración de LoRA, se guardan automáticamente. Cuando se carga el archivo, esos metadatos se analizan para que la configuración de LoRA sea correcta. Inspecciona los metadatos de un archivo safetensors haciendo clic en el icono junto al archivo en el Hub.

Guarde los metadatos del adaptador LoRA para los puntos de control que no se entrenaron con Diffusers pasándolos a save_lora_weights(). Use transformer_lora_adapter_metadata para el transformer y text_encoder_lora_adapter_metadata para el codificador de texto. También debe pasar save_directory y al menos uno de transformer_lora_layers o text_encoder_lora_layers. Esta ruta solo se admite para archivos safetensors.

import torch
from peft.utils import get_peft_model_state_dict
from diffusers import FluxPipeline

pipeline = FluxPipeline.from_pretrained(
    "black-forest-labs/FLUX.1-dev", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
pipeline.load_lora_weights("linoyts/yarn_art_Flux_LoRA")

transformer_lora_layers = get_peft_model_state_dict(pipeline.transformer)
pipeline.save_lora_weights(
    save_directory="path/to/lora",
    transformer_lora_layers=transformer_lora_layers,
    transformer_lora_adapter_metadata={"r": 8, "lora_alpha": 8},
)

ckpt

Los pesos de modelos antiguos se guardan comúnmente con la utilidad pickle de Python en un archivo ckpt.

Los archivos pickled pueden ser inseguros porque pueden explotarse para ejecutar código malicioso. Se recomienda usar archivos safetensors o convertir los pesos a archivos safetensors.

Use from_single_file() para cargar un archivo ckpt.

from diffusers import StableDiffusionPipeline

pipeline = StableDiffusionPipeline.from_single_file(
    "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/blob/main/v1-5-pruned.ckpt"
)

GGUF

GGUF almacena pesos precuantizados en un solo archivo. Diffusers carga GGUF a través del método from_single_file() del modelo con GGUFQuantizationConfig. No se admite la carga de GGUF a nivel de pipeline.

Consulte GGUF para los pasos de instalación y ejemplos completos.

import torch
from diffusers import FluxTransformer2DModel, GGUFQuantizationConfig

transformer = FluxTransformer2DModel.from_single_file(
    "https://huggingface.co/city96/FLUX.1-dev-gguf/blob/main/flux1-dev-Q2_K.gguf",
    quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
)

Conversión de formatos y archivos

Diffusers proporciona scripts y métodos para convertir formatos y archivos, de modo que más herramientas del ecosistema de difusión puedan utilizarlos.

Mira la carpeta diffusers/scripts para encontrar un script de conversión. Los scripts con "to_diffusers" al final convierten un modelo al formato de Diffusers. Cada script tiene un conjunto específico de argumentos para configurar la conversión. Asegúrate de comprobar qué argumentos están disponibles.

El ejemplo siguiente convierte un modelo almacenado en formato Diffusers a un formato de archivo único. Proporcione la ruta del modelo a convertir y el lugar donde guardar el modelo convertido. Opcionalmente, puede especificar el tipo de archivo y el tipo de datos en los que se guardará el modelo.

python convert_diffusers_to_original_sdxl.py --model_path path/to/model/to/convert --checkpoint_path path/to/save/model/to --use_safetensors

El método save_pretrained() también guarda un modelo en el formato de Diffusers y se encarga de crear subcarpetas para cada modelo. Por defecto, guarda los archivos como archivos safetensor.

from diffusers import StableDiffusionXLPipeline

pipeline = StableDiffusionXLPipeline.from_single_file(
    "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0.safetensors",
)
pipeline.save_pretrained("path/to/save/model")

Próximos pasos

Obtenga más información sobre las decisiones de diseño y por qué los archivos safetensor son preferidos para guardar y cargar los pesos de los modelos en la publicación de blog Safetensors audited as really safe and becoming the default.

Update on GitHub