Hugging Face's logo

Diffusers documentation

Утилиты

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Утилиты

Вспомогательные и служебные функции для работы с 🤗 Diffusers.

numpy_to_pil

diffusers.utils.numpy_to_pil

< >

( images )

Преобразование изображения numpy или пакета изображений в изображение PIL.

pt_to_pil

diffusers.utils.pt_to_pil

< >

( images )

Преобразование изображения torch в изображение PIL.

load_image

diffusers.utils.load_image

< >

( image: str | PIL.Image.Imageconvert_method: typing.Optional[typing.Callable[[PIL.Image.Image], PIL.Image.Image]] = None ) → PIL.Image.Image

Параметры

  • image (str или PIL.Image.Image) — Изображение, которое нужно преобразовать в формат PIL Image.
  • convert_method (Callable[[PIL.Image.Image], PIL.Image.Image], optional) — Метод преобразования, применяемый к изображению после его загрузки. Если установлено значение None, изображение будет преобразовано в «RGB».

Возвращает

PIL.Image.Image

Изображение PIL.

Загружает image в изображение PIL.

load_video

diffusers.utils.load_video

< >

( video: strconvert_method: typing.Optional[typing.Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]]] = Nonereturn_fps: bool = False ) → list[PIL.Image.Image] or tuple[list[PIL.Image.Image], float]

Параметры

  • video (str) — URL или путь к видео для преобразования в список изображений в формате PIL Image.
  • convert_method (Callable[[list[PIL.Image.Image]], list[PIL.Image.Image]], optional) — Метод преобразования, применяемый к видео после его загрузки. Если установлено значение None, изображения будут преобразованы в формат «RGB».
  • return_fps (bool, необязательный, по умолчанию False) — Следует ли также возвращать частоту кадров, с которой было закодировано видео. Требуется для конвейеров, которые пересэмплируют входные данные до частоты кадров, с которой работает их модель, поскольку список кадров не содержит этой информации.

Возвращает

list[PIL.Image.Image] или tuple[list[PIL.Image.Image], float]

Видео в виде списка изображений PIL, а также частота кадров, если задан параметр return_fps.

Загружает video в список изображений PIL.

export_to_gif

diffusers.utils.export_to_gif

< >

( image: list[PIL.Image.Image]output_gif_path: str = Nonefps: int = 10 )

export_to_video

diffusers.utils.export_to_video

< >

( video_frames: list[np.ndarray] | list[PIL.Image.Image]output_video_path: str = Nonefps: int = 10quality: float = 5.0bitrate: int | None = Nonemacro_block_size: int | None = 16 )

quality: Качество видеовыхода. По умолчанию 5. Используется переменная битрейт. Максимальное качество — 10, минимальное — 0. Установите None, чтобы не передавать флаги переменной битрейт в FFMPEG, что позволит указать их вручную с помощью output_params. Указание фиксированного битрейта с помощью bitrate отключает этот параметр.

bitrate: Устанавливает постоянную скорость кодирования видео. По умолчанию значение None, в этом случае используется параметр quality. Использование параметра переменной скорости quality позволяет получить видео лучшего качества при меньшем размере файла, чем при задании фиксированной скорости с помощью этого параметра.

macro_block_size: Ограничение размера для видео. Ширина и высота должны делиться на это число. Если они не делятся на это число, imageio укажет ffmpeg масштабировать изображение до ближайшего размера, делящегося на это число. Большинство кодеков совместимы с размером макроблока 16 (по умолчанию), некоторые поддерживают меньшие значения (4, 8). Чтобы отключить эту автоматическую функцию, установите значение None или 1, однако имейте в виду, что многие плееры не могут декодировать видео с нечётным размером, а некоторые кодеки могут выдавать низкое качество или не работать. См. https://en.wikipedia.org/wiki/Macroblock.

encode_video

diffusers.utils.encode_video

< >

( video: list[PIL.Image.Image] | np.ndarray | 'torch.Tensor' | Iterator['torch.Tensor']fps: intoutput_path: straudio: 'torch.Tensor' | None = Noneaudio_sample_rate: int | None = Nonevideo_chunks_number: int = 1 )

Параметры

  • video (List[PIL.Image.Image] или np.ndarray или torch.Tensor) — Тензор видео с формой [frames, height, width, channels] и целочисленными значениями пикселей в диапазоне [0, 255]. Если входные данные представлены в виде np.ndarray, ожидается, что это будет массив с плавающей точкой со значениями в диапазоне [0, 1] (именно такой формат обычно возвращают пайплайны при output_type="np").
  • fps (int) — Количество кадров в секунду (FPS) закодированного видео.
  • output_path (str) — Путь для сохранения закодированного видео.
  • audio (torch.Tensor, необязательный) — Аудиосигнал с формой [audio_channels, samples].
  • audio_sample_rate — (int, необязательный): Частота дискретизации аудиосигнала.
  • video_chunks_number (int, необязательный, по умолчанию 1) — Количество фрагментов, на которые видео делится для кодирования. Каждый фрагмент кодируется отдельно. Количество используемых фрагментов часто зависит от конфигурации тайлинга для видео-VAE.

Кодирует видео с необязательным аудио с использованием библиотеки PyAV. Основано на коде из оригинального репозитория LTX-2: https://github.com/Lightricks/LTX-2/blob/4f410820b198e05074a1e92de793e3b59e9ab5a0/packages/ltx-pipelines/src/ltx_pipelines/utils/media_io.py#L182

make_image_grid

diffusers.utils.make_image_grid

< >

( images: listrows: intcols: intresize: int = None )

Готовит единую сетку изображений. Полезно для целей визуализации.

randn_tensor

diffusers.utils.torch_utils.randn_tensor

< >

( shape: tuple | listgenerator: list['torch.Generator'] | 'torch.Generator' | None = Nonedevice: str | 'torch.device' | None = Nonedtype: 'torch.dtype' | None = Nonelayout: 'torch.layout' | None = None )

Вспомогательная функция для создания случайных тензоров на нужном device с нужным dtype. При передаче списка генераторов можно задать отдельный seed для каждого размера батча. Если переданы генераторы для CPU, тензор всегда создаётся на CPU.

TorchDeviceBackend

класс diffusers.utils.torch_utils.TorchDeviceBackend

< >

( device: str | torch.device | None = None )

Прокси для пространства имён torch.<backend> (torch.cuda, torch.xpu, torch.mps, …) одного устройства. Атрибуты, которые класс не определяет, принадлежат самому модулю (synchronize, device_count, Stream, current_stream, …); методы, определённые здесь, переопределяют операции, доступность которых различается между бэкендами и для которых требуется запасной вариант: очистка кэша, установка seed и запросы о памяти. Если device не указан, ускоритель хоста определяется через torch.accelerator. Если у torch нет модуля для данного бэкенда, возникает исключение, а не происходит тихого переключения на torch.cuda.

max_memory_allocated

< >

( )

Пиковый объём памяти, выделенной на устройстве в байтах с момента последнего сброса; 0, если бэкенд не ведёт статистику.

mem_get_info

< >

( )

Свободная и общая память устройства в байтах.

apply_layerwise_casting

diffusers.hooks.apply_layerwise_casting

< >

( module: Modulestorage_dtype: dtypecompute_dtype: dtypeskip_modules_pattern: str | tuple[str, ...] = 'auto'skip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )

Параметры

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

Применяет послойное приведение типов к заданному модулю. Ожидаемым модулем здесь является Diffusers ModelMixin, но это может быть любой nn.Module, использующий слои diffusers или примитивы pytorch.

Пример:

>>> import torch
>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     model_id, subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> apply_layerwise_casting(
...     transformer,
...     storage_dtype=torch.float8_e4m3fn,
...     compute_dtype=torch.bfloat16,
...     skip_modules_pattern=["patch_embed", "norm", "proj_out"],
...     non_blocking=True,
... )

apply_group_offloading

diffusers.hooks.apply_group_offloading

< >

( module: Moduleonload_device: typing.Union[str, torch.device]offload_device: typing.Union[str, torch.device] = torch.device()offload_type: str | diffusers.hooks.group_offloading.GroupOffloadingType = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage: bool = Falseoffload_to_disk_path: str | None = Noneblock_modules: list[str] | None = Noneexclude_kwargs: list[str] | None = None )

Параметры

  • module (torch.nn.Module) — Модуль, к которому применяется групповая разгрузка.
  • onload_device (torch.device) — Устройство, на которое загружается группа модулей.
  • offload_device (torch.device, по умолчанию torch.device("cpu")) — Устройство, на которое выгружается группа модулей. Обычно это CPU. По умолчанию — CPU.
  • offload_type (str или GroupOffloadingType, по умолчанию “block_level”) — Тип применяемого offloading. Может быть “block_level” или “leaf_level”. По умолчанию — “block_level”.
  • offload_to_disk_path (str, необязательный, по умолчанию None) — Путь к каталогу, в который будут выгружаться параметры. Установка этого параметра может быть полезна в условиях ограниченной оперативной памяти, когда требуется разумный компромисс между скоростью и потреблением памяти.
  • num_blocks_per_group (int, необязательный) — Количество блоков в группе при использовании offload_type=“block_level”. Это значение обязательно при использовании offload_type=“block_level”.
  • non_blocking (bool, по умолчанию False) — Если True, выгрузка и загрузка данных выполняются с неблокирующей передачей.
  • use_stream (bool, по умолчанию False) — Если True, выгрузка и загрузка данных выполняются асинхронно с использованием CUDA-потока. Это может быть полезно для перекрытия вычислений и передачи данных.
  • record_stream (bool, по умолчанию False) — при включении вместе с use_stream помечает текущий тензор как использованный этим потоком. Работает быстрее, но требует немного больше памяти. Подробности см. в официальной документации PyTorch.
  • low_cpu_mem_usage (bool, по умолчанию False) — Если True, использование памяти CPU минимизируется за счёт закрепления тензоров на лету, а не их предварительного закрепления. Этот параметр имеет значение только при использовании потоковой разгрузки на CPU (т. е. use_stream=True). Это может быть полезно, когда память CPU является узким местом, но может нивелировать преимущества использования потоков.
  • block_modules (list[str], необязательный) — Список имён модулей, которые следует рассматривать как блоки для offloading. Если указан, для offloading на уровне блоков будут учитываться только эти модули. Если не указан, будет использоваться логика обнаружения блоков по умолчанию.
  • exclude_kwargs (list[str], необязательный) — Список ключей аргументов keyword, которые не должны обрабатываться send_to_device. Это полезно для изменяемого состояния, такого как списки кэша, которые должны сохранять идентичность объектов между проходами forward. Если не указано, значение будет выведено из атрибута _skip_keys модуля, если он существует.

Применяет групповую разгрузку (group offloading) для внутренних слоёв модуля torch.nn.Module. Чтобы понять, что такое групповая разгрузка и в каких случаях она полезна, сначала нужно дать некоторый контекст о том, как работают другие поддерживаемые методы разгрузки.

Как правило, выгрузка выполняется на двух уровнях:

  • На уровне модуля: в Diffusers это можно включить с помощью метода ModelMixin::enable_model_cpu_offload(). Он работает за счёт выгрузки каждого компонента пайплайна на CPU для хранения и загрузки на устройство ускорителя по мере необходимости для вычислений. Этот метод более эффективен с точки зрения памяти, чем хранение всех компонентов на ускорителе, однако требования к памяти всё ещё остаются довольно высокими. Для работы этого метода необходимо иметь объём памяти, эквивалентный размеру модели в рабочем типе данных (runtime dtype) + размеру крупнейших промежуточных тензоров активаций, чтобы завершить прямой проход (forward pass).
  • Уровень листьев: в Diffusers это можно включить с помощью метода ModelMixin::enable_sequential_cpu_offload(). Он работает за счёт выгрузки параметров нижнего уровня (листьев) вычислительного графа на CPU для хранения и загрузки только этих листьев на устройство ускорителя для вычислений. Этот вариант использует минимальное количество памяти ускорителя, но может работать медленнее из-за избыточного числа синхронизаций устройств.

Групповое выгружение представляет собой промежуточный вариант между двумя методами. Оно работает путём выгрузки групп внутренних слоёв (либо torch.nn.ModuleList, либо torch.nn.Sequential). Этот метод потребляет меньше памяти, чем выгружение на уровне модулей. Он также быстрее, чем выгружение на уровне листьев/последовательное выгружение, поскольку количество синхронизаций устройств снижается.

Ещё одна поддерживаемая функция (для CUDA-устройств с поддержкой потоков асинхронной передачи данных) — возможность перекрывать передачу данных и вычисления, чтобы сократить общее время выполнения по сравнению с последовательным offloading. Это реализуется с помощью предварительной загрузки слоёв (layer prefetching) с использованием потоков: следующий к выполнению слой начинает onloading на ускорительное устройство, пока выполняется текущий слой, — это немного увеличивает требования к памяти. Обратите внимание, что данная реализация также поддерживает offloading на уровне листьев (leaf-level), однако при использовании потоков она может стать значительно быстрее.

Пример:

>>> from diffusers import CogVideoXTransformer3DModel
>>> from diffusers.hooks import apply_group_offloading

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

>>> apply_group_offloading(
...     transformer,
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="block_level",
...     num_blocks_per_group=2,
...     use_stream=True,
... )
Update on GitHub

←Пользовательские слои нормализации Обработчик изображений VAE→