Diffusers documentation
Форматы моделей
Форматы моделей
Модели диффузии обычно хранятся в формате Diffusers или в формате одного файла. Файлы моделей могут быть сохранены в различных форматах, таких как safetensors или ckpt.
Format (формат) указывает на то, хранятся ли веса в структуре каталогов. File type (тип файла) описывает способ сериализации этих весов, например, в формате safetensors или 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/
В этом руководстве показано, как загружать конвейеры и модели из этих форматов и файлов.
Формат Diffusers
Формат Diffusers хранит каждую модель (UNet, transformer, text encoder) в отдельной подпапке. Раздельное хранение моделей имеет несколько преимуществ.
- Общая инициализация конвейера выполняется быстрее, так как можно загрузить только нужную модель или загрузить все модели параллельно.
- Сниженное потребление памяти, так как нет необходимости загружать все компоненты конвейера, если требуется только одна модель. Повторное использование модели, общей для нескольких конвейеров.
- Меньшие требования к хранилищу, поскольку общие модели, используемые несколькими конвейерами, загружаются только один раз.
- Гибкость при использовании новых или улучшенных моделей в конвейере.
Формат одного файла
Формат одного файла хранит все веса модели (UNet, transformer, text encoder) в одном файле. Преимущества форматов одного файла:
- Более высокая совместимость с ComfyUI или Automatic1111.
- Удобнее скачивать и передавать один файл.
Используйте from_single_file() для загрузки одного файла.
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"
)Метод from_single_file() также поддерживает передачу новых моделей или планировщиков.
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"
)Параметры конфигурации
Модели в формате Diffusers содержат в своих репозиториях файл config.json с важными атрибутами, такими как количество слоёв и заголовков внимания. Метод from_single_file() автоматически определяет подходящий конфиг из config.json. Однако в редких случаях это может не сработать, тогда следует использовать аргумент config.
Также следует использовать аргумент config, если модели в конвейере отличаются от исходной реализации или если в ней отсутствует необходимая метаданные для определения корректной конфигурации.
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")При передаче original_config с local_files_only=True Diffusers выводит компоненты пайплайна из сигнатуры класса пайплайна. Он не загружает файлы конфигурации с Hub, что позволяет избежать проблем с совместимостью при работе в автономном режиме. Этот путь менее надёжен, чем указание локального пути к модели в config, и может приводить к ошибкам. Выполните запуск один раз с local_files_only=False, чтобы конфигурации сохранились в локальном кэше, если вам понадобится доступ к ним в автономном режиме в будущем.
Переопределите конфигурации по умолчанию, передав аргументы непосредственно в from_single_file(). Примеры ниже демонстрируют, как переопределить конфигурации в конвейере или модели.
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
)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)Локальные файлы
Метод from_single_file() пытается настроить конвейер или модель, выводя тип модели из ключей в файле контрольной точки. Например, любой контрольный файл в одном файле, основанный на базовой модели Stable Diffusion XL, настраивается из stabilityai/stable-diffusion-xl-base-1.0.
Если вы работаете с локальными файлами, скачайте файлы конфигурации с помощью метода snapshot_download и контрольную точку модели с помощью hf_hub_download. Эти файлы загружаются в ваш каталог кэша, но вы можете скачать их в конкретный каталог с помощью аргумента 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
)Символическая ссылка
Если вы работаете с файловой системой, которая не поддерживает символьные ссылки, сначала скачайте файл контрольной точки в локальный каталог с помощью параметра local_dir. Использование параметра 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",
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)Передайте эти пути в from_single_file().
pipeline = StableDiffusionXLPipeline.from_single_file(
my_local_checkpoint_path, config=my_local_config_path, local_files_only=True
)Типы файлов
Модели могут храниться в нескольких форматах файлов. Safetensors — самый распространённый формат, однако на Hub или в сообществе диффузионных моделей вы можете встретить и другие форматы.
safetensors
Safetensors — это безопасный и быстрый формат файлов для надёжного хранения и загрузки тензоров. Он ограничивает размер заголовка, чтобы предотвратить определённые виды атак, поддерживает ленивую загрузку (полезно для распределённых конфигураций) и, как правило, загружается быстрее.
Diffusers по умолчанию загружает файл safetensors (обязательная зависимость), если он доступен и библиотека Safetensors установлена.
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,
)Если вы используете контрольную точку, обученную с помощью скрипта обучения Diffusers, метаданные, такие как конфигурация LoRA, сохраняются автоматически. При загрузке файла эти метаданные анализируются, чтобы LoRA была настроена корректно. Чтобы просмотреть метаданные файла safetensors, нажмите на значок 
рядом с файлом на Hub.
Сохраните метаданные адаптера LoRA для контрольных точек, которые не обучены с помощью Diffusers, передав их в save_lora_weights(). Используйте transformer_lora_adapter_metadata для трансформера и text_encoder_lora_adapter_metadata для текстового энкодера. Также необходимо передать save_directory и хотя бы один из параметров transformer_lora_layers или text_encoder_lora_layers. Этот путь поддерживается только для файлов 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
Веса старых моделей обычно сохраняются с помощью утилиты pickle из Python в файл ckpt.
Файлы pickle могут быть небезопасными, так как их можно использовать для выполнения вредоносного кода. Рекомендуется использовать файлы safetensors или конвертировать веса в формат safetensors.
Используйте from_single_file() для загрузки файла 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 хранит предварительно квантованные веса в одном файле. Diffusers загружает GGUF через модель from_single_file() с GGUFQuantizationConfig. Загрузка GGUF на уровне пайплайна не поддерживается.
См. GGUF для инструкций по установке и полных примеров.
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),
)Конвертация форматов и файлов
Diffusers предоставляет скрипты и методы для конвертации форматов и файлов, чтобы больше инструментов в экосистеме диффузии могли их использовать.
Ознакомьтесь с содержимым папки diffusers/scripts, чтобы найти скрипт конвертации. Скрипты, в именах которых в конце добавлено "to_diffusers", преобразуют модель в формат Diffusers. У каждого скрипта есть свой набор аргументов для настройки процесса конвертации. Убедитесь, что вы проверили, какие аргументы доступны.
Пример ниже преобразует модель, сохранённую в формате Diffusers, в формат одного файла. Укажите путь к модели для преобразования и место для сохранения преобразованной модели. При необходимости можно указать тип файла и тип данных для сохранения модели.
python convert_diffusers_to_original_sdxl.py --model_path path/to/model/to/convert --checkpoint_path path/to/save/model/to --use_safetensors
Метод save_pretrained() также сохраняет модель в формате Diffusers и создаёт подпапки для каждой модели. По умолчанию файлы сохраняются в формате 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")Дальнейшие шаги
- Подробнее о принятых проектных решениях и о том, почему файлы safetensor предпочтительны для сохранения и загрузки весов моделей, читайте в блоге Сafetensors: проверены на безопасность и становятся стандартом по умолчанию.