# 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. > [!TIP] > 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. ```text 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 vous n'avez besoin que d'un seul modèle. [Réutiliser](./loading#reusing-models-in-multiple-pipelines) 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](https://github.com/comfyanonymous/ComfyUI) ou [Automatic1111](https://github.com/AUTOMATIC1111/stable-diffusion-webui). - Plus facile de télécharger et de partager un seul fichier. Utilisez [from_single_file()](/docs/diffusers/v0.43.0/fr/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) pour charger un fichier unique. ```py 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()](/docs/diffusers/v0.43.0/fr/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) prend également en charge le passage de nouveaux modèles ou planificateurs. ```py 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()](/docs/diffusers/v0.43.0/fr/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.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. ```py 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()](/docs/diffusers/v0.43.0/fr/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file). Les exemples ci-dessous montrent comment écraser les configurations dans un pipeline ou un modèle. ```py from diffusers import StableDiffusionXLInstructPix2PixPipeline ckpt_path = "https://huggingface.co/stabilityai/cosxl/blob/main/cosxl_edit.safetensors" pipeline = StableDiffusionXLInstructPix2PixPipeline.from_single_file( ckpt_path, config="diffusers/sdxl-instructpix2pix-768", is_cosxl_edit=True ) ``` ```py from diffusers import UNet2DConditionModel ckpt_path = "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/blob/main/sd_xl_base_1.0_0.9vae.safetensors" model = UNet2DConditionModel.from_single_file(ckpt_path, upcast_attention=True) ``` ### Fichiers locaux La méthode [from_single_file()](/docs/diffusers/v0.43.0/fr/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.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](https://huggingface.co/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](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/file_download#huggingface_hub.snapshot_download) et le point de contrôle du modèle avec [hf_hub_download](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/file_download#huggingface_hub.hf_hub_download). Ces fichiers sont téléchargés dans votre [répertoire de cache](https://huggingface.co/docs/huggingface_hub/en/guides/manage-cache), mais vous pouvez les télécharger dans un répertoire spécifique avec l'argument `local_dir`. ```py 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. ```py 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()](/docs/diffusers/v0.43.0/fr/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file). ```py 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](https://hf.co/docs/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()](/docs/diffusers/v0.43.0/fr/api/pipelines/overview#diffusers.DiffusionPipeline.from_pretrained) or [from_single_file()](/docs/diffusers/v0.43.0/fr/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) to load safetensor files. ```py 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 à 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()](/docs/diffusers/v0.43.0/fr/api/loaders/lora#diffusers.loaders.FluxLoraLoaderMixin.save_lora_weights). Utilisez `transformer_lora_adapter_metadata` pour le transformeur 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. ```py 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](https://docs.python.org/3/library/pickle.html) 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()](/docs/diffusers/v0.43.0/fr/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) pour charger un fichier ckpt. ```py 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()](/docs/diffusers/v0.43.0/fr/api/loaders/single_file#diffusers.loaders.FromSingleFileMixin.from_single_file) avec [GGUFQuantizationConfig](/docs/diffusers/v0.43.0/fr/api/quantization#diffusers.GGUFQuantizationConfig). Le chargement de GGUF au niveau du pipeline n'est pas pris en charge. Consultez [GGUF](../quantization/gguf) pour les étapes d’installation et des exemples complets. ```py 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](https://github.com/huggingface/diffusers/tree/main/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. ```bash 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()](/docs/diffusers/v0.43.0/fr/api/pipelines/overview#diffusers.DiffusionPipeline.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. ```py 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](https://blog.eleuther.ai/safetensors-security-audit/).