Hugging Face's logo

Diffusers 文档

IP-Adapter

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

IP-Adapter

IP-Adapter 是一种轻量级适配器，可以使用图像提示扩散模型。此方法解耦了图像和文本特征的交叉注意力层。图像特征由图像编码器生成。

了解如何在 IP-Adapter 加载 指南中加载 IP-Adapter 检查点和图像，您可以在 使用 指南中查看如何使用它。

IPAdapterMixin

class diffusers.loaders.IPAdapterMixin

< >

( )

用于处理 IP Adapters 的 Mixin。

load_ip_adapter

< >

( pretrained_model_name_or_path_or_dict: typing.Union[str, typing.List[str], typing.Dict[str, torch.Tensor]] subfolder: typing.Union[str, typing.List[str]] weight_name: typing.Union[str, typing.List[str]] image_encoder_folder: typing.Optional[str] = 'image_encoder' **kwargs )

参数

  • pretrained_model_name_or_path_or_dict (str 或 List[str] 或 os.PathLike 或 List[os.PathLike] 或 dict 或 List[dict]) — 可以是以下之一：

    • 一个字符串，预训练模型的模型 ID（例如 google/ddpm-celebahq-256），托管在 Hub 上。
    • 一个目录的路径（例如 ./my_model_directory），其中包含使用 ModelMixin.save_pretrained() 保存的模型权重。
    • 一个 torch 状态字典。
  • 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 (Union[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") — 要使用的特定模型版本。 它可以是分支名称、标签名称、提交 ID 或 Git 允许的任何标识符。
  • low_cpu_mem_usage (bool, 可选, 默认为 True 如果 torch 版本 >= 1.9.0 否则为 False) — 加速模型加载，仅加载预训练权重而不初始化权重。这还尝试在加载模型时，CPU 内存使用量（包括峰值内存）不超过 1 倍模型大小。仅支持 PyTorch >= 1.9.0。如果您使用的是旧版本的 PyTorch，则将此参数设置为 True 将引发错误。

set_ip_adapter_scale

< >

( scale )

为每个 Transformer 块设置 IP-Adapter 比例。输入 scale 可以是单个配置或配置列表，用于精细控制每个 IP-Adapter 的行为。配置可以是浮点数或字典。

示例

# 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

< >

( )

卸载 IP Adapter 权重

示例

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

SD3IPAdapterMixin

class diffusers.loaders.SD3IPAdapterMixin

< >

( )

用于处理 StableDiffusion 3 IP Adapter 的 Mixin。

is_ip_adapter_active

< >

( ) → bool

返回

bool

当 IP-Adapter 已加载且任何层级的 scale > 0 时返回 True。

检查 IP-Adapter 是否已加载且 scale > 0。

IP-Adapter 比例控制图像提示与文本提示的影响。当此值设置为 0 时，图像上下文无关紧要。

load_ip_adapter

< >

( pretrained_model_name_or_path_or_dict: typing.Union[str, typing.Dict[str, torch.Tensor]] weight_name: str = 'ip-adapter.safetensors' subfolder: typing.Optional[str] = None image_encoder_folder: typing.Optional[str] = 'image_encoder' **kwargs )

参数

  • pretrained_model_name_or_path_or_dict (str 或 os.PathLike 或 dict) — 可以是以下之一：
    • 字符串，Hub 上托管的预训练模型的模型 ID（例如 google/ddpm-celebahq-256）。
    • 目录的路径（例如 ./my_model_directory），其中包含使用 ModelMixin.save_pretrained() 保存的模型权重。
    • torch 状态字典。
  • 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 (Union[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") — 要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID 或 Git 允许的任何标识符。
  • low_cpu_mem_usage (bool, 可选, 默认为 True 如果 torch 版本 >= 1.9.0 否则为 False) — 加速模型加载，仅加载预训练权重而不初始化权重。这还尝试在加载模型时，CPU 内存使用量（包括峰值内存）不超过 1 倍模型大小。仅支持 PyTorch >= 1.9.0。如果您使用的是旧版本的 PyTorch，则将此参数设置为 True 将引发错误。

set_ip_adapter_scale

< >

( scale: float )

参数

  • scale (float) — 要设置的 IP-Adapter 比例。

设置 IP-Adapter 比例，该比例控制图像提示条件。值为 1.0 表示模型仅以图像提示为条件，而 0.0 仅以文本提示为条件。降低此值会鼓励模型生成更多样化的图像，但它们可能与图像提示不太一致。

示例

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

unload_ip_adapter

< >

( )

卸载 IP Adapter 权重。

示例

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

IPAdapterMaskProcessor

class diffusers.image_processor.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 )

参数

  • do_resize (bool, 可选, 默认为 True) — 是否将图像的（高度，宽度）尺寸缩小到 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 适配器图像掩码的图像处理器。

下采样

< >

( mask: Tensor batch_size: int num_queries: int value_embed_dim: int ) → torch.Tensor

参数

  • mask (torch.Tensor) — 使用 IPAdapterMaskProcessor.preprocess() 生成的输入掩码张量。
  • batch_size (int) — 批次大小。
  • num_queries (int) — 查询数量。
  • value_embed_dim (int) — 值嵌入的维度。

返回

torch.Tensor

下采样后的掩码张量。

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

< > 在 GitHub 上更新

←量化 LoRA→