Diffusers 文档

PEFT

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

PEFT

Diffusers 支持使用 PEFT 库加载适配器,例如 LoRA,通过 PeftAdapterMixin 类实现。这使得 Diffusers 中的模型类(如 UNet2DConditionModelSD3Transformer2DModel)能够使用适配器。

有关如何在 Diffusers 中使用 PEFT 进行推理的概述,请参阅 使用 PEFT 进行推理 教程。

PeftAdapterMixin

class diffusers.loaders.PeftAdapterMixin

< >

( )

一个包含所有用于加载和使用 PEFT 库中支持的适配器权重的函数类。有关适配器及其在基础模型中注入的更多详细信息,请查看 PEFT 文档

安装最新版本的 PEFT,并使用此混入类来

  • 在模型中附加新的适配器。
  • 附加多个适配器并迭代激活/停用它们。
  • 激活/停用模型中的所有适配器。
  • 获取活动适配器列表。

active_adapters

< >

( )

获取模型当前活动适配器列表。

如果您不熟悉适配器和 PEFT 方法,我们建议您在 PEFT 文档上了解更多信息。

add_adapter

< >

( adapter_config adapter_name: str = 'default' )

参数

  • adapter_config ([~peft.PeftConfig]) — 要添加的适配器配置;支持非前缀调优和自适应提示方法。
  • adapter_name (str, 可选, 默认为 "default") — 要添加的适配器名称。如果未传递名称,则为适配器分配默认名称。

为当前模型添加新的适配器以进行训练。如果未传递适配器名称,则为适配器分配默认名称,以遵循 PEFT 库的约定。

如果您不熟悉适配器和 PEFT 方法,我们建议您在 PEFT 文档上了解更多信息。

delete_adapters

< >

( adapter_names: typing.Union[typing.List[str], str] )

参数

  • adapter_names (Union[List[str], str]) — 要删除的适配器名称(单个字符串或字符串列表)。

从基础模型中删除适配器的 LoRA 层。

示例

from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_names="cinematic"
)
pipeline.unet.delete_adapters("cinematic")

disable_adapters

< >

( )

禁用附加到模型的所有适配器,并仅回退到使用基础模型进行推理。

如果您不熟悉适配器和 PEFT 方法,我们建议您在 PEFT 文档上了解更多信息。

disable_lora

< >

( )

禁用基础模型的活动 LoRA 层。

示例

from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.unet.disable_lora()

enable_adapters

< >

( )

启用附加到模型的适配器。模型使用 self.active_adapters() 来检索要启用的适配器列表。

如果您不熟悉适配器和 PEFT 方法,我们建议您在 PEFT 文档上了解更多信息。

enable_lora

< >

( )

启用基础模型的活动 LoRA 层。

示例

from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.unet.enable_lora()

enable_lora_hotswap

< >

( target_rank: int = 128 check_compiled: typing.Literal['error', 'warn', 'ignore'] = 'error' )

参数

  • target_rank (int, 可选, 默认为 128) — 所有将要加载的适配器中最高的秩。
  • check_compiled (str, 可选, 默认为 "error") — 如何处理模型已编译的情况,通常应避免此情况。选项包括:

    • "error"(默认):引发错误
    • "warn":发出警告
    • "ignore":不执行任何操作

启用 LoRA 适配器的热插拔功能。

仅当热插拔适配器以及模型已编译或已加载适配器的秩不同时,才需要调用此方法。

load_lora_adapter

< >

( pretrained_model_name_or_path_or_dict prefix = 'transformer' hotswap: bool = False **kwargs )

参数

  • pretrained_model_name_or_path_or_dict (stros.PathLikedict) — 可以是以下之一:

    • 一个字符串,即托管在 Hub 上的预训练模型 *模型 ID*(例如 google/ddpm-celebahq-256)。
    • 一个 *目录* 路径(例如 ./my_model_directory),包含使用 ModelMixin.save_pretrained() 保存的模型权重。
    • 一个 torch 状态字典
  • prefix (str, 可选) — 用于过滤状态字典的前缀。
  • 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 (strbool, 可选) — 用作远程文件 HTTP bearer 授权的 token。如果为 True,则使用从 diffusers-cli login 生成的 token(存储在 ~/.huggingface 中)。
  • revision (str, 可选, 默认为 "main") — 要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID 或 Git 允许的任何标识符。
  • subfolder (str, 可选, 默认为 "") — Hub 或本地较大模型仓库中模型文件的子文件夹位置。
  • network_alphas (Dict[str, float]) — 用于稳定学习和防止下溢的 network alpha 值。此值与 kohya-ss 训练器脚本中的 --network_alpha 选项含义相同。请参阅 此链接
  • low_cpu_mem_usage (bool, 可选) — 通过仅加载预训练的 LoRA 权重而不初始化随机权重来加快模型加载速度。
  • hotswap — (bool, 可选) 默认为 False。是否用新加载的适配器就地替换现有(LoRA)适配器。这意味着,这将不是加载额外的适配器,而是获取现有适配器权重并将其替换为新适配器的权重。这可以更快、更节省内存。但是,热插拔的主要优点是,当模型使用 torch.compile 编译时,加载新适配器不需要重新编译模型。使用热插拔时,传入的 adapter_name 应该是已加载适配器的名称。

    如果新适配器和旧适配器具有不同的秩和/或 LoRA alpha(即缩放),您需要在加载适配器之前调用一个额外的方法:

将 LoRA 适配器加载到基础模型中。

save_lora_adapter

< >

( save_directory adapter_name: str = 'default' upcast_before_saving: bool = False safe_serialization: bool = True weight_name: typing.Optional[str] = None )

参数

  • save_directory (stros.PathLike) — 保存 LoRA 参数的目录。如果不存在,将被创建。
  • adapter_name — (str, 默认为 "default"):要序列化的适配器名称。当基础模型加载了多个适配器时非常有用。
  • upcast_before_saving (bool, 默认为 False) — 是否在序列化之前将基础模型转换为 torch.float32
  • safe_serialization (bool, 可选, 默认为 True) — 是否使用 safetensors 而不是传统的 PyTorch 方式(使用 pickle)保存模型。
  • weight_name — (str, 可选, 默认为 None):用于序列化状态字典的文件名。

保存对应于底层模型的 LoRA 参数。

set_adapter

< >

( adapter_name: typing.Union[str, typing.List[str]] )

参数

  • adapter_name (Union[str, List[str]]) — 要设置的适配器列表或单个适配器名称。

通过强制模型仅使用该适配器并禁用其他适配器来设置特定适配器。

如果您不熟悉适配器和 PEFT 方法,我们建议您在 PEFT 文档上了解更多信息。

set_adapters

< >

( adapter_names: typing.Union[typing.List[str], str] weights: typing.Union[float, typing.Dict, typing.List[float], typing.List[typing.Dict], typing.List[NoneType], NoneType] = None )

参数

  • adapter_names (List[str]str) — 要使用的适配器名称。
  • adapter_weights (Union[List[float], float], 可选) — 用于 UNet 的适配器权重。如果为 None,则所有适配器的权重均设置为 1.0

设置当前活动的适配器,以便在扩散网络(例如 unet、transformer 等)中使用。

示例

from diffusers import AutoPipelineForText2Image
import torch

pipeline = AutoPipelineForText2Image.from_pretrained(
    "stabilityai/stable-diffusion-xl-base-1.0", torch_dtype=torch.float16
).to("cuda")
pipeline.load_lora_weights(
    "jbilcke-hf/sdxl-cinematic-1", weight_name="pytorch_lora_weights.safetensors", adapter_name="cinematic"
)
pipeline.load_lora_weights("nerijs/pixel-art-xl", weight_name="pixel-art-xl.safetensors", adapter_name="pixel")
pipeline.unet.set_adapters(["cinematic", "pixel"], adapter_weights=[0.5, 0.5])
< > 在 GitHub 上更新