Hugging Face's logo

Diffusers documentation

IP-Adapter

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

IP-Adapter

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

在 IP-Adapter 指南中，学习如何加载和使用 IP-Adapter 检查点和图像。

IPAdapterMixin

class diffusers.loaders.IPAdapterMixin

< >

( )

用于处理 IP Adapter 的 Mixin。

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 )

参数

  • 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() 保存的模型权重。
    • 一个 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 (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，可选，如果 torch 版本 >= 1.9.0 则默认为 True，否则为 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

类 diffusers.loaders.SD3IPAdapterMixin

< >

( )

用于处理 StableDiffusion 3 IP Adapters 的 Mixin。

is_ip_adapter_active

< >

( ) → bool

返回值

bool

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

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

IP-Adapter scale 用于控制图像提示词相对于文本提示词的影响程度。当该值设置为 0 时，图像上下文将不起作用。

load_ip_adapter

< >

( pretrained_model_name_or_path_or_dict: str | dict[str, torch.Tensor]weight_name: str = 'ip-adapter.safetensors'subfolder: str | None = Noneimage_encoder_folder: str | None = '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 状态字典。
    • 一个字符串，即托管在 Hub 上的预训练模型的 model 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 (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，可选，如果 torch 版本 >= 1.9.0 则默认为 True，否则为 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

类 diffusers.IPAdapterMaskProcessor

< >

( do_resize: bool = Truevae_scale_factor: int = 8resample: str = 'lanczos'do_normalize: bool = Falsedo_binarize: bool = Truedo_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 Adapter 图像蒙版的图像处理器。

下采样

< >

( mask: Tensorbatch_size: intnum_queries: intvalue_embed_dim: int ) → torch.Tensor

参数

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

返回值

torch.Tensor

下采样后的掩码张量。

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

Update on GitHub

←引导者 LoRA→