Diffusers documentation

モデル

Diffusers

はじめに

Diffusers インストールクイックスタートコマンドラインインターフェース

推論

拡散パイプラインの使用

アダプターとパーソナライズ

最適化とスケーリング

基本的なパフォーマンス

速度とメモリ

分散推論

量子化

ハードウェア固有のアクセラレーション

コミュニティの手法

モジュール型 Diffusers

学習とファインチューニング

リソース

コントリビュート

API

主なクラス

モジュール型

ローダー

モデル

概要 AutoModel

ControlNets

Transformers

UNets

VAE

Pipelines

スケジューラ

内部クラス

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

モデル

🤗 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()を呼び出す際にモデルを保存するファイル名。

compile_repeated_blocks

( *args**kwargs )

モデル全体をコンパイルするのではなく、頻繁に繰り返し実行されるサブモジュール（Transformer層など）のみをコンパイルします。この手法はリージョナルコンパイル（PyTorchのレシピ https://docs.pytorch.org/tutorials/recipes/regional_compilation.html を参照）とも呼ばれ、torch.compile 全体を適用した場合に期待されるランタイムの高速化を維持しつつ、エンドツーエンドのコンパイル時間を大幅に短縮できます。

コンパイル対象のサブモジュールのセットは、モデル定義内の _repeated_blocks 属性の存在によって特定されます。この属性をモデルのサブクラスに、クラス名（文字列）のリスト/タプルとして定義してください。クラス名が一致するすべてのモジュールがコンパイルされます。

発見された各一致するサブモジュールは、submodule.compile(*args, **kwargs)を呼び出すことでコンパイルされます。compile_repeated_blocksに指定した位置引数やキーワード引数は、そのままtorch.compileに転送されます。

cuda

( *args**kwargs )

ドット区切りパス（例: torch.float32）のモック値: 属性アクセスチェーン、呼び出しはパススルーデコレータとして動作し、repr はドット区切りパスを返し、ベースクラスとして使用するとプレーンな type ベースに置き換えられます（PEP 560 の __mro_entries__）。これにより、実際のサブクラスは通常のメタクラスを保持し、inspect.signature はモックの __init__ ではなく、実際の __init__ を読み取ります。

dequantize

( )

量子化手法によって量子化されている場合、デクォンタイズをサポートしている場合は、モデルをデクォンタイズする可能性があります。

disable_gradient_checkpointing

( )

現在のモデルの勾配チェックポイント機能を無効にします（他のフレームワークでは、activation checkpointingまたはcheckpoint activationsと呼ばれる場合があります）。

disable_npu_flash_attention

( )

torch_npu から NPU フラッシュアテンションを無効にする

disable_xformers_memory_efficient_attention

( )

xFormersからのメモリ効率の高いアテンションを無効にします。

disable_xla_flash_attention

( )

torch_xla における flash attention pallals カーネルを無効にします。

enable_gradient_checkpointing

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

パラメータ

gradient_checkpointing_func (Callable, 省略可) — 勾配チェックポイントに使用する関数です。None の場合、PyTorch のデフォルトのチェックポイント関数 (torch.utils.checkpoint.checkpoint) が使用されます。

現在のモデルに対して勾配チェックポイントを有効にします（他のフレームワークでは、activation checkpointingまたはcheckpoint activationsと呼ばれる場合があります）。

enable_group_offload

( onload_device: deviceoffload_device: device = torch.device()offload_type: str = 'block_level'num_blocks_per_group: int | None = Nonenon_blocking: bool = Falseuse_stream: bool = Falserecord_stream: bool = Falselow_cpu_mem_usage = Falseoffload_to_disk_path: str | None = Noneblock_modules: str | None = Noneexclude_kwargs: str | None = 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_e4m3fncompute_dtype: typing.Optional[torch.dtype] = Noneskip_modules_pattern: tuple[str, ...] | None = Noneskip_modules_classes: tuple[typing.Type[torch.nn.Module], ...] | None = Nonenon_blocking: bool = False )

パラメータ

storage_dtype (torch.dtype) — モデルを保存するためにキャストする dtype。
compute_dtype (torch.dtype) — フォワードパス中にモデルの重みをキャストする dtype。
skip_modules_pattern (tuple[str, ...]、省略可) — レイヤーワイズキャスト処理中にスキップするモジュールの名前と一致させるためのパターンリストです。Noneに設定されている場合、モジュールの特定の内部レイヤーおよびPEFTレイヤーを無視するために、デフォルトのスキップパターンが使用されます。
skip_modules_classes (tuple[Type[torch.nn.Module], ...], 省略可) — レイヤーワイズキャスト処理中にスキップするモジュールクラスのリストです。
non_blocking (bool、省略可、デフォルトはFalse) — Trueの場合、重みのキャスト操作はブロッキングなしで実行されます。

現在のモデルに対してレイヤー単位のキャストを有効にします。

Layerwise castingは、モデルの重みを低精度のdtypeにキャストして保存し、計算時にはオンザフライで高精度のdtypeにアップキャストする技術です。このプロセスにより、モデルの重みによるメモリフットプリントを大幅に削減できますが、出力の品質が若干低下する可能性があります。品質の低下の多くは無視できるレベルであり、主に正規化層やモジュレーション層での重みキャストに起因します。

デフォルトでは、diffusers のほとんどのモデルは _skip_layerwise_casting_patterns 属性を設定し、パッチ埋め込み、位置埋め込み、正規化レイヤーを無視します。これは、これらのレイヤーが品質に対して精度が重要である可能性が高いためです。この動作を変更したい場合は、_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 フラッシュアテンションを有効にする

enable_xformers_memory_efficient_attention

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

パラメータ

attention_op (Callable, 省略可) — xFormers の memory_efficient_attention() 関数の op 引数として使用する、デフォルトの None オペレータを上書きします。

xFormersからメモリ効率の高いアテンションを有効にします。

このオプションを有効にすると、推論時にGPUメモリ使用量の低下と速度向上が期待できます。ただし、トレーニング時の速度向上は保証されません。

> ⚠️ memory efficient attention と sliced attention の両方が有効な場合、memory efficient attention が > 優先されます。

例:

>>> 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 pallals カーネルを有効にします。

from_pretrained

( pretrained_model_name_or_path: str | os.PathLike | None**kwargs )

パラメータ

pretrained_model_name_or_path (str または os.PathLike, 省略可) — 次のいずれかです:
- Hub にホストされている事前学習済みモデルの model id（例: google/ddpm-celebahq-256）を表す文字列。
- A path to a directory (for example ./my_model_directory) containing the model weights saved with save_pretrained().
cache_dir (str | os.PathLike, 任意) — 標準のキャッシュを使用しない場合、ダウンロードした事前学習モデルの構成がキャッシュされるディレクトリのパス。
dtype (torch.dtype, 省略可) — デフォルトのtorch.dtypeを上書きし、別の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 ベアラ認証に使用するトークンです。True の場合、diffusers-cli login で生成されたトークン（~/.huggingface に保存されています）が使用されます。
revision (str、任意、デフォルトは"main") — 使用する特定のモデルのバージョンです。ブランチ名、タグ名、コミット ID、または Git によって許可される任意の識別子を使用できます。
subfolder (str、任意、デフォルトは"") — Hub またはローカル上のより大きなモデルリポジトリ内での、モデルファイルのサブフォルダの場所。
mirror (str, 任意) — 中国でモデルをダウンロードする際に、アクセシビリティの問題を解決するためのミラーソースです。ソースの鮮度や安全性を保証するものではなく、詳細についてはミラーサイトをご参照ください。

device_map (int | str | torch.device または dict[str, int | str | torch.device], 省略可) — 各サブモジュールをどのデバイスに配置するかを指定するマップです。各パラメータ/バッファ名に対して定義する必要はありません。特定のモジュール名がマップに含まれている場合、そのモジュールのすべてのサブモジュールが同じデバイスに送信されます。デフォルトは None, で、モデルがCPUにロードされることを意味します。

例:

>>> from diffusers import AutoModel
>>> import torch

>>> # This works.
>>> model = AutoModel.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", device_map="cuda"
... )
>>> # This also works (integer accelerator device ID).
>>> model = AutoModel.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", device_map=0
... )
>>> # Specifying a supported offloading strategy like "auto" also works.
>>> model = AutoModel.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0", subfolder="unet", device_map="auto"
... )
>>> # Specifying a dictionary as `device_map` also works.
>>> model = AutoModel.from_pretrained(
...     "stabilityai/stable-diffusion-xl-base-1.0",
...     subfolder="unet",
...     device_map={"": torch.device("cuda")},
... )

device_map="auto" を設定すると、🤗 Accelerate が最も最適化された device_map を自動的に計算します。各オプションの詳細については、デバイスマップの設計を参照してください。より具体的な例については、Diffusers 固有のドキュメントも参照できます。

max_memory (Dict, 任意) — 最大メモリを示すデバイスの識別子の辞書です。未設定の場合、各 GPU の利用可能な最大メモリと、利用可能な CPU RAM がデフォルトとして使用されます。
offload_folder (str または os.PathLike、省略可) — device_map に "disk" という値が含まれる場合、重みをオフロードするパス。
offload_state_dict (bool、省略可) — Trueの場合、CPU RAMが不足するのを避けるため、CPU state dictの重さとチェックポイントの最大シャードの合計が収まらない場合に、CPU state dictを一時的にハードドライブへオフロードします。ディスクオフロードが存在する場合、デフォルトは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")から重みをロードします。
use_safetensors (bool、任意、デフォルトは None) — None に設定されている場合、safetensors の重みが利用可能であり、かつ safetensors ライブラリがインストールされている場合、それらの 重みがダウンロードされます。True に設定されている場合、モデルは safetensors の重みから強制的に読み込まれます。False に設定されている場合、safetensors の重みは読み込まれません。
disable_mmap (‘bool’, 任意、デフォルトは ‘False’) — Safetensors モデルの読み込み時に mmap を無効にするかどうか。モデルがネットワークマウントやハードドライブ上にあり、mmap のランダムアクセス（seek）を適切に処理できない可能性がある場合、このオプションを有効にするとパフォーマンスが向上する場合があります。
use_flashpack (bool、省略可能、デフォルトはFalse) — Trueに設定すると、モデルはflashpackの重みから読み込まれます。
flashpack_kwargs(`dict[str, Any], *optional*, defaults to {}) -- Kwargs passed to [flashpack.deserialization.assign_from_file`](https://github.com/fal-ai/flashpack/blob/f1aa91c5cd9532a3dbf5bcc707ab9b01c274b76c/src/flashpack/deserialization.py#L408-L422)

事前学習済みモデルの構成から、事前学習済み PyTorch モデルをインスタンス化します。

モデルはデフォルトで評価モードに設定されており、model.eval() が呼び出され、dropout モジュールは無効化されています。モデルを学習するには、model.train() を呼び出して学習モードに戻してください。

> プライベートモデルやゲート付きモデルを使用するには、hf > auth loginでログインしてください。また、ファイアウォールが設定された環境でこの方法を使用するために、特別な> 「オフラインモード」を有効にすることもできます。

例:

from diffusers import UNet2DConditionModel

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

以下のエラーメッセージが表示された場合、下流タスク用に重みをファインチューニングする必要があります。

Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/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) — メモリフットプリントの計算において、バッファテンソルのサイズを返すかどうかを指定します。バッファとは、勾配を必要とせず、パラメータとして登録されていないテンソルです。例えば、batch norm 層の mean や std などです。詳細は 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 = Falseexclude_embeddings: bool = False ) → int

パラメータ

only_trainable (bool、省略可、デフォルトは False) — 学習可能なパラメータの数のみを返すかどうかを指定します。
exclude_embeddings (bool、省略可、デフォルトはFalse) — 埋め込みパラメータ以外のパラメータ数のみを返すかどうかを指定します。

戻り値

int

パラメータの数。

モジュール内の（学習可能な、または埋め込み以外の）パラメータ数を取得します。

例:

from diffusers import UNet2DConditionModel

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

reset_attention_backend

( )

モデルのattentionバックエンドをリセットします。以降のforward呼び出しでは、設定されている場合は環境のデフォルト、設定されていない場合はtorchネイティブのscaled dot product attentionが使用されます。

save_pretrained

( save_directory: str | os.PathLikeis_main_process: bool = Truesave_function: typing.Optional[typing.Callable] = Nonesafe_serialization: bool = Truevariant: str | None = Nonemax_shard_size: int | str = '10GB'push_to_hub: bool = Falseuse_flashpack: 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を使用してモデルを保存するか、従来のpickleによるPyTorchの方式で保存するかどうかを指定します。
variant (str, 任意) — 指定した場合、重みはpytorch_model.<variant>.binの形式で保存されます。
max_shard_size (int または str、デフォルトは "10GB") — シャード化される前のチェックポイントの最大サイズです。シャード化されたチェックポイントは、それぞれがこのサイズ未満になります。文字列で指定する場合は、数字の後に単位（"5GB" など）を続ける必要があります。整数で指定する場合は、単位はバイトです。なお、diffusers の最新バージョンへのアップグレードをユーザーに促すため、2024年10月以降、一定期間後にこの上限値が引き下げられる予定です。これは、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_attention_backend

( backend: str )

パラメータ

backend (str) — 設定するバックエンドの名前。AttentionBackendName で定義されている利用可能なバックエンドのいずれかである必要があります。利用可能なバックエンドは diffusers.attention_dispatch.AttentionBackendName で確認できます。デフォルトでは、torch ネイティブのスケーリングドットプロダクトアテンションをバックエンドとして使用します。

モデルのattentionバックエンドを設定します。

set_use_npu_flash_attention

( valid: bool )

NPU flash attention のスイッチを設定します。

へ

( *args**kwargs )

ドット区切りパス（例: torch.float32）のモック値: 属性アクセスチェーン、呼び出しはパススルーデコレータとして動作し、repr はドット区切りパスを返し、ベースクラスとして使用するとプレーンな type ベースに置き換えられます（PEP 560 の __mro_entries__）。これにより、実際のサブクラスは通常のメタクラスを保持し、inspect.signature はモックの __init__ ではなく、実際の __init__ を読み取ります。

PushToHubMixin

class diffusers.utils.PushToHubMixin

( )

Hugging Face Hub にモデル、スケジューラ、またはパイプラインをプッシュするための Mixin。

push_to_hub

( repo_id: strcommit_message: str | None = Noneprivate: bool | None = Nonetoken: str | None = Nonecreate_pr: bool = Falsesafe_serialization: bool = Truevariant: str | None = Nonesubfolder: str | None = None )

パラメータ

repo_id (str) — モデル、スケジューラ、またはパイプラインのファイルをプッシュするリポジトリの名前です。組織にプッシュする場合は、組織名を含める必要があります。repo_id はローカルディレクトリへのパスとしても指定できます。
commit_message (str, 省略可) — プッシュ時にコミットするメッセージ。デフォルトは "Upload {object}" です。
private (bool、省略可) — リポジトリをプライベートにするかどうか。None（デフォルト）の場合、組織のデフォルトがプライベートでない限り、リポジトリはパブリックになります。リポジトリが既に存在する場合、この値は無視されます。
token (str, 任意) — リモートファイルの HTTP ベアラ認証に使用するトークン。hf auth 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")

Update on GitHub

←PEFT AutoModel→