Diffusers documentation

Модели

Diffusers

Начало работы

Diffusers Установка Быстрый старт Интерфейс командной строки

Вывод

Использование конвейеров диффузии

Адаптеры и персонализация

Оптимизация и масштабирование

Базовая производительность

Скорость и память

Распределённый вывод

Квантование

Ускорение для конкретного оборудования

Методы сообщества

Модульные Diffusers

Обучение и дообучение

Ресурсы

Внести вклад

API

Основные классы

Модульный

Загрузчики

Модели

Обзор AutoModel

ControlNets

Transformers

UNets

VAE

Конвейеры

Планировщики

Внутренние классы

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Модели

🤗 Diffusers предоставляет предобученные модели для популярных алгоритмов и модули для создания собственных диффузионных систем. Основная функция моделей — устранение шума из входного примера в соответствии с распределением $p_{\theta}(x_{t-1}|x_{t})$ .

Все модели создаются на основе базового класса ModelMixin, который является torch.nn.Module и обеспечивает базовые функции сохранения и загрузки моделей, как локально, так и из Hugging Face Hub.

ModelMixin

класс diffusers.ModelMixin

( )

Базовый класс для всех моделей.

ModelMixin отвечает за сохранение конфигурации модели и предоставляет методы для загрузки, скачивания и сохранения моделей.

config_name (str) — Имя файла, в который сохраняется модель при вызове save_pretrained().

compile_repeated_blocks

( *args**kwargs )

Компилирует только часто повторяющиеся подмодули модели (например, слои Transformer), а не всю модель целиком. Этот подход, часто называемый региональной компиляцией (см. рецепт PyTorch https://docs.pytorch.org/tutorials/recipes/regional_compilation.html), может существенно сократить общее время компиляции, сохраняя при этом ускорение времени выполнения, ожидаемое от полной torch.compile.

Набор подмодулей для компиляции определяется наличием атрибута _repeated_blocks в определении модели. Определите этот атрибут в вашем подклассе модели как список/кортеж имён классов (строки). Будут скомпилированы все модули, имя класса которых совпадает.

После обнаружения каждый подходящий подмодуль компилируется путём вызова submodule.compile(*args, **kwargs). Любые позиционные или именованные аргументы, переданные в compile_repeated_blocks, передаются без изменений в torch.compile.

cuda

( *args**kwargs )

Мок-значение для пути с точками (например, torch.float32): цепочки доступа к атрибутам и вызовы работают как пропускные декораторы, repr возвращает путь с точками, а использование в качестве базового класса подставляет обычный базовый класс type (PEP 560 __mro_entries__), благодаря чему реальные дочерние классы сохраняют обычный метакласс, а inspect.signature читает их реальный __init__, а не мок-объект.

dequantize

( )

При необходимости выполнить декуантизацию модели, если она была квантована методом квантования, поддерживающим декуантизацию.

disable_gradient_checkpointing

( )

Отключает контрольные точки градиентов для текущей модели (в других фреймворках может называться activation checkpointing или checkpoint activations).

disable_npu_flash_attention

( )

отключить npu flash attention из torch_npu

disable_xformers_memory_efficient_attention

( )

Отключить энергоэффективное внимание из xFormers.

disable_xla_flash_attention

( )

Отключите ядро pallals для flash attention в torch_xla.

enable_gradient_checkpointing

( gradient_checkpointing_func: typing.Optional[typing.Callable] = None )

Параметры

gradient_checkpointing_func (Callable, необязательный) — Функция, используемая для gradient checkpointing. Если None, используется функция checkpointing PyTorch по умолчанию (torch.utils.checkpoint.checkpoint).

Включает градиентный чекпоинтинг для текущей модели (в других фреймворках может называться activation checkpointing или checkpoint activations).

enable_group_offload

( onload_device: deviceoffload_device: device = torch.device()offload_type: str = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage = Falseoffload_to_disk_path: str | None = Noneblock_modules: str | None = Noneexclude_kwargs: str | None = None )

Включает групповую разгрузку для текущей модели.

См. apply_group_offloading() для получения дополнительной информации.

Пример:

>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> transformer.enable_group_offload(
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="leaf_level",
...     use_stream=True,
... )

enable_layerwise_casting

( storage_dtype: dtype = torch.float8_e4m3fncompute_dtype: typing.Optional[torch.dtype] = Noneskip_modules_pattern: tuple[str, ...] | None = Noneskip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )

Параметры

storage_dtype (torch.dtype) — dtype, к которому модель должна быть приведена для хранения.
compute_dtype (torch.dtype) — dtype, к которому следует привести веса модели во время прямого прохода.
skip_modules_pattern (tuple[str, ...], необязательный) — Список шаблонов для сопоставления с именами модулей, которые нужно пропустить в процессе послойного приведения типов. Если значение установлено в None, используются шаблоны пропуска по умолчанию для игнорирования определенных внутренних слоев модулей и слоев PEFT.
skip_modules_classes (tuple[Type[torch.nn.Module], ...], необязательный) — Список классов модулей, которые нужно пропустить при послойном приведении типов.
non_blocking (bool, необязательный, по умолчанию False) — Если True, операции приведения весов выполняются без блокировки.

Включает послойное приведение типов для текущей модели.

Послойное приведение типов (layerwise casting) — это техника, при которой веса модели приводятся к типу данных с меньшей точностью для хранения, но на лету приводятся обратно к типу данных с большей точностью для вычислений. Этот процесс может значительно уменьшить объём памяти, занимаемый весами модели, однако может привести к некоторому снижению качества результатов. Большинство потерь качества незначительны и в основном связаны с приведением типов весов в слоях нормализации и модуляции.

По умолчанию большинство моделей в diffusers устанавливают атрибут _skip_layerwise_casting_patterns так, чтобы игнорировать слои встраивания патчей, позиционного встраивания и нормализации. Это связано с тем, что эти слои, скорее всего, критичны к точности для качества. Если вы хотите изменить это поведение, вы можете установить атрибут _skip_layerwise_casting_patterns в None или вызвать apply_layerwise_casting() с пользовательскими аргументами.

Пример:

Использование enable_layerwise_casting():

>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> # Enable layerwise casting via the model, which ignores certain modules by default
>>> transformer.enable_layerwise_casting(storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16)

enable_npu_flash_attention

( )

Включить npu flash attention из torch_npu

enable_xformers_memory_efficient_attention

( attention_op: typing.Optional[typing.Callable] = None )

Параметры

attention_op (Callable, необязательный) — Заменяет оператор по умолчанию None для использования в качестве аргумента op функции memory_efficient_attention() библиотеки xFormers.

Включите энергоэффективное внимание из xFormers.

Когда эта опция включена, вы должны наблюдать меньшее потребление памяти GPU и потенциальное ускорение во время инференса. Ускорение во время обучения не гарантируется.

> ⚠️ Если включены и memory efficient attention, и sliced attention, то memory efficient attention имеет > приоритет.

Примеры:

>>> import torch
>>> from diffusers import UNet2DConditionModel
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> model = UNet2DConditionModel.from_pretrained(
...     "stabilityai/stable-diffusion-2-1", subfolder="unet", torch_dtype=torch.float16
... )
>>> model = model.to("cuda")
>>> model.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)

enable_xla_flash_attention

( partition_spec: typing.Optional[typing.Callable] = None**kwargs )

Включите ядро flash attention pallals для torch_xla.

from_pretrained

( pretrained_model_name_or_path: str | os.PathLike | None**kwargs )

Параметры

pretrained_model_name_or_path (str или os.PathLike, необязательный) — Может быть:
- Строка, идентификатор модели (например, google/ddpm-celebahq-256) предобученной модели, размещенной на Hub.
- Путь к каталогу (например, ./my_model_directory), содержащему веса модели, сохранённые с помощью save_pretrained().
cache_dir (str | os.PathLike, необязательный) — Путь к каталогу, в котором кэшируется загруженная конфигурация предобученной модели, если стандартный кэш не используется.
dtype (torch.dtype, необязательный) — Переопределяет стандартный torch.dtype и загружает модель с другим dtype.
force_download (bool, необязательный, по умолчанию False) — Следует ли принудительно (пере)скачивать веса модели и файлы конфигурации, игнорируя кэшированные версии, если они существуют.
proxies (dict[str, str], необязательный) — Словарь прокси-серверов, используемых по протоколу или конечной точке, например, {'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}. Прокси применяются при каждом запросе.
output_loading_info (bool, необязательный, по умолчанию False) — Возвращать ли также словарь, содержащий отсутствующие ключи, неожиданные ключи и сообщения об ошибках.
local_files_only(bool, необязательный, по умолчанию False) — Определяет, следует ли загружать только локальные веса модели и файлы конфигурации. Если установлено значение True, модель не будет скачана с Hub.
token (str или bool, необязательный) — Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если True, используется токен, сгенерированный командой diffusers-cli login (сохранённый в ~/.huggingface).
revision (str, необязательный, по умолчанию "main") — Конкретная версия модели, которую следует использовать. Может быть именем ветки, именем тега, идентификатором коммита или любым другим идентификатором, поддерживаемым Git.
subfolder (str, необязательный, по умолчанию "") — Расположение подпапки файла модели внутри более крупного репозитория моделей на Hub или локально.
mirror (str, optional) — Источник зеркала для решения проблем с доступностью при загрузке модели в Китае. Мы не гарантируем актуальность или безопасность источника, поэтому за дополнительной информацией обращайтесь на сайт зеркала.
device_map (int | str | torch.device или dict[str, int | str | torch.device], необязательный) — Словарь, определяющий, на какое устройство следует поместить каждый подмодуль. Не обязательно указывать его для каждого параметра/буфера; как только имя модуля указано, все его подмодули будут отправлены на то же устройство. По умолчанию None, что означает, что модель будет загружена на CPU.
Примеры:
```
>>> from diffusers import AutoModel
>>> import torch

>>> # This works.
>>> model = AutoModel.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", device_map="cuda"
... )
>>> # This also works (integer accelerator device ID).
>>> model = AutoModel.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", device_map=0
... )
>>> # Specifying a supported offloading strategy like "auto" also works.
>>> model = AutoModel.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", device_map="auto"
... )
>>> # Specifying a dictionary as `device_map` also works.
>>> model = AutoModel.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0",
...     subfolder="unet",
...     device_map={"": torch.device("cuda")},
... )
```
Установите device_map="auto", чтобы 🤗 Accelerate автоматически вычислила наиболее оптимизированную device_map. Подробнее о каждом варианте см. в разделе проектирование device map. Также вы можете обратиться к документации, специфичной для Diffusers, чтобы увидеть более конкретные примеры.
max_memory (Dict, необязательный) — Словарь с идентификаторами устройств и максимальным объемом памяти. Если не задан, по умолчанию используется максимальная доступная память для каждого GPU и доступная оперативная память CPU.
offload_folder (str или os.PathLike, необязательный) — Путь для выгрузки весов, если device_map содержит значение "disk".
offload_state_dict (bool, необязательный) — Если True, временно выгружает CPU state dict на диск, чтобы избежать нехватки оперативной памяти CPU, если вес CPU state dict + самый большой фрагмент контрольной точки не помещается. По умолчанию True, если используется выгрузка на диск.
low_cpu_mem_usage (bool, необязательный, по умолчанию True, если версия torch >= 1.9.0, иначе False) — Ускоряет загрузку модели, загружая только предобученные веса и не инициализируя их. Это также позволяет не использовать более 1x размера модели в оперативной памяти CPU (включая пиковое потребление) при загрузке модели. Поддерживается только для PyTorch >= 1.9.0. Если вы используете более старую версию PyTorch, установка этого аргумента в True вызовет ошибку.
variant (str, необязательный) — Загружает веса из файла с указанным variant, например "fp16" или "ema".
use_safetensors (bool, необязательный, по умолчанию None) — Если установлено значение None, веса safetensors загружаются, если они доступны и если библиотека safetensors установлена. Если установлено значение True, модель принудительно загружается из весов safetensors. Если установлено значение False, веса safetensors не загружаются.
disable_mmap (‘bool’, необязательный, по умолчанию ‘False’) — Определяет, следует ли отключать mmap при загрузке модели Safetensors. Этот параметр может обеспечить лучшую производительность, если модель находится на сетевом диске или жёстком диске, которые могут плохо справляться с частыми операциями перемотки, характерными для mmap.
use_flashpack (bool, необязательный, по умолчанию False) — Если установлено в True, модель загружается из весов flashpack.
flashpack_kwargs(`dict[str, Any], *optional*, defaults to {}) -- Kwargs passed to [flashpack.deserialization.assign_from_file`](https://github.com/fal-ai/flashpack/blob/f1aa91c5cd9532a3dbf5bcc707ab9b01c274b76c/src/flashpack/deserialization.py#L408-L422)

Создайте предобученную модель PyTorch на основе конфигурации предобученной модели.

Модель по умолчанию находится в режиме оценки - model.eval() - и модули dropout отключены. Для обучения модели верните её в режим обучения с помощью model.train().

> Для использования частных или модели с ограниченным доступом выполните вход с помощью hf > auth login. Также можно активировать специальный режим > «офлайн», чтобы использовать этот метод в > среде с файрволом.

Пример:

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5", subfolder="unet")

Если вы получаете сообщение об ошибке, приведённое ниже, вам необходимо дообучить веса для вашей целевой задачи:

Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.

get_memory_footprint

( return_buffers = True )

Параметры

return_buffers (bool, необязательный, по умолчанию True) — Определяет, следует ли учитывать размер тензоров буферов при вычислении объёма занимаемой памяти. Буферы — это тензоры, для которых не требуется вычисление градиентов и которые не зарегистрированы как параметры. Например, среднее значение и стандартное отклонение в слоях batch norm. См.: https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

Получить объём памяти, занимаемый моделью. Этот метод возвращает объём памяти текущей модели в байтах. Полезно для бенчмаркинга объёма памяти текущей модели и проектирования тестов. Решение вдохновлено обсуждениями в PyTorch: https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

num_parameters

( only_trainable: bool = Falseexclude_embeddings: bool = False ) → int

Параметры

only_trainable (bool, необязательный, по умолчанию False) — Возвращать ли только количество обучаемых параметров.
exclude_embeddings (bool, необязательный, по умолчанию False) — Определяет, следует ли возвращать только количество параметров, не являющихся эмбеддингами.

Возвращает

int

Количество параметров.

Получить количество (обучаемых или не являющихся эмбеддингами) параметров в модуле.

Пример:

from diffusers import UNet2DConditionModel

model_id = "stable-diffusion-v1-5/stable-diffusion-v1-5"
unet = UNet2DConditionModel.from_pretrained(model_id, subfolder="unet")
unet.num_parameters(only_trainable=True)
859520964

reset_attention_backend

( )

Сбрасывает бэкенд внимания для модели. Последующие вызовы forward будут использовать значение по умолчанию из окружения, если оно задано, или встроенное в PyTorch масштабированное внимание на основе скалярного произведения.

save_pretrained

( save_directory: str | os.PathLikeis_main_process: bool = Truesave_function: typing.Optional[typing.Callable] = Nonesafe_serialization: bool = Truevariant: str | None = Nonemax_shard_size: int | str = '10GB'push_to_hub: bool = Falseuse_flashpack: bool = False**kwargs )

Параметры

save_directory (str or os.PathLike) — Каталог для сохранения модели и файла её конфигурации. Будет создан, если не существует.
is_main_process (bool, необязательный, по умолчанию True) — Указывает, является ли процесс, вызывающий эту функцию, основным. Полезно при распределенном обучении, когда необходимо вызвать эту функцию во всех процессах. В этом случае установите is_main_process=True только в основном процессе, чтобы избежать гонок.
save_function (Callable) — Функция, используемая для сохранения словаря состояния. Полезно при распределённом обучении, когда необходимо заменить torch.save на другой метод. Может быть настроена с помощью переменной окружения DIFFUSERS_SAVE_MODE.
safe_serialization (bool, необязательный, по умолчанию True) — Определяет, сохранять ли модель с помощью safetensors или традиционным способом PyTorch с использованием pickle.
variant (str, необязательный) — Если указано, веса сохраняются в формате pytorch_model.<variant>.bin.
max_shard_size (int или str, по умолчанию "10GB") — Максимальный размер контрольной точки перед её разбиением на части. Каждая из частей будет иметь размер, меньший этого значения. Если значение указано в виде строки, оно должно состоять из цифр, за которыми следует единица измерения (например, "5GB"). Если значение указано в виде целого числа, единицей измерения являются байты. Обратите внимание, что это ограничение будет уменьшено через определённое время (начиная с октября 2024 года), чтобы пользователи могли перейти на последнюю версию diffusers. Это сделано для установления общего размера по умолчанию для этого аргумента в разных библиотеках экосистемы Hugging Face (например, transformers и accelerate).
push_to_hub (bool, необязательный, по умолчанию False) — Указывает, следует ли отправлять вашу модель в Hugging Face Hub после сохранения. Репозиторий, в который вы хотите отправить модель, можно указать с помощью repo_id (по умолчанию используется имя save_directory в вашем пространстве имён).
kwargs (dict[str, Any], необязательный) — Дополнительные именованные аргументы, передаваемые в метод push_to_hub().

Сохраните модель и файл её конфигурации в каталог, чтобы её можно было загрузить снова с помощью метода класса from_pretrained().

set_attention_backend

( backend: str )

Параметры

backend (str) — Имя задаваемого бэкенда. Должно быть одним из доступных бэкендов, определенных в AttentionBackendName. Список доступных бэкендов можно найти в diffusers.attention_dispatch.AttentionBackendName. По умолчанию используется нативное для PyTorch масштабное точечное произведение (scaled dot product attention) в качестве бэкенда.

Установите бэкенд внимания для модели.

set_use_npu_flash_attention

( valid: bool )

Установите переключатель для npu flash attention.

до

( *args**kwargs )

Мок-значение для пути с точками (например, torch.float32): цепочки доступа к атрибутам и вызовы работают как пропускные декораторы, repr возвращает путь с точками, а использование в качестве базового класса подставляет обычный базовый класс type (PEP 560 __mro_entries__), благодаря чему реальные дочерние классы сохраняют обычный метакласс, а inspect.signature читает их реальный __init__, а не мок-объект.

PushToHubMixin

класс diffusers.utils.PushToHubMixin

( )

Миксин для загрузки модели, планировщика или конвейера на Hugging Face Hub.

push_to_hub

( repo_id: strcommit_message: str | None = Noneprivate: bool | None = Nonetoken: str | None = Nonecreate_pr: bool = Falsesafe_serialization: bool = Truevariant: str | None = Nonesubfolder: str | None = None )

Параметры

repo_id (str) — Имя репозитория, в который вы хотите загрузить файлы модели, планировщика или конвейера. При загрузке в организацию оно должно содержать имя вашей организации. repo_id также может быть путём к локальному каталогу.
commit_message (str, необязательный) — Сообщение для коммита при отправке. По умолчанию "Upload {object}".
private (bool, optional) — Определяет, следует ли сделать репозиторий приватным. Если None (по умолчанию), репозиторий будет публичным, если только по умолчанию для организации не задан приватный режим. Это значение игнорируется, если репозиторий уже существует.
token (str, необязательный) — Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Токен, сгенерированный при выполнении hf auth login (хранится в ~/.huggingface).
create_pr (bool, необязательный, по умолчанию False) — Создавать ли PR с загруженными файлами или коммитить изменения напрямую.
safe_serialization (bool, необязательный, по умолчанию True) — Определяет, следует ли преобразовать веса модели в формат safetensors.
variant (str, необязательный) — Если указано, веса сохраняются в формате pytorch_model.<variant>.bin.

Загрузите файлы модели, планировщика или конвейера в 🤗 Hugging Face Hub.

Примеры:

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-2", subfolder="unet")

# Push the `unet` to your namespace with the name "my-finetuned-unet".
unet.push_to_hub("my-finetuned-unet")

# Push the `unet` to an organization with the name "my-finetuned-unet".
unet.push_to_hub("your-org/my-finetuned-unet")

Update on GitHub

←PEFT AutoModel→