Diffusers 文档

模型

Diffusers

加入 Hugging Face 社区

并获得增强的文档体验

在模型、数据集和 Spaces 上协作

通过加速推理获得更快的示例

切换文档主题

开始使用

模型

🤗 Diffusers 为流行的算法提供预训练模型，并提供模块以创建自定义扩散系统。模型的主要功能是去噪输入样本，如分布建模所示 $p_{\theta}(x_{t-1}|x_{t})$ .

所有模型都基于 ModelMixin 基类构建，该基类是一个 torch.nn.Module，为本地和从 Hugging Face Hub 保存和加载模型提供基本功能。

ModelMixin

class diffusers.ModelMixin

( )

所有模型的基础类。

ModelMixin 负责存储模型配置，并提供用于加载、下载和保存模型的方法。

config_name (str) — 调用 save_pretrained() 时用于保存模型的文件名。

反量化

( )

如果模型已被支持反量化的量化方法量化，则可能对其进行反量化。

禁用梯度检查点

( )

禁用当前模型的梯度检查点（在其他框架中可能称为激活检查点或检查点激活）。

disable_npu_flash_attention

( )

禁用来自 torch_npu 的 npu flash attention

disable_xformers_memory_efficient_attention

( )

禁用来自 xFormers 的内存高效注意力。

disable_xla_flash_attention

( )

禁用 torch_xla 的 flash attention pallals 内核。

启用梯度检查点

( )

为当前模型激活梯度检查点（在其他框架中可能称为激活检查点或检查点激活）。

enable_npu_flash_attention

( )

启用来自 torch_npu 的 npu flash attention

enable_xformers_memory_efficient_attention

( attention_op: typing.Optional[typing.Callable] = None )

参数

attention_op (Callable, 可选) — 覆盖默认的 None 运算符，以用作 xFormers 的 memory_efficient_attention() 函数的 op 参数。

启用来自 xFormers 的内存高效注意力。

启用此选项后，您应该会观察到更低的 GPU 内存使用率以及推理期间潜在的速度提升。不保证训练期间的速度提升。

⚠️ 当内存高效注意力和切片注意力都启用时，内存高效注意力优先。

示例

>>> import torch
>>> from diffusers import UNet2DConditionModel
>>> from xformers.ops import MemoryEfficientAttentionFlashAttentionOp

>>> model = UNet2DConditionModel.from_pretrained(
...     "stabilityai/stable-diffusion-2-1", subfolder="unet", torch_dtype=torch.float16
... )
>>> model = model.to("cuda")
>>> model.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)

enable_xla_flash_attention

( partition_spec: typing.Optional[typing.Callable] = None )

为 torch_xla 启用 flash attention pallals 内核。

from_pretrained

( pretrained_model_name_or_path: typing.Union[str, os.PathLike, NoneType] **kwargs )

参数

pretrained_model_name_or_path (str 或 os.PathLike, 可选) — 可以是以下之一：
- 一个字符串，Hub 上托管的预训练模型的模型 ID (例如 google/ddpm-celebahq-256)。
- 一个目录的路径 (例如 ./my_model_directory)，其中包含使用 save_pretrained() 保存的模型权重。
cache_dir (Union[str, os.PathLike], 可选) — 如果不使用标准缓存，则下载的预训练模型配置缓存到的目录路径。
torch_dtype (str 或 torch.dtype, 可选) — 覆盖默认的 torch.dtype 并使用另一种 dtype 加载模型。如果传递 "auto"，则 dtype 会自动从模型的权重中派生。
force_download (bool, 可选, 默认为 False) — 是否强制（重新）下载模型权重和配置文件，覆盖缓存的版本（如果存在）。
proxies (Dict[str, str], 可选) — 按协议或端点使用的代理服务器字典，例如，{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}。代理用于每个请求。
output_loading_info (bool, 可选, 默认为 False) — 是否也返回一个字典，其中包含缺失的键、意外的键和错误消息。
local_files_only(bool, 可选, 默认为 False) — 是否仅加载本地模型权重和配置文件。如果设置为 True，则不会从 Hub 下载模型。
token (str 或 bool, 可选) — 用作远程文件的 HTTP Bearer 授权的令牌。如果为 True，则使用从 diffusers-cli login 生成的令牌（存储在 ~/.huggingface 中）。
revision (str, 可选, 默认为 "main") — 要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID 或 Git 允许的任何标识符。
from_flax (bool, 可选, 默认为 False) — 从 Flax 检查点保存文件加载模型权重。
subfolder (str, 可选, 默认为 "") — Hub 或本地的较大模型仓库中模型文件的子文件夹位置。
mirror (str, 可选) — 镜像源，用于解决在中国下载模型时的可访问性问题。我们不保证来源的及时性或安全性，您应参考镜像站点以获取更多信息。
device_map (str 或 Dict[str, Union[int, str, torch.device]], 可选) — 一个指定每个子模块应放置位置的映射。无需为每个参数/缓冲区名称定义；一旦给定的模块名称在其中，它的每个子模块都将被发送到同一设备。默认为 None，表示模型将在 CPU 上加载。

设置 device_map="auto" 以使 🤗 Accelerate 自动计算最优化的 device_map。有关每个选项的更多信息，请参阅设计设备映射。
max_memory (Dict, 可选) — 最大内存的字典设备标识符。如果未设置，则默认为每个 GPU 的最大可用内存和可用的 CPU RAM。
offload_folder (str 或 os.PathLike, 可选) — 如果 device_map 包含值 "disk"，则用于卸载权重的路径。
offload_state_dict (bool, 可选) — 如果为 True，则临时将 CPU 状态字典卸载到硬盘驱动器，以避免在 CPU 状态字典的权重 + 检查点的最大分片不适合时耗尽 CPU RAM。当存在一些磁盘卸载时，默认为 True。
low_cpu_mem_usage (bool, 可选, 如果 torch 版本 >= 1.9.0 则默认为 True，否则为 False) — 加速模型加载，仅加载预训练权重，而不初始化权重。这还尝试在加载模型时，CPU 内存（包括峰值内存）的使用量不超过模型大小的 1 倍。仅支持 PyTorch >= 1.9.0。如果您使用的是旧版本的 PyTorch，则将此参数设置为 True 将引发错误。
variant (str, 可选) — 从指定的 variant 文件名（例如 "fp16" 或 "ema"）加载权重。从 from_flax 加载时，此项将被忽略。
use_safetensors (bool, 可选, 默认为 None) — 如果设置为 None，则当 safetensors 权重可用**且**安装了 safetensors 库时，将下载它们。如果设置为 True，则强制从 safetensors 权重加载模型。如果设置为 False，则不加载 safetensors 权重。

从预训练模型配置实例化预训练 PyTorch 模型。

默认情况下，该模型设置为评估模式 - model.eval() - 并且 dropout 模块被停用。要训练模型，请使用 model.train() 将其设置回训练模式。

要使用私有模型或门控模型，请使用 huggingface-cli login 登录。您还可以激活特殊的“离线模式”，以便在有防火墙的环境中使用此方法。

示例

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("runwayml/stable-diffusion-v1-5", subfolder="unet")

如果您收到以下错误消息，则需要为您的下游任务微调权重

Some weights of UNet2DConditionModel were not initialized from the model checkpoint at runwayml/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.

get_memory_footprint

( return_buffers = True )

参数

return_buffers (bool, 可选, 默认为 True) — 是否在内存占用计算中返回缓冲区张量的大小。缓冲区是不需要梯度且未注册为参数的张量。例如，批归一化层中的均值和标准差。请参阅： https://discuss.pytorch.org/t/what-pytorch-means-by-buffers/120266/2

获取模型的内存占用量。这将返回当前模型的内存占用量（以字节为单位）。有助于基准测试当前模型的内存占用量并设计一些测试。解决方案灵感来自 PyTorch 讨论： https://discuss.pytorch.org/t/gpu-memory-that-model-uses/56822/2

num_parameters

( only_trainable: bool = False exclude_embeddings: bool = False ) → int

参数

only_trainable (bool, 可选, 默认为 False) — 是否仅返回可训练参数的数量。
exclude_embeddings (bool, 可选, 默认为 False) — 是否仅返回非嵌入参数的数量。

返回值

int

参数的数量。

获取模块中（可训练或非嵌入）参数的数量。

示例

from diffusers import UNet2DConditionModel

model_id = "runwayml/stable-diffusion-v1-5"
unet = UNet2DConditionModel.from_pretrained(model_id, subfolder="unet")
unet.num_parameters(only_trainable=True)
859520964

save_pretrained

( save_directory: typing.Union[str, os.PathLike] is_main_process: bool = True save_function: typing.Optional[typing.Callable] = None safe_serialization: bool = True variant: typing.Optional[str] = None max_shard_size: typing.Union[int, str] = '10GB' push_to_hub: bool = False **kwargs )

参数

save_directory (str 或 os.PathLike) — 用于保存模型及其配置文件到其中的目录。如果目录不存在，将会被创建。
is_main_process (bool, 可选, 默认为 True) — 调用此方法的进程是否为主进程。在分布式训练中很有用，您需要在所有进程上调用此函数。在这种情况下，仅在主进程上设置 is_main_process=True 以避免竞争条件。
save_function (Callable) — 用于保存状态字典的函数。在分布式训练中，当您需要用另一种方法替换 torch.save 时很有用。可以使用环境变量 DIFFUSERS_SAVE_MODE 进行配置。
safe_serialization (bool, 可选, 默认为 True) — 是否使用 safetensors 或传统的 PyTorch 方式 pickle 保存模型。
variant (str, 可选) — 如果指定，权重将以 pytorch_model.<variant>.bin 格式保存。
max_shard_size (int 或 str, 默认为 "10GB") — 分片之前的检查点最大大小。检查点分片后的每个大小都将低于此大小。如果表示为字符串，则需要是数字后跟单位（如 "5GB"）。如果表示为整数，则单位为字节。请注意，此限制将在一段时间后（从 2024 年 10 月开始）减少，以便用户升级到最新版本的 diffusers。这是为了在 Hugging Face 生态系统（例如 transformers 和 accelerate）的不同库中为此参数建立通用的默认大小。
push_to_hub (bool, 可选, 默认为 False) — 是否在保存模型后将其推送到 Hugging Face Hub。您可以使用 repo_id 指定要推送到的存储库（默认为您命名空间中 save_directory 的名称）。
kwargs (Dict[str, Any], 可选) — 传递给 push_to_hub() 方法的附加关键字参数。

将模型及其配置文件保存到目录中，以便可以使用 from_pretrained() 类方法重新加载。

set_use_npu_flash_attention

( valid: bool )

设置 npu flash attention 的开关。

FlaxModelMixin

class diffusers.FlaxModelMixin

( )

所有 Flax 模型的基础类。

FlaxModelMixin 负责存储模型配置，并提供加载、下载和保存模型的方法。

config_name (str) — 调用 save_pretrained() 时用于保存模型的文件名。

from_pretrained

( pretrained_model_name_or_path: typing.Union[str, os.PathLike] dtype: dtype = <class 'jax.numpy.float32'> *model_args **kwargs )

参数

pretrained_model_name_or_path (str 或 os.PathLike) — 可以是以下之一：
- 一个字符串，Hub 上托管的预训练模型的模型 ID（例如 runwayml/stable-diffusion-v1-5）。
- 一个目录的路径（例如 ./my_model_directory），其中包含使用 save_pretrained() 保存的模型权重。
dtype (jax.numpy.dtype, 可选, 默认为 jax.numpy.float32) — 计算的数据类型。可以是 jax.numpy.float32、jax.numpy.float16 (在 GPU 上) 和 jax.numpy.bfloat16 (在 TPU 上) 之一。

这可以用于在 GPU 或 TPU 上启用混合精度训练或半精度推理。如果指定，所有计算将使用给定的 dtype 执行。

这仅指定计算的 dtype，不影响模型参数的 dtype。

如果您希望更改模型参数的 dtype，请参阅 to_fp16() 和 to_bf16()。
model_args (位置参数序列, 可选) — 所有剩余的位置参数都将传递给底层模型的 __init__ 方法。
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 下载模型。
revision (str, 可选, 默认为 "main") — 要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID 或 Git 允许的任何标识符。
from_pt (bool, 可选, 默认为 False) — 从 PyTorch 检查点保存文件加载模型权重。
kwargs (剩余的关键字参数字典, 可选) — 可用于更新配置对象（加载后）和初始化模型（例如， output_attentions=True）。根据是否提供 config 或自动加载 config，行为有所不同：
- 如果使用 config 提供了配置，则 kwargs 直接传递给底层模型的 __init__ 方法（我们假设已完成对配置的所有相关更新）。
- 如果未提供配置，则 kwargs 首先传递给配置类初始化函数 from_config()。 kwargs 的每个键（对应于配置属性）用于使用提供的 kwargs 值覆盖所述属性。不对应于任何配置属性的剩余键将传递给底层模型的 __init__ 函数。

从预训练模型配置实例化预训练的 Flax 模型。

示例

>>> from diffusers import FlaxUNet2DConditionModel

>>> # Download model and configuration from huggingface.co and cache.
>>> model, params = FlaxUNet2DConditionModel.from_pretrained("runwayml/stable-diffusion-v1-5")
>>> # Model was saved using *save_pretrained('./test/saved_model/')* (for example purposes, not runnable).
>>> model, params = FlaxUNet2DConditionModel.from_pretrained("./test/saved_model/")

如果您收到以下错误消息，则需要为您的下游任务微调权重

Some weights of UNet2DConditionModel were not initialized from the model checkpoint at runwayml/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.

save_pretrained

( save_directory: typing.Union[str, os.PathLike] params: typing.Union[typing.Dict, flax.core.frozen_dict.FrozenDict] is_main_process: bool = True push_to_hub: bool = False **kwargs )

参数

save_directory (str or os.PathLike) — 将模型及其配置文件保存到的目录。如果目录不存在，则会创建它。
params (Union[Dict, FrozenDict]) — 模型参数的 PyTree。
is_main_process (bool, 可选, 默认为 True) — 调用此进程是否为主进程。在分布式训练期间很有用，您需要在所有进程上调用此函数。在这种情况下，仅在主进程上设置 is_main_process=True，以避免竞争条件。
push_to_hub (bool, 可选, 默认为 False) — 是否在保存模型后将其推送到 Hugging Face 模型 Hub。您可以使用 repo_id 指定要推送到的仓库（默认为您命名空间中 save_directory 的名称）。
kwargs (Dict[str, Any], 可选) — 传递给 push_to_hub() 方法的其他关键字参数。

将模型及其配置文件保存到目录，以便可以使用 from_pretrained() 类方法重新加载。

to_bf16

( params: typing.Union[typing.Dict, flax.core.frozen_dict.FrozenDict] mask: typing.Any = None )

参数

params (Union[Dict, FrozenDict]) — 模型参数的 PyTree。
mask (Union[Dict, FrozenDict]) — 具有与 params 树相同结构的 PyTree。叶节点应为布尔值。对于要转换的参数，它应为 True，对于要跳过的参数，它应为 False。

将浮点 params 转换为 jax.numpy.bfloat16。这将返回一个新的 params 树，并且不会就地转换 params。

此方法可以在 TPU 上使用，以显式地将模型参数转换为 bfloat16 精度，以进行全半精度训练或将权重保存为 bfloat16 以进行推理，从而节省内存并提高速度。

示例

>>> from diffusers import FlaxUNet2DConditionModel

>>> # load model
>>> model, params = FlaxUNet2DConditionModel.from_pretrained("runwayml/stable-diffusion-v1-5")
>>> # By default, the model parameters will be in fp32 precision, to cast these to bfloat16 precision
>>> params = model.to_bf16(params)
>>> # If you don't want to cast certain parameters (for example layer norm bias and scale)
>>> # then pass the mask as follows
>>> from flax import traverse_util

>>> model, params = FlaxUNet2DConditionModel.from_pretrained("runwayml/stable-diffusion-v1-5")
>>> flat_params = traverse_util.flatten_dict(params)
>>> mask = {
...     path: (path[-2] != ("LayerNorm", "bias") and path[-2:] != ("LayerNorm", "scale"))
...     for path in flat_params
... }
>>> mask = traverse_util.unflatten_dict(mask)
>>> params = model.to_bf16(params, mask)

to_fp16

( params: typing.Union[typing.Dict, flax.core.frozen_dict.FrozenDict] mask: typing.Any = None )

参数

params (Union[Dict, FrozenDict]) — 模型参数的 PyTree。
mask (Union[Dict, FrozenDict]) — 具有与 params 树相同结构的 PyTree。叶节点应为布尔值。对于要转换的参数，它应为 True，对于要跳过的参数，它应为 False。

将浮点 params 转换为 jax.numpy.float16。这将返回一个新的 params 树，并且不会就地转换 params。

此方法可以在 GPU 上使用，以显式地将模型参数转换为 float16 精度，以进行全半精度训练或将权重保存为 float16 以进行推理，从而节省内存并提高速度。

示例

>>> from diffusers import FlaxUNet2DConditionModel

>>> # load model
>>> model, params = FlaxUNet2DConditionModel.from_pretrained("runwayml/stable-diffusion-v1-5")
>>> # By default, the model params will be in fp32, to cast these to float16
>>> params = model.to_fp16(params)
>>> # If you want don't want to cast certain parameters (for example layer norm bias and scale)
>>> # then pass the mask as follows
>>> from flax import traverse_util

>>> model, params = FlaxUNet2DConditionModel.from_pretrained("runwayml/stable-diffusion-v1-5")
>>> flat_params = traverse_util.flatten_dict(params)
>>> mask = {
...     path: (path[-2] != ("LayerNorm", "bias") and path[-2:] != ("LayerNorm", "scale"))
...     for path in flat_params
... }
>>> mask = traverse_util.unflatten_dict(mask)
>>> params = model.to_fp16(params, mask)

to_fp32

( params: typing.Union[typing.Dict, flax.core.frozen_dict.FrozenDict] mask: typing.Any = None )

参数

params (Union[Dict, FrozenDict]) — 模型参数的 PyTree。
mask (Union[Dict, FrozenDict]) — 具有与 params 树相同结构的 PyTree。叶节点应为布尔值。对于要转换的参数，它应为 True，对于要跳过的参数，它应为 False。

将浮点 params 转换为 jax.numpy.float32。此方法可用于显式地将模型参数转换为 fp32 精度。这将返回一个新的 params 树，并且不会就地转换 params。

示例

>>> from diffusers import FlaxUNet2DConditionModel

>>> # Download model and configuration from huggingface.co
>>> model, params = FlaxUNet2DConditionModel.from_pretrained("runwayml/stable-diffusion-v1-5")
>>> # By default, the model params will be in fp32, to illustrate the use of this method,
>>> # we'll first cast to fp16 and back to fp32
>>> params = model.to_f16(params)
>>> # now cast back to fp32
>>> params = model.to_fp32(params)

PushToHubMixin

class diffusers.utils.PushToHubMixin

( )

一个 Mixin，用于将模型、调度器或 pipeline 推送到 Hugging Face Hub。

push_to_hub

( repo_id: str commit_message: typing.Optional[str] = None private: typing.Optional[bool] = None token: typing.Optional[str] = None create_pr: bool = False safe_serialization: bool = True variant: typing.Optional[str] = None )

参数

repo_id (str) — 您要将模型、调度器或 pipeline 文件推送到的仓库的名称。当推送到组织时，它应包含您的组织名称。 repo_id 也可以是本地目录的路径。
commit_message (str, 可选) — 推送时提交的消息。默认为 "Upload {object}"。
private (bool, 可选) — 是否将仓库设为私有。如果为 None（默认值），则仓库将是公开的，除非组织的默认设置为私有。如果仓库已存在，则忽略此值。
token (str, 可选) — 用作远程文件的 HTTP Bearer 授权的令牌。运行 huggingface-cli login 时生成的令牌（存储在 ~/.huggingface 中）。
create_pr (bool, 可选, 默认为 False) — 是否使用上传的文件创建 PR 或直接提交。
safe_serialization (bool, 可选, 默认为 True) — 是否将模型权重转换为 safetensors 格式。
variant (str, 可选) — 如果指定，权重将以 pytorch_model.<variant>.bin 格式保存。

将模型、调度器或 pipeline 文件上传到 🤗 Hugging Face Hub。

示例

from diffusers import UNet2DConditionModel

unet = UNet2DConditionModel.from_pretrained("stabilityai/stable-diffusion-2", subfolder="unet")

# Push the `unet` to your namespace with the name "my-finetuned-unet".
unet.push_to_hub("my-finetuned-unet")

# Push the `unet` to an organization with the name "my-finetuned-unet".
unet.push_to_hub("your-org/my-finetuned-unet")

< > 在 GitHub 上更新

←PEFT ControlNetModel→