# IP-Adapter

[IP-Adapter](https://hf.co/papers/2308.06721) 是一种轻量级适配器，允许使用图像来提示扩散模型。该方法将图像特征和文本特征的交叉注意力层解耦。图像特征由图像编码器生成。

> [!TIP]
> 在 [IP-Adapter](../../using-diffusers/ip_adapter) 指南中，学习如何加载和使用 IP-Adapter 检查点和图像。

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

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

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

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L54)

用于处理 IP Adapter 的 Mixin。

#### 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/v0.43.0/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]`) : 可以是以下之一： - 一个字符串，即托管在 Hub 上的预训练模型的 *model id*（例如 `google/ddpm-celebahq-256`）。 - 一个指向 *目录* 的路径（例如 `./my_model_directory`），其中包含使用 [ModelMixin.save_pretrained()](/docs/diffusers/v0.43.0/zh/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`) : 图像编码器在 Hub 或本地较大模型仓库中的子文件夹位置。传入 `None` 以不加载图像编码器。如果图像编码器位于 `subfolder` 内的某个文件夹中，您只需传入包含图像编码器权重的文件夹名称，例如 `image_encoder_folder="image_encoder"`。如果图像编码器位于 `subfolder` 以外的文件夹中，您应传入包含图像编码器权重的文件夹路径，例如 `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 承载者授权令牌。如果为 `True`，则使用由 `diffusers-cli login` 生成的令牌（存储在 `~/.huggingface` 中）。

revision (`str`，*可选*，默认为 `"main"`)：要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID，或 Git 允许的任何标识符。

low_cpu_mem_usage (`bool`，*可选*，如果 torch 版本 >= 1.9.0 则默认为 `True`，否则为 `False`)：通过仅加载预训练权重而不初始化权重来加速模型加载。加载模型时，此参数还尝试将 CPU 内存使用量（包括峰值内存）控制在不超过 1 倍模型大小。仅支持 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/v0.43.0/src/diffusers/loaders/ip_adapter.py#L252)

按 Transformer 块设置 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/v0.43.0/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/v0.43.0/src/diffusers/loaders/ip_adapter.py#L885)

用于处理 StableDiffusion 3 IP Adapters 的 Mixin。

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

```python
is_ip_adapter_active()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/loaders/ip_adapter.py#L888)

**返回：** `bool`

当 IP-Adapter 已加载且任意层的 scale > 0 时为 True。

检查 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/v0.43.0/src/diffusers/loaders/ip_adapter.py#L906)

**参数：**

pretrained_model_name_or_path_or_dict (`str` 或 `os.PathLike` 或 `dict`) : 可以是以下之一： - 一个字符串，即托管在 Hub 上的预训练模型的 *model id*（例如 `google/ddpm-celebahq-256`）。 - 一个 *目录* 的路径（例如 `./my_model_directory`），其中包含使用 [ModelMixin.save_pretrained()](/docs/diffusers/v0.43.0/zh/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`) : 图像编码器在 Hub 或本地较大模型仓库中的子文件夹位置。传入 `None` 以不加载图像编码器。如果图像编码器位于 `subfolder` 内的某个文件夹中，您只需传入包含图像编码器权重的文件夹名称，例如 `image_encoder_folder="image_encoder"`。如果图像编码器位于 `subfolder` 以外的文件夹中，您应传入包含图像编码器权重的文件夹路径，例如 `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 承载者授权令牌。如果为 `True`，则使用由 `diffusers-cli login` 生成的令牌（存储在 `~/.huggingface` 中）。

revision (`str`，*可选*，默认为 `"main"`)：要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID，或 Git 允许的任何标识符。

low_cpu_mem_usage (`bool`，*可选*，如果 torch 版本 >= 1.9.0 则默认为 `True`，否则为 `False`)：通过仅加载预训练权重而不初始化权重来加速模型加载。加载模型时，此参数还尝试将 CPU 内存使用量（包括峰值内存）控制在不超过 1 倍模型大小。仅支持 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/v0.43.0/src/diffusers/loaders/ip_adapter.py#L1054)

**参数：**

scale (float) : 要设置的 IP-Adapter 缩放比例。

设置 IP-Adapter 的 scale，用于控制图像提示的条件强度。值为 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/v0.43.0/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/v0.43.0/src/diffusers/image_processor.py#L1277)

**参数：**

do_resize (`bool`，*可选*，默认为 `True`)：是否将图像的 (height, width) 维度缩小为 `vae_scale_factor` 的整数倍。

vae_scale_factor (`int`，*可选*，默认为 `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 图像蒙版的图像处理器。

#### 下采样[[diffusers.IPAdapterMaskProcessor.downsample]]

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

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/image_processor.py#L1318)

**参数：**

mask (`torch.Tensor`) : 使用 `IPAdapterMaskProcessor.preprocess()` 生成的输入掩码张量。

batch_size (`int`) : 批次大小。

num_queries (`int`) : 查询的数量。

value_embed_dim (`int`)：值嵌入的维度。

**返回：** `torch.Tensor`

下采样后的掩码张量。

将提供的掩码张量下采样，以匹配缩放点积注意力所需的预期维度。如果掩码的宽高比与输出图像的宽高比不匹配，则会发出警告。