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.