# IP-Adapter

[IP-Adapter](https://hf.co/papers/2308.06721) — это лёгкий адаптер, позволяющий использовать изображение в качестве промпта для диффузионной модели. Этот метод разделяет слои кросс-внимания для признаков изображения и текста. Признаки изображения генерируются с помощью энкодера изображений.

> [!TIP]
> Узнайте, как загрузить и использовать контрольную точку и изображение IP-Adapter в руководстве [IP-Adapter](../../using-diffusers/ip_adapter).

## IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

#### diffusers.loaders.IPAdapterMixin[[diffusers.loaders.IPAdapterMixin]]

```python
diffusers.loaders.IPAdapterMixin()
```

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

Миксин для работы с IP-адаптерами.

#### load_ip_adapter[[diffusers.loaders.IPAdapterMixin.load_ip_adapter]]

```python
load_ip_adapter(pretrained_model_name_or_path_or_dict: str | list[str] | dict[str, torch.Tensor], subfolder: str | list[str], weight_name: str | list[str], image_encoder_folder: str | None = 'image_encoder', **kwargs)
```

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

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

pretrained_model_name_or_path_or_dict (`str` или `list[str]` или `os.PathLike` или `list[os.PathLike]` или `dict` или `list[dict]`) : Может быть одним из следующих:  - строка, *model id* (например, `google/ddpm-celebahq-256`) предобученной модели, размещенной на Hub. - путь к *каталогу* (например, `./my_model_directory`), содержащему веса модели, сохраненные с помощью [ModelMixin.save_pretrained()](/docs/diffusers/main/ru/api/models/overview#diffusers.ModelMixin.save_pretrained). - [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

subfolder (`str` или `list[str]`) : Путь к подпапке, в которой находится файл модели в более крупном репозитории моделей на Hub или локально. Если передан список, его длина должна совпадать с длиной `weight_name`.

weight_name (`str` или `list[str]`) : Имя файла весов для загрузки. Если передан список, его длина должна совпадать с длиной `subfolder`.

image_encoder_folder (`str`, *необязательный*, по умолчанию `image_encoder`) : Путь к подпапке с image encoder внутри более крупной модели на Hub или локально. Передайте `None`, чтобы не загружать image encoder. Если image encoder находится в папке внутри `subfolder`, достаточно передать имя папки, содержащей веса image encoder, например, `image_encoder_folder="image_encoder"`. Если image encoder находится в папке, отличной от `subfolder`, следует передать путь к папке, содержащей веса image encoder, например, `image_encoder_folder="different_subfolder/image_encoder"`.

cache_dir (`str | os.PathLike`, *необязательный*) : Путь к каталогу, в котором кэшируется конфигурация загруженной предобученной модели, если стандартный кэш не используется.

force_download (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли принудительно (пере)скачивать веса модели и файлы конфигурации, заменяя кэшированные версии, если они существуют.

proxies (`dict[str, str]`, *необязательный*) : Словарь прокси-серверов для использования по протоколу или конечной точке, например, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Прокси используются при каждом запросе.

local_files_only (`bool`, *необязательный*, по умолчанию `False`) : Загружать только локальные веса модели и файлы конфигурации или нет. Если установлено в `True`, модель не будет скачана с Hub.

token (`str` или *bool*, *необязательный*) : Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если `True`, используется токен, сгенерированный командой `diffusers-cli login` (сохранённый в `~/.huggingface`).

revision (`str`, *необязательный*, по умолчанию `"main"`) : Конкретная версия модели, которую следует использовать. Может быть именем ветки, именем тега, идентификатором коммита или любым другим идентификатором, поддерживаемым Git.

low_cpu_mem_usage (`bool`, *необязательный*, по умолчанию `True`, если версия torch >= 1.9.0, иначе `False`) : Ускоряет загрузку модели, загружая только предобученные веса и не инициализируя их. Также это позволяет не использовать больше 1x размера модели в оперативной памяти (включая пиковое потребление) при загрузке модели. Поддерживается только для PyTorch >= 1.9.0. Если вы используете более старую версию PyTorch, установка этого аргумента в `True` вызовет ошибку.

#### set_ip_adapter_scale[[diffusers.loaders.IPAdapterMixin.set_ip_adapter_scale]]

```python
set_ip_adapter_scale(scale)
```

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

Устанавливает масштабы IP-Adapter для каждого блока трансформера. Входной параметр `scale` может быть одиночной конфигурацией или списком конфигураций для детального управления поведением каждого IP-Adapter. Конфигурация может быть числом с плавающей точкой или словарем.

Пример:

```py
# To use original IP-Adapter
scale = 1.0
pipeline.set_ip_adapter_scale(scale)

# To use style block only
scale = {
    "up": {"block_0": [0.0, 1.0, 0.0]},
}
pipeline.set_ip_adapter_scale(scale)

# To use style+layout blocks
scale = {
    "down": {"block_2": [0.0, 1.0]},
    "up": {"block_0": [0.0, 1.0, 0.0]},
}
pipeline.set_ip_adapter_scale(scale)

# To use style and layout from 2 reference images
scales = [{"down": {"block_2": [0.0, 1.0]}}, {"up": {"block_0": [0.0, 1.0, 0.0]}}]
pipeline.set_ip_adapter_scale(scales)
```

#### unload_ip_adapter[[diffusers.loaders.IPAdapterMixin.unload_ip_adapter]]

```python
unload_ip_adapter()
```

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

Разгружает веса IP Adapter

Примеры:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.unload_ip_adapter()
>>> ...
```

## SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

#### diffusers.loaders.SD3IPAdapterMixin[[diffusers.loaders.SD3IPAdapterMixin]]

```python
diffusers.loaders.SD3IPAdapterMixin()
```

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

Миксин для работы с IP-адаптерами StableDiffusion 3.

#### is_ip_adapter_active[[diffusers.loaders.SD3IPAdapterMixin.is_ip_adapter_active]]

```python
is_ip_adapter_active()
```

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

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

Истина, если IP-Adapter загружен и у любого слоя scale > 0.

Проверяет, загружен ли IP-Adapter и что scale > 0.

IP-Adapter scale управляет влиянием изображения-промпта по сравнению с текстовым промптом. Если это значение установлено в 0, контекст изображения не имеет значения.

#### load_ip_adapter[[diffusers.loaders.SD3IPAdapterMixin.load_ip_adapter]]

```python
load_ip_adapter(pretrained_model_name_or_path_or_dict: str | dict[str, torch.Tensor], weight_name: str = 'ip-adapter.safetensors', subfolder: str | None = None, image_encoder_folder: str | None = 'image_encoder', **kwargs)
```

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

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

pretrained_model_name_or_path_or_dict (`str` или `os.PathLike` или `dict`) : Может быть одним из следующих: - строка, *model id* (например, `google/ddpm-celebahq-256`) предобученной модели, размещенной на Hub. - путь к *каталогу* (например, `./my_model_directory`), содержащему веса модели, сохраненные с помощью [ModelMixin.save_pretrained()](/docs/diffusers/main/ru/api/models/overview#diffusers.ModelMixin.save_pretrained). - [torch state dict](https://pytorch.org/tutorials/beginner/saving_loading_models.html#what-is-a-state-dict).

weight_name (`str`, по умолчанию "ip-adapter.safetensors") : имя файла с весами для загрузки. Если передан список, его длина должна совпадать с длиной `subfolder`.

subfolder (`str`, *необязательный*) : Путь к подпапке, в которой находится файл модели в более крупном репозитории моделей на Hub или локально. Если передан список, его длина должна совпадать с длиной `weight_name`.

image_encoder_folder (`str`, *необязательный*, по умолчанию `image_encoder`) : Путь к подпапке с image encoder внутри более крупной модели на Hub или локально. Передайте `None`, чтобы не загружать image encoder. Если image encoder находится в папке внутри `subfolder`, достаточно передать имя папки, содержащей веса image encoder, например, `image_encoder_folder="image_encoder"`. Если image encoder находится в папке, отличной от `subfolder`, следует передать путь к папке, содержащей веса image encoder, например, `image_encoder_folder="different_subfolder/image_encoder"`.

cache_dir (`str | os.PathLike`, *необязательный*) : Путь к каталогу, в котором кэшируется конфигурация загруженной предобученной модели, если стандартный кэш не используется.

force_download (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли принудительно (пере)скачивать веса модели и файлы конфигурации, заменяя кэшированные версии, если они существуют.

proxies (`dict[str, str]`, *необязательный*) : Словарь прокси-серверов для использования по протоколу или конечной точке, например, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Прокси используются при каждом запросе.

local_files_only (`bool`, *необязательный*, по умолчанию `False`) : Загружать только локальные веса модели и файлы конфигурации или нет. Если установлено в `True`, модель не будет скачана с Hub.

token (`str` или *bool*, *необязательный*) : Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если `True`, используется токен, сгенерированный командой `diffusers-cli login` (сохранённый в `~/.huggingface`).

revision (`str`, *необязательный*, по умолчанию `"main"`) : Конкретная версия модели, которую следует использовать. Может быть именем ветки, именем тега, идентификатором коммита или любым другим идентификатором, поддерживаемым Git.

low_cpu_mem_usage (`bool`, *необязательный*, по умолчанию `True`, если версия torch >= 1.9.0, иначе `False`) : Ускоряет загрузку модели, загружая только предобученные веса и не инициализируя их. Также это позволяет не использовать больше 1x размера модели в оперативной памяти (включая пиковое потребление) при загрузке модели. Поддерживается только для PyTorch >= 1.9.0. Если вы используете более старую версию PyTorch, установка этого аргумента в `True` вызовет ошибку.

#### set_ip_adapter_scale[[diffusers.loaders.SD3IPAdapterMixin.set_ip_adapter_scale]]

```python
set_ip_adapter_scale(scale: float)
```

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

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

scale (float) : масштаб IP-Adapter, который нужно установить.

Установите масштаб IP-Adapter, который управляет условным формированием на основе изображения. Значение 1.0 означает, что модель обусловлена только изображением, а 0.0 — только текстовым промптом. Уменьшение этого значения побуждает модель генерировать более разнообразные изображения, однако они могут хуже соответствовать исходному изображению.

Пример:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.set_ip_adapter_scale(0.6)
>>> ...
```

#### unload_ip_adapter[[diffusers.loaders.SD3IPAdapterMixin.unload_ip_adapter]]

```python
unload_ip_adapter()
```

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

Разгружает веса IP Adapter.

Пример:

```python
>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.unload_ip_adapter()
>>> ...
```

## IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

#### diffusers.IPAdapterMaskProcessor[[diffusers.IPAdapterMaskProcessor]]

```python
diffusers.IPAdapterMaskProcessor(do_resize: bool = True, vae_scale_factor: int = 8, resample: str = 'lanczos', do_normalize: bool = False, do_binarize: bool = True, do_convert_grayscale: bool = True)
```

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

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

do_resize (`bool`, *необязательный*, по умолчанию `True`) : Указывает, следует ли масштабировать размеры изображения (высота, ширина) до кратных `vae_scale_factor`.

vae_scale_factor (`int`, *optional*, по умолчанию `8`) : масштабный коэффициент VAE. Если `do_resize` равно `True`, изображение автоматически масштабируется до кратных этого коэффициента.

resample (`str`, *необязательный*, по умолчанию `lanczos`) : Фильтр ресемплинга, используемый при изменении размера изображения.

do_normalize (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли нормализовать изображение в диапазон [-1,1].

do_binarize (`bool`, *необязательный*, по умолчанию `True`) : Бинаризовать ли изображение в 0/1.

do_convert_grayscale (`bool`, *необязательный*, по умолчанию `True`) : Преобразовать ли изображения в формат оттенков серого.

Обработчик изображений для масок изображений IP Adapter.

#### downsample[[diffusers.IPAdapterMaskProcessor.downsample]]

```python
downsample(mask: Tensor, batch_size: int, num_queries: int, value_embed_dim: int)
```

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

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

mask (`torch.Tensor`) : входной тензор маски, созданный с помощью `IPAdapterMaskProcessor.preprocess()`.

batch_size (`int`) : Размер батча.

num_queries (`int`) : Количество запросов.

value_embed_dim (`int`) : размерность векторов значений.

**Возвращает:** `torch.Tensor`

Тензор маски после уменьшения разрешения.

Уменьшает размер предоставленного тензора маски до ожидаемых размерностей для масштабированного внимания на основе скалярного произведения. Если соотношение сторон маски не совпадает с соотношением сторон выходного изображения, выводится предупреждение.