Diffusers 文档

模型

Diffusers

加入 Hugging Face 社区

并获得升级文档体验的访问权限

在模型、数据集和空间上进行协作

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

在文档主题之间切换

开始

模型

🤗 扩散器提供流行算法的预训练模型和创建自定义扩散系统的模块。模型的主要功能是根据分布对输入样本进行去噪 $p_{\theta}(x_{t-1}|x_{t})$ .

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

ModelMixin

类 diffusers.ModelMixin

< 源代码 >

( )

所有模型的基类。

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

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

disable_gradient_checkpointing

< 源代码 >

( )

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

disable_npu_flash_attention

< 源代码 >

( )

禁用 torch_npu 中的 npu flash attention

disable_xformers_memory_efficient_attention

< 源代码 >

( )

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

enable_gradient_checkpointing

< 源代码 >

( )

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

enable_npu_flash_attention

< 源代码 >

( )

从 torch_npu 启用 npu flash attention

enable_xformers_memory_efficient_attention

< 源文件 >

( attention_op: 可选 = None )

参数

attention_op (可调用对象，可选) — 覆盖默认的 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)

from_pretrained

< 源 >

( pretrained_model_name_or_path: Union **kwargs )

参数

pretrained_model_name_or_path (str 或 os.PathLike，可选) — 可以是：
- 一个字符串，一个在 Hub 上托管的预训练模型的模型 id (例如 google/ddpm-celebahq-256)。
- 一个包含保存有 save_pretrained() 所保存的模型权重的文件夹 (例如 ./my_model_directory) 的路径。
cache_dir (Union[str, os.PathLike], 可选) — 下载的预训练模型配置的缓存目录路径，如果未使用标准缓存。
torch_dtype (str 或 torch.dtype, 可选) — 重写默认 torch.dtype，使用另一种 dtype 加载模型。如果 “auto” 传入，则 dtype 将根据模型的权重自动推导。
force_download (布尔值, 可选，默认为 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 持有者授权的令牌。如果为 True，将使用从 diffusers-cli login（存储在 ~/.huggingface）生成的令牌。
revision （str，可选，默认为 "main"）— 要使用的特定模型版本。它可以是分支名称、标签名称、提交 ID 或 Git 允许的任何标识符。
subfolder (str，可选，默认为 "") — 在 Hub 上较大的模型仓库或本地中，模型文件的子文件夹位置。
镜像 (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, 可选，默认为 True 如果火炬版本 >= 1.9.0 否则为 False) — 加快模型加载速度，仅加载预训练的权重，而不初始化权重。这还尝试在加载模型时，不在 CPU 内存中使用超过 1x 模型大小的内存（包括峰值内存）。仅支持 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.

num_parameters

< source >

（ 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: Union is_main_process: bool = True save_function: Optional = None safe_serialization: bool = True variant: Optional = None max_shard_size: Union = '10GB' push_to_hub: bool = False **kwargs )

参数

save_directory (str 或 os.PathLike) —保存模型及其配置文件的目录。如果不存在，则创建。
is_main_process (bool, 可选，默认为 True) —调用此项的过程是否是主过程。分布式训练期间很有用，您需要在所有进程中都调用此函数。在这种情况下，仅对主进程设置 is_main_process=True，以避免竞争条件。
save_function (Callable) — 可用来保存 state dictionary 的方法。此方法对于需要使用其他方法替换 `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: 布尔值 )

设置 npu Flash attention 的开关。

FlaxModelMixin

类 diffusers.FlaxModelMixin

< 来源 >

( )

所有 Flax 模型的基础类。

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

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

from_pretrained

< 来源 >

( pretrained_model_name_or_path: Union dtype: dtype = <class 'jax.numpy.float32'> *model_args **kwargs

参数

pretrained_model_name_or_path (str 或 os.PathLike) — 可以是以下选项之一：
- 字符串，预训练模型的模型 ID（例如 runwayml/stable-diffusion-v1-5），该模型托管在 Hub 中。
- 指向目录的路径（例如 ./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 (布尔值, 可选, 默认为 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 (布尔值，可选，默认为 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

< source >

( save_directory: Union params: Union 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: Union mask: 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: Union mask: 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

< source >

( params: Union mask: Any = None )

参数

params (Union[Dict, FrozenDict]) — 模型参数的PyTree。

params转换为jax.numpy.float32。此方法可用于将模型参数明确转换为 fp32 精度。这会返回一个新的参数树，不会在适当位置转换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

类 diffusers.utils.PushToHubMixin

< 源代码 >

( )

一个混合类，可以将模型、调度程序或管道推送到 Hugging Face Hub。

push_to_hub

< 来源 >

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

参数

repo_id (str) — 你希望将模型、调度器或管道文件推送到其上的存储库的名称。推送到组织时应包含组织名称。
commit_message (str, 可选) — 推送时用来提交的消息。默认为 "上传 {object}"。
private (bool, 可选) — 要创建的存储库是否为私有。
create_pr (布尔, 可选, 默认值为假的) — 是否使用上传的文件创建 PR 或直接提交。
safe_serialization (布尔, 可选, 默认值为真的) — 是否将模型权重转换为 safetensors 格式。


   举例
 
 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 UNet1DModel→


		



模型 模型混合 Flax模型混合 推送至Hub混合