Diffusers 文档
PEFT
并获得增强的文档体验
开始使用
PEFT
Diffusers 支持使用 PEFT 库加载适配器,例如 LoRA,通过 PeftAdapterMixin 类实现。这使得 Diffusers 中的模型类(如 UNet2DConditionModel、SD3Transformer2DModel)能够使用适配器。
有关如何在 Diffusers 中使用 PEFT 进行推理的概述,请参阅 使用 PEFT 进行推理 教程。
PeftAdapterMixin
一个包含所有用于加载和使用 PEFT 库中支持的适配器权重的函数类。有关适配器及其在基础模型中注入的更多详细信息,请查看 PEFT 文档。
安装最新版本的 PEFT,并使用此混入类来
- 在模型中附加新的适配器。
- 附加多个适配器并迭代激活/停用它们。
- 激活/停用模型中的所有适配器。
- 获取活动适配器列表。
add_adapter
< 来源 >( adapter_config adapter_name: str = 'default' )
为当前模型添加新的适配器以进行训练。如果未传递适配器名称,则为适配器分配默认名称,以遵循 PEFT 库的约定。
如果您不熟悉适配器和 PEFT 方法,我们建议您在 PEFT 文档上了解更多信息。
delete_adapters
< 来源 >( adapter_names: typing.Union[typing.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")
禁用附加到模型的所有适配器,并仅回退到使用基础模型进行推理。
如果您不熟悉适配器和 PEFT 方法,我们建议您在 PEFT 文档上了解更多信息。
禁用基础模型的活动 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()
启用附加到模型的适配器。模型使用 self.active_adapters()
来检索要启用的适配器列表。
如果您不熟悉适配器和 PEFT 方法,我们建议您在 PEFT 文档上了解更多信息。
启用基础模型的活动 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' )
启用 LoRA 适配器的热插拔功能。
仅当热插拔适配器以及模型已编译或已加载适配器的秩不同时,才需要调用此方法。
load_lora_adapter
< 来源 >( pretrained_model_name_or_path_or_dict prefix = 'transformer' hotswap: bool = False **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 上的预训练模型 *模型 ID*(例如
- 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 (
str
或 bool, 可选) — 用作远程文件 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 (
str
或os.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
< source >( adapter_name: typing.Union[str, typing.List[str]] )
通过强制模型仅使用该适配器并禁用其他适配器来设置特定适配器。
如果您不熟悉适配器和 PEFT 方法,我们建议您在 PEFT 文档上了解更多信息。
set_adapters
< source >( 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 )
设置当前活动的适配器,以便在扩散网络(例如 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])