diffusers/main/ru/api/models/overview.md

Модели

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

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

ModelMixin[[diffusers.ModelMixin]]

diffusers.ModelMixin[[diffusers.ModelMixin]]

diffusers.ModelMixin()

Источник

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

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

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

compile_repeated_blocks[[diffusers.ModelMixin.compile_repeated_blocks]]

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[[diffusers.ModelMixin.cuda]]

cuda(*args, **kwargs)

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

dequantize[[diffusers.ModelMixin.dequantize]]

dequantize()

Источник

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

disable_gradient_checkpointing[[diffusers.ModelMixin.disable_gradient_checkpointing]]

disable_gradient_checkpointing()

Источник

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

disable_npu_flash_attention[[diffusers.ModelMixin.disable_npu_flash_attention]]

disable_npu_flash_attention()

Источник

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

disable_xformers_memory_efficient_attention[[diffusers.ModelMixin.disable_xformers_memory_efficient_attention]]

disable_xformers_memory_efficient_attention()

Источник

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

disable_xla_flash_attention[[diffusers.ModelMixin.disable_xla_flash_attention]]

disable_xla_flash_attention()

Источник

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

enable_gradient_checkpointing[[diffusers.ModelMixin.enable_gradient_checkpointing]]

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

Источник

Параметры:

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

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

enable_group_offload[[diffusers.ModelMixin.enable_group_offload]]

enable_group_offload(onload_device: device, offload_device: device = torch.device(), offload_type: str = 'block_level', num_blocks_per_group: int | None = None, non_blocking: bool = False, use_stream: bool = False, record_stream: bool = False, low_cpu_mem_usage = False, offload_to_disk_path: str | None = None, block_modules: str | None = None, exclude_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[[diffusers.ModelMixin.enable_layerwise_casting]]

enable_layerwise_casting(storage_dtype: dtype = torch.float8_e4m3fn, compute_dtype: typing.Optional[torch.dtype] = None, skip_modules_pattern: tuple[str, ...] | None = None, skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = None, non_blocking: bool = False)

Источник

Параметры:

storage_dtype (torch.dtype) : тип данных, к которому модель должна быть приведена для хранения.

compute_dtype (torch.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 так, чтобы игнорировать слои patch embedding, positional embedding и нормализации. Это связано с тем, что эти слои, скорее всего, критичны к точности для качества. Если вы хотите изменить это поведение, вы можете установить атрибут _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[[diffusers.ModelMixin.enable_npu_flash_attention]]

enable_npu_flash_attention()

Источник

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

enable_xformers_memory_efficient_attention[[diffusers.ModelMixin.enable_xformers_memory_efficient_attention]]

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[[diffusers.ModelMixin.enable_xla_flash_attention]]

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

Источник

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

from_pretrained[[diffusers.ModelMixin.from_pretrained]]

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, необязательный) : Зеркальный источник для решения проблем с доступностью при загрузке модели в Китае. Мы не гарантируем актуальность или безопасность источника, поэтому за дополнительной информацией обращайтесь на сайт зеркала.

device_map (int | str | torch.device или dict[str, int | str | torch.device], необязательный) : Карта, указывающая, на какое устройство следует поместить каждый подмодуль. Не обязательно определять её для каждого имени параметра/буфера; как только имя модуля указано, все его подмодули будут отправлены на то же устройство. По умолчанию None, что означает загрузку модели на CPU. Примеры: py >>> 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. Подробнее о каждом варианте см. проектирование карты устройств. Также можно обратиться к документации, специфичной для 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 размера модели в оперативной памяти (включая пиковое потребление) при загрузке модели. Поддерживается только для 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', optional, по умолчанию 'False') : Отключает ли использование mmap при загрузке модели Safetensors. Этот параметр может обеспечить лучшую производительность, если модель находится на сетевом диске или жёстком диске, которые могут плохо справляться с частыми операциями перемотки, характерными для mmap.

use_flashpack (bool, необязательный, по умолчанию False) : Если установлено в True, модель загружается из весов flashpack.

flashpack_kwargs(dict[str, Any], необязательный, по умолчанию {}) : Kwargs, передаваемые в flashpack.deserialization.assign_from_file

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

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

> Для использования частных или gated models выполните вход с помощью hf > auth login. Вы также можете активировать специальный режим > "offline-mode", чтобы использовать этот метод в > среде с файрволом.

Пример:

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[[diffusers.ModelMixin.get_memory_footprint]]

get_memory_footprint(return_buffers = True)

Источник

Параметры:

return_buffers (bool, optional, по умолчанию 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[[diffusers.ModelMixin.num_parameters]]

num_parameters(only_trainable: bool = False, exclude_embeddings: bool = False)

Источник

Параметры:

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[[diffusers.ModelMixin.reset_attention_backend]]

reset_attention_backend()

Источник

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

save_pretrained[[diffusers.ModelMixin.save_pretrained]]

save_pretrained(save_directory: str | os.PathLike, is_main_process: bool = True, save_function: typing.Optional[typing.Callable] = None, safe_serialization: bool = True, variant: str | None = None, max_shard_size: int | str = '10GB', push_to_hub: bool = False, use_flashpack: bool = False, **kwargs)

Источник

Параметры:

save_directory (str или 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[[diffusers.ModelMixin.set_attention_backend]]

set_attention_backend(backend: str)

Источник

Параметры:

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

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

set_use_npu_flash_attention[[diffusers.ModelMixin.set_use_npu_flash_attention]]

set_use_npu_flash_attention(valid: bool)

Источник

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

к[[diffusers.ModelMixin.to]]

to(*args, **kwargs)

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

PushToHubMixin[[diffusers.utils.PushToHubMixin]]

diffusers.utils.PushToHubMixin[[diffusers.utils.PushToHubMixin]]

diffusers.utils.PushToHubMixin()

Источник

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

push_to_hub[[diffusers.utils.PushToHubMixin.push_to_hub]]

push_to_hub(repo_id: str, commit_message: str | None = None, private: bool | None = None, token: str | None = None, create_pr: bool = False, safe_serialization: bool = True, variant: str | None = None, subfolder: str | None = None)

Источник

Параметры:

repo_id (str) : Имя репозитория, в который вы хотите загрузить файлы модели, планировщика или конвейера. При загрузке в организацию оно должно содержать имя вашей организации. repo_id также может быть путём к локальному каталогу.

commit_message (str, необязательный) : Сообщение для коммита при выполнении push. По умолчанию "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")