Hugging Face's logo

Diffusers documentation

IP-Adapter

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
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→