Hugging Face 的 LOGO

Diffusers 文档

IP-Adapter

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

IP-Adapter

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

请查阅 IP-Adapter 加载 指南以了解如何加载 IP-Adapter 检查点和图像，并查阅 使用 指南以了解如何使用它。

IPAdapterMixin

class diffusers.loaders.IPAdapterMixin

< >

( )

用于处理 IP 适配器的 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]) — 可以是：

    • Hub 上托管的预训练模型的模型 ID 字符串（例如 google/ddpm-celebahq-256）。
    • 包含使用 ModelMixin.save_pretrained() 保存的模型权重的目录路径（例如 ./my_model_directory）。
    • 一个 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, 可选, 如果 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 适配器权重

示例

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

SD3IPAdapterMixin

class diffusers.loaders.SD3IPAdapterMixin

< >

( )

用于处理 StableDiffusion 3 IP 适配器的 Mixin。

is_ip_adapter_active

< >

( ) → bool

返回

布尔值

当 IP-Adapter 加载且任意层的缩放比例 > 0 时为 True。

检查 IP-Adapter 是否已加载且缩放比例 > 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）。
    • 包含使用 ModelMixin.save_pretrained() 保存的模型权重的目录路径（例如 ./my_model_directory）。
    • 一个 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, 可选, 如果 torch 版本 >= 1.9.0 则默认为 True，否则为 False) — 通过仅加载预训练权重而不初始化权重来加速模型加载。这还尝试在加载模型时不超过 CPU 内存中模型大小的 1 倍（包括峰值内存）。仅支持 PyTorch >= 1.9.0。如果您使用的是旧版 PyTorch，将此参数设置为 True 将引发错误。

set_ip_adapter_scale

< >

( scale: float )

参数

  • scale (浮点数) — 要设置的 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 适配器权重。

示例

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

IPAdapterMaskProcessor

类 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 Adapter 图像遮罩的图像处理器。

下采样

< >

( 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→