Buckets:

hf-doc-build
/

doc

Files
xet
hf-doc-build/doc / diffusers /main /ru /api /modular_diffusers /pipeline_components.md
mishig
7 days ago
preview code
download
raw
21.9 kB
# Компоненты и конфигурации

## ComponentSpec[[diffusers.ComponentSpec]]

#### diffusers.ComponentSpec[[diffusers.ComponentSpec]]

```python
diffusers.ComponentSpec(name: str | None = None, type_hint: typing.Optional[typing.Type] = None, description: str | None = None, config: diffusers.configuration_utils.FrozenDict | None = None, pretrained_model_name_or_path: str | list[str] | None = None, subfolder: str | None = '', variant: str | None = None, revision: str | None = None, default_creation_method: typing.Literal['from_config', 'from_pretrained'] = 'from_pretrained', repo: str | list[str] | None = None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L98)

**Параметры:**

name : Название компонента

type_hint : Тип компонента (например, UNet2DConditionModel)
description : Необязательное описание компонента
config : Необязательный словарь конфигурации для создания __init__
pretrained_model_name_or_path : Необязательный путь pretrained_model_name_or_path для создания с помощью from_pretrained

subfolder : Необязательная подпапка в pretrained_model_name_or_path

variant : Необязательный вариант в pretrained_model_name_or_path

revision : необязательная ревизия в pretrained_model_name_or_path

default_creation_method : предпочтительный метод создания — from_config или from_pretrained

Спецификация компонента конвейера.

Компонент можно создать двумя способами:
1. С нуля с помощью __init__ и словаря конфигурации
2. с помощью `from_pretrained`

#### create[[diffusers.ComponentSpec.create]]

```python
create(config: diffusers.configuration_utils.FrozenDict | dict[str, typing.Any] | None = None, **kwargs)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L267)

Создайте компонент с помощью from_config с конфигурацией.
#### decode_load_id[[diffusers.ComponentSpec.decode_load_id]]
```python
decode_load_id(load_id: str)
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L228)
**Параметры:**
load_id : строка load_id для декодирования, формат: "pretrained_model_name_or_path|subfolder|variant|revision", где значения None представлены как "null"
**Возвращает:**
Словарь, сопоставляющий имена полей загрузки с их значениями. Например, { "pretrained_model_name_or_path": "path/to/repo", "subfolder": "subfolder", "variant": "variant", "revision": "revision" }. Если значение сегмента равно "null", оно заменяется на None. Возвращает None, если load_id равно "null" (что указывает на то, что компонент не был создан с помощью метода `load`).
Декодировать строку load_id обратно в словарь полей и значений загрузки.
#### from_component[[diffusers.ComponentSpec.from_component]]
```python
from_component(name: str, component: Any)
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L149)
**Параметры:**
name : Название компонента
component : Объект компонента, на основе которого создаётся спецификация
**Возвращает:**
Объект ComponentSpec
**Исключения:** ``ValueError``
- ``ValueError`` -- если компонент не поддерживается (например, nn.Module без load_id, не ConfigMixin)

Создайте ComponentSpec из Component.

В настоящее время поддерживаются:
- Компоненты, созданные с помощью метода `ComponentSpec.load()`
- Компоненты, являющиеся подклассами ConfigMixin, но не nn.Modules (например, планировщики, направляющие)

#### load[[diffusers.ComponentSpec.load]]

```python
load(**kwargs)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L295)

Загрузите компонент с помощью from_pretrained.
#### loading_fields[[diffusers.ComponentSpec.loading_fields]]
```python
loading_fields()
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L209)
Возвращает имена всех полей, связанных с загрузкой (то есть тех, для которых field.metadata["loading"] равно True).
## ConfigSpec[[diffusers.ConfigSpec]]
#### diffusers.ConfigSpec[[diffusers.ConfigSpec]]
```python
diffusers.ConfigSpec(name: str, default: Any, description: str | None = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L360)
Спецификация параметра конфигурации конвейера.
## ComponentsManager[[diffusers.ComponentsManager]]
#### diffusers.ComponentsManager[[diffusers.ComponentsManager]]
```python
diffusers.ComponentsManager()
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L296)
Центральный реестр и система управления компонентами моделей в нескольких конвейерах.
[ComponentsManager](/docs/diffusers/main/ru/api/modular_diffusers/pipeline_components#diffusers.ComponentsManager) предоставляет единый способ регистрации, отслеживания и повторного использования компонентов модели (таких как UNet, VAE, текстовые энкодеры и т. д.) в различных модульных конвейерах. Он включает функции для обнаружения дубликатов, управления памятью и организации компонентов.
> [!WARNING] > Это экспериментальная функция, которая может измениться в будущем.
Пример:
```python
from diffusers import ComponentsManager

# Create a components manager
cm = ComponentsManager()

# Add components
cm.add("unet", unet_model, collection="sdxl")
cm.add("vae", vae_model, collection="sdxl")

# Enable auto offloading
cm.enable_auto_cpu_offload()
# Retrieve components
unet = cm.get_one(name="unet", collection="sdxl")
```
#### добавить[[diffusers.ComponentsManager.add]]
```python
add(name: str, component: Any, collection: str | None = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L393)
**Параметры:**
name (str) : имя компонента
component (Any) : Компонент для добавления
collection (str | None) : Коллекция, в которую нужно добавить компонент
**Возвращает:** `str`
Уникальный идентификатор компонента, который генерируется как "{name}_{id(component)}", где id(component) — это встроенный в Python уникальный идентификатор объекта
Добавьте компонент в ComponentsManager.
#### disable_auto_cpu_offload[[diffusers.ComponentsManager.disable_auto_cpu_offload]]
```python
disable_auto_cpu_offload()
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L795)
Отключите автоматическую выгрузку на CPU для всех компонентов.
#### enable_auto_cpu_offload[[diffusers.ComponentsManager.enable_auto_cpu_offload]]
```python
enable_auto_cpu_offload(device: str | int | torch.device = None, memory_reserve_margin = '3GB', offload_strategy = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L701)
**Параметры:**
device (str | int | torch.device) : Устройство выполнения, на которое модели перемещаются для прямых проходов
memory_reserve_margin (str) : Запас памяти, который следует использовать; по умолчанию — 3 ГБ. Это объём памяти, который нужно держать свободным на устройстве, чтобы избежать нехватки памяти во время выполнения модели (например, для промежуточных активаций, градиентов и т. д.).
offload_strategy : любой вызываемый объект с сигнатурой `(hooks, model_id, model, execution_device) -> hooks`, возвращающий, какие резидентные модели следует выгрузить (offload) перед загрузкой входящей. По умолчанию используется `AutoOffloadStrategy`, который освобождает наименьшую достаточную комбинацию.

Включите автоматическую выгрузку на CPU для всех компонентов.

Алгоритм работает следующим образом:
1. Все модели по умолчанию загружаются на CPU
2. Когда вызывается прямой проход модели, она перемещается на устройство выполнения
3. Если памяти недостаточно, другие модели на устройстве возвращаются на CPU
4. Система пытается выгрузить наименьшую комбинацию моделей, которая освобождает достаточно памяти
5. Модели остаются на устройстве выполнения, пока другая модель не потребует память и не вытеснит их

Модель, выгружаемая группами, участвует в этом процессе, но определяет своё расположение: она может освободить место, переместив другие модели, но никогда не перемещается, чтобы освободить место для них. Порядок не имеет значения — выгрузка группами может выполняться до или после включения этой функции. `AutoOffloadStrategy` принимает решения на основе объёма памяти, занимаемой моделями, что не отражает ситуацию, когда модель удерживает только одну группу за раз, поэтому передайте `offload_strategy`, который принимает решения на основе рабочего процесса.

#### get_components_by_ids[[diffusers.ComponentsManager.get_components_by_ids]]

```python
get_components_by_ids(ids: list[str], return_dict_with_names: bool | None = True)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1104)

**Параметры:**

ids (list[str]) : список идентификаторов компонентов

return_dict_with_names (bool | None) : Возвращать ли словарь с именами компонентов в качестве ключей:
**Возвращает:** dict[str, Any]
Словарь компонентов.
- Если return_dict_with_names=True, ключами являются имена компонентов.
- Если return_dict_with_names=False, ключами являются идентификаторы компонентов.
**Исключения:** ``ValueError``
- ``ValueError`` -- если в результатах поиска обнаружены дублирующиеся имена компонентов при return_dict_with_names=True

Получение компонентов по списку идентификаторов.

#### get_components_by_names[[diffusers.ComponentsManager.get_components_by_names]]

```python
get_components_by_names(names: list[str], collection: str | None = None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1137)

**Параметры:**

names (list[str]) : список имён компонентов

collection (str | None) : Необязательная коллекция для фильтрации

**Возвращает:** dict[str, Any]

Словарь компонентов, где ключами являются имена компонентов

**Исключения:** ``ValueError``

- ``ValueError`` -- если в результатах поиска обнаружены дублирующиеся имена компонентов

Получить компоненты по списку имен, при необходимости с фильтром по коллекции.

#### get_ids[[diffusers.ComponentsManager.get_ids]]

```python
get_ids(names: str | list[str] = None, collection: str | None = None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1086)

**Параметры:**

names (str | list[str]) : список имён компонентов

collection (str | None) : Необязательная коллекция для фильтрации

**Возвращает:** list[str]

список идентификаторов компонентов

Получить идентификаторы компонентов по списку имен, при необходимости с фильтрацией по коллекции.

#### get_model_info[[diffusers.ComponentsManager.get_model_info]]

```python
get_model_info(component_id: str, fields: str | list[str] | None = None)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L812)

**Параметры:**

component_id (str) : Имя компонента, для которого нужно получить информацию
fields (str | list[str] | None) : Поле (или поля) для возврата. Может быть строкой для одного поля или списком полей. Если None, используется настройка available_info_fields.
**Возвращает:**
Словарь, содержащий метаданные запрошенного компонента. Если указано fields, возвращаются только эти поля. В противном случае возвращаются все поля.
Получите подробную информацию о компоненте.
#### get_one[[diffusers.ComponentsManager.get_one]]
```python
get_one(component_id: str | None = None, name: str | None = None, collection: str | None = None, load_id: str | None = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L1041)
**Параметры:**
component_id (str | None) : Необязательный идентификатор компонента для получения
name (str | None) : Имя компонента или шаблон
collection (str | None) : Необязательная коллекция для фильтрации
load_id (str | None) : Необязательный load_id для фильтрации
**Возвращает:**
Один компонент
**Исключения:** ``ValueError``
- ``ValueError`` -- если ни один компонент не совпадает или совпадает несколько
Получить один компонент можно одним из способов:
- поиск по имени (совпадение по шаблону), коллекции или load_id.
- передавая component_id
Вызывает ошибку, если найдено несколько совпадающих компонентов или ни одного.
#### удалить[[diffusers.ComponentsManager.remove]]
```python
remove(component_id: str = None)
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L485)
**Параметры:**
component_id (str) : идентификатор компонента для удаления

Удалить компонент из ComponentsManager.

#### remove_from_collection[[diffusers.ComponentsManager.remove_from_collection]]

```python
remove_from_collection(component_id: str, collection: str)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L467)

Удалить компонент из коллекции.

#### search_components[[diffusers.ComponentsManager.search_components]]

```python
search_components(names: str | None = None, collection: str | None = None, load_id: str | None = None, return_dict_with_names: bool = True)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L515)

**Параметры:**

names : Имя(я) компонента или шаблон(ы) Шаблоны: - "unet" : совпадает с любым компонентом с базовым именем "unet" (например, unet_123abc) - "!unet" : все, кроме компонентов с базовым именем "unet" - "unet*" : все, у кого базовое имя начинается с "unet" - "!unet*" : все, у кого базовое имя НЕ начинается с "unet" - "*unet*" : все, у кого базовое имя содержит "unet" - "!*unet*" : все, у кого базовое имя НЕ содержит "unet" - "refiner|vae|unet" : все, у кого базовое имя точно совпадает с "refiner", "vae" или "unet" - "!refiner|vae|unet" : все, у кого базовое имя НЕ точно совпадает с "refiner", "vae" или "unet" - "unet*|vae*" : все, у кого базовое имя начинается с "unet" ИЛИ начинается с "vae"
collection : Необязательная коллекция для фильтрации
load_id : Необязательный load_id для фильтрации
return_dict_with_names : Если True, возвращает словарь с именами компонентов в качестве ключей, при обнаружении нескольких компонентов с одинаковым именем возникает ошибка. Если False, возвращает словарь с идентификаторами компонентов в качестве ключей

**Возвращает:**

Dictionary mapping component names to components if return_dict_with_names=True, or a dictionary mapping component IDs to components if return_dict_with_names=False

Ищите компоненты по имени с помощью простого сопоставления шаблонов. При необходимости фильтруйте по коллекции или load_id.
#### set_offload_strategy[[diffusers.ComponentsManager.set_offload_strategy]]
```python
set_offload_strategy(offload_strategy)
```
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/components_manager.py#L779)
**Параметры:**
offload_strategy : любой вызываемый объект с сигнатурой `(hooks, model_id, model, execution_device) -> hooks`: он получает хуки моделей, находящихся на устройстве, и возвращает те, которые нужно выгрузить перед загрузкой входящей модели. По умолчанию используется `AutoOffloadStrategy`, который освобождает наименьшую достаточную комбинацию.
Замените стратегию offload для всех управляемых моделей. Действительно только при включённом автоматическом offloading на CPU.
## InsertableDict[[diffusers.modular_pipelines.InsertableDict]]
#### diffusers.modular_pipelines.InsertableDict[[diffusers.modular_pipelines.InsertableDict]]
[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py#L60)
Xet Storage Details

Size:: 21.9 kB
Xet hash:: 1dbec4b61793ffdc78244a54efaa74088b053e916d76d6d7bc8ce949e4a03971
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.