Formats de modèles

Les modèles de diffusion sont généralement stockés au format Diffusers ou au format fichier unique. Les fichiers de modèle peuvent être stockés dans divers types de fichiers, tels que safetensors ou ckpt.

Le format désigne si les poids sont stockés dans une structure de répertoires. Le type de fichier désigne la manière dont ces poids sont sérialisés, par exemple en safetensors ou en 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/

Ce guide vous montre comment charger des pipelines et des modèles à partir de ces formats et fichiers.

Format Diffusers

Le format Diffusers stocke chaque modèle (UNet, transformer, encodeur de texte) dans un sous-dossier distinct. Le stockage séparé des modèles présente plusieurs avantages.

Initialisation plus rapide du pipeline global, car vous pouvez charger le modèle individuel dont vous avez besoin ou les charger tous en parallèle.
Réduction de l’utilisation de la mémoire, car il n’est pas nécessaire de charger tous les composants du pipeline si un seul modèle est requis. Réutiliser un modèle partagé entre plusieurs pipelines.
Exigences de stockage réduites, car les modèles communs partagés entre plusieurs pipelines ne sont téléchargés qu'une seule fois.
Flexibilité pour utiliser de nouveaux modèles ou des modèles améliorés dans un pipeline.

Format de fichier unique

Le format à fichier unique stocke tous les poids du modèle (UNet, transformer, encodeur de texte) dans un seul fichier. Les avantages des formats à fichier unique incluent :

Meilleure compatibilité avec ComfyUI ou Automatic1111.
Plus facile de télécharger et de partager un seul fichier.

Utilisez from_single_file() pour charger un fichier unique.

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

La méthode from_single_file() prend également en charge le passage de nouveaux modèles ou planificateurs.

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

Options de configuration

Les modèles au format Diffusers disposent d'un fichier config.json dans leurs dépôts, contenant des attributs importants tels que le nombre de couches et de têtes d'attention. La méthode from_single_file() détermine automatiquement la configuration appropriée à partir de config.json. Cela peut toutefois échouer dans quelques cas rares, auquel cas vous devez utiliser l'argument config.

Vous devez également utiliser l'argument config si les modèles d'un pipeline diffèrent de l'implémentation originale ou s'il ne dispose pas des métadonnées nécessaires pour déterminer la configuration correcte.

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

Lorsque vous passez original_config avec local_files_only=True, Diffusers infère les composants du pipeline à partir de la signature de la classe de pipeline. Il ne télécharge pas les fichiers de configuration depuis le Hub, ce qui évite les modifications cassantes lorsque vous êtes hors ligne. Cette méthode est moins fiable que de fournir à config un chemin local vers un modèle, et peut générer une erreur. Exécutez une fois avec local_files_only=False afin que les configurations soient enregistrées dans le cache local, au cas où vous en auriez besoin hors ligne plus tard.

Écrasez les configurations par défaut en passant directement les arguments à from_single_file(). Les exemples ci-dessous montrent comment écraser les configurations dans un pipeline ou un modèle.

pipeline

model

Fichiers locaux

La méthode from_single_file() tente de configurer un pipeline ou un modèle en déduisant le type de modèle à partir des clés du fichier de checkpoint. Par exemple, tout checkpoint en fichier unique basé sur le modèle de base Stable Diffusion XL est configuré à partir de stabilityai/stable-diffusion-xl-base-1.0.

Si vous travaillez avec des fichiers locaux, téléchargez les fichiers de configuration avec la méthode snapshot_download et le point de contrôle du modèle avec hf_hub_download. Ces fichiers sont téléchargés dans votre répertoire de cache, mais vous pouvez les télécharger dans un répertoire spécifique à l'aide de l'argument 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
)

Lien symbolique

Si vous travaillez avec un système de fichiers qui ne prend pas en charge les liens symboliques, téléchargez d’abord le fichier de point de contrôle dans un répertoire local à l’aide du paramètre local_dir. L’utilisation du paramètre local_dir désactive automatiquement les liens symboliques.

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)

Pass these paths to from_single_file().

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

Types de fichiers

Les modèles peuvent être stockés dans plusieurs types de fichiers. Safetensors est le type de fichier le plus courant, mais vous pouvez rencontrer d'autres types de fichiers sur le Hub ou au sein de la communauté de la diffusion.

safetensors

Safetensors est un type de fichier sûr et rapide pour stocker et charger des tenseurs de manière sécurisée. Il limite la taille de l’en-tête afin de restreindre certains types d’attaques, prend en charge le chargement paresseux (utile pour les configurations distribuées) et se charge généralement plus rapidement.

Diffusers charge le fichier safetensors par défaut (une dépendance requise) s'il est disponible et si la bibliothèque Safetensors est installée.

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 vous utilisez un point de contrôle entraîné avec un script d’entraînement Diffusers, les métadonnées telles que la configuration LoRA sont automatiquement enregistrées. Lorsque le fichier est chargé, ces métadonnées sont analysées afin que le LoRA soit correctement configuré. Inspectez les métadonnées d’un fichier safetensors en cliquant sur l’icône située à côté du fichier sur le Hub.

Enregistrez les métadonnées des adaptateurs LoRA pour les points de contrôle non entraînés avec Diffusers en les transmettant à save_lora_weights(). Utilisez transformer_lora_adapter_metadata pour le transformer et text_encoder_lora_adapter_metadata pour l’encodeur de texte. Vous devez également transmettre save_directory et au moins l’un des paramètres transformer_lora_layers ou text_encoder_lora_layers. Ce chemin n’est pris en charge que pour les fichiers 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

Les poids des modèles plus anciens sont généralement enregistrés à l'aide de l'utilitaire pickle de Python dans un fichier ckpt.

Les fichiers pickled peuvent être dangereux car ils peuvent être exploités pour exécuter du code malveillant. Il est recommandé d’utiliser des fichiers safetensors ou de convertir les poids en fichiers safetensors.

Utilisez from_single_file() pour charger un fichier 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 stocke les poids pré-quantifiés dans un fichier unique. Diffusers charge les GGUF via le modèle from_single_file() avec GGUFQuantizationConfig. Le chargement de GGUF au niveau du pipeline n'est pas pris en charge.

Consultez GGUF pour les étapes d’installation et des exemples complets.

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

Conversion des formats et des fichiers

Diffusers fournit des scripts et des méthodes pour convertir des formats et des fichiers afin que davantage d’outils de l’écosystème de diffusion puissent les utiliser.

Consultez le dossier diffusers/scripts pour trouver un script de conversion. Les scripts dont le nom se termine par "to_diffusers" convertissent un modèle au format Diffusers. Chaque script possède un ensemble d’arguments spécifique pour configurer la conversion. Assurez-vous de vérifier les arguments disponibles.

L’exemple ci-dessous convertit un modèle stocké au format Diffusers vers un format à fichier unique. Fournissez le chemin du modèle à convertir ainsi que l’emplacement où enregistrer le modèle converti. Vous pouvez éventuellement spécifier le type de fichier et le type de données à utiliser pour enregistrer le modèle.

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

La méthode save_pretrained() enregistre également un modèle au format Diffusers et s'occupe de créer des sous-dossiers pour chaque modèle. Par défaut, elle enregistre les fichiers au format 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")

Étapes suivantes

En savoir plus sur les décisions de conception et sur la raison pour laquelle les fichiers safetensor sont préférés pour l’enregistrement et le chargement des poids des modèles dans le billet de blog Safetensors audited as really safe and becoming the default.

Update on GitHub