Hugging Face 的 LOGO

Diffusers 文档

模型

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

模型

🤗 Diffusers 为流行算法提供了预训练模型和用于创建自定义扩散系统的模块。模型的主要功能是对输入样本进行去噪，其建模的分布为pθ(xt−1∣xt)p_{\theta}(x_{t-1}|x_{t}).

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

ModelMixin

class diffusers.ModelMixin

< >

( )

所有模型的基类。

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

dequantize

< >

( )

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

disable_gradient_checkpointing

< >

( )

为当前模型禁用梯度检查点（在其他框架中可能称为 activation checkpointing 或 checkpoint activations）。

disable_npu_flash_attention

< >

( )

禁用 torch_npu 的 npu flash attention

disable_xformers_memory_efficient_attention

< >

( )

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

disable_xla_flash_attention

< >

( )

禁用 torch_xla 的 flash attention 并行内核。

enable_gradient_checkpointing

< >

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

参数

  • gradient_checkpointing_func (Callable, optional) — 用于梯度检查点的函数。如果为 None，则使用默认的 PyTorch 检查点函数 (torch.utils.checkpoint.checkpoint)。

为当前模型启用梯度检查点（在其他框架中可能称为 activation checkpointing 或 checkpoint activations）。

enable_group_offload

< >

( onload_device: device offload_device: device = device(type='cpu') offload_type: str = 'block_level' num_blocks_per_group: typing.Optional[int] = None non_blocking: bool = False use_stream: bool = False record_stream: bool = False low_cpu_mem_usage = False offload_to_disk_path: typing.Optional[str] = None )

为当前模型启用分组卸载。

有关更多信息，请参阅 apply_group_offloading()。

示例

>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> transformer.enable_group_offload(
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="leaf_level",
...     use_stream=True,
... )

enable_layerwise_casting

< >

( storage_dtype: dtype = torch.float8_e4m3fn compute_dtype: typing.Optional[torch.dtype] = None skip_modules_pattern: typing.Optional[typing.Tuple[str, ...]] = None skip_modules_classes: typing.Optional[typing.Tuple[typing.Type[torch.nn.modules.module.Module], ...]] = None non_blocking: bool = False )

参数

  • storage_dtype (torch.dtype) — 用于存储的模型应转换到的 dtype。
  • compute_dtype (torch.dtype) — 在前向传播期间模型权重应转换到的 dtype。
  • skip_modules_pattern (Tuple[str, ...], optional) — 在逐层转换过程中用于匹配要跳过的模块名称的模式列表。如果设置为 None，将使用默认的跳过模式来忽略模块的某些内部层和 PEFT 层。
  • skip_modules_classes (Tuple[Type[torch.nn.Module], ...], optional) — 在逐层转换过程中要跳过的模块类列表。
  • non_blocking (bool, optional, 默认为 False) — 如果为 True，则权重转换操作是非阻塞的。

为当前模型启用逐层转换。

逐层转换是一种技术，它将模型权重转换为较低精度的 dtype 进行存储，但在计算时动态地将其上转换为较高精度的 dtype。这个过程可以显著减少模型权重的内存占用，但可能会导致输出质量有所下降。大多数质量下降可以忽略不计，主要源于归一化层和调制层中的权重转换。

默认情况下，diffusers 中的大多数模型都会设置 _skip_layerwise_casting_patterns 属性来忽略 patch embedding、positional embedding 和归一化层。这是因为这些层很可能是影响质量的关键精度层。如果你希望改变这种行为，可以将 _skip_layerwise_casting_patterns 属性设置为 None，或者使用自定义参数调用 apply_layerwise_casting()。

示例

使用 enable_layerwise_casting()

>>> from diffusers import CogVideoXTransformer3DModel

>>> transformer = CogVideoXTransformer3DModel.from_pretrained(
...     "THUDM/CogVideoX-5b", subfolder="transformer", torch_dtype=torch.bfloat16
... )

>>> # Enable layerwise casting via the model, which ignores certain modules by default
>>> transformer.enable_layerwise_casting(storage_dtype=torch.float8_e4m3fn, compute_dtype=torch.bfloat16)

enable_npu_flash_attention

< >

( )

启用 torch_npu 的 npu flash attention

enable_xformers_memory_efficient_attention

< >

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

参数

  • attention_op (Callable, optional) — 覆盖默认的 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 **kwargs )

启用 torch_xla 的 flash attention 并行内核。

from_pretrained

< >

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

参数

  • pretrained_model_name_or_path (str 或 os.PathLike, optional) — 可以是以下之一：

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

    示例：

从预训练模型配置中实例化一个预训练的 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 )

参数

获取模型的内存占用。这将返回当前模型以字节为单位的内存占用。有助于对当前模型的内存占用进行基准测试和设计一些测试。解决方案灵感来自 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, optional, 默认为 False) — 是否只返回可训练参数的数量。
  • exclude_embeddings (bool, optional, 默认为 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 负责存储模型配置，并提供加载、下载和保存模型的方法。

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 上的预训练模型的 model id（例如 runwayml/stable-diffusion-v1-5）。
    • 一个指向包含使用 save_pretrained() 保存的模型权重的目录的路径（例如 ./my_model_directory）。
  • 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 提供了配置，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 或 os.PathLike) — 用于保存模型及其配置文件的目录。如果目录不存在，将会被创建。
  • params (Union[Dict, FrozenDict]) — 模型参数的 PyTree。
  • is_main_process (bool, 可选, 默认为 True) — 调用此函数的进程是否为主进程。这在分布式训练中非常有用，当你需要在所有进程上调用此函数时。在这种情况下，仅在主进程上设置 is_main_process=True 以避免竞态条件。
  • push_to_hub (bool, 可选, 默认为 False) — 是否在保存模型后将其推送到 Hugging Face 模型中心。你可以使用 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

< >

( )

用于将模型、调度器或管道推送到Hugging Face Hub的Mixin。

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

将模型、调度器或管道文件上传到 🤗 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 AutoModel→
© . This site is unofficial and not affiliated with Hugging Face, Inc.