diffusers/main/ja/api/pipelines/overview.md

パイプライン

Pipelines は、推論時に最先端の拡散モデルを実行するためのシンプルな方法を提供します。必要なコンポーネント（個別に学習された複数のモデル、スケジューラ、プロセッサ）を単一のエンドツーエンドのクラスにまとめることで実現されています。Pipelines は柔軟性があり、異なるスケジューラやモデルコンポーネントの使用に適応させることができます。

すべてのパイプラインは、コンポーネントの読み込み、ダウンロード、保存に関する基本的な機能を提供するベースクラスである DiffusionPipeline から構築されます。from_pretrained() で読み込まれる具体的なパイプラインの種類（例えば StableDiffusionPipeline）は自動的に検出され、パイプラインのコンポーネントが読み込まれて、そのパイプラインの __init__ 関数に渡されます。

DiffusionPipeline クラスは学習には使用しないでください。拡散パイプラインの個別コンポーネント（UNet2DModel や UNet2DConditionModel など）は通常、個別に学習されるため、それらを直接扱うことをお勧めします。

Pipelinesには学習機能は提供されていません。torch.no_gradデコレーターで__call__()メソッドを装飾しているため、PyTorchのautogradが無効化されていることに気づくでしょう。これは、Pipelinesは学習に使用すべきではないためです。学習について興味がある場合は、代わりにTrainingガイドをご覧ください。

サイドバーのAPI > パイプラインを使用して、モダリティ別のすべてのパイプラインリファレンスを確認できます。タスク指向のワークフローでは、クイックスタートまたはテキストから画像へ、画像から画像へ、インペインティング、動画生成などのガイドから始めることをお勧めします。

DiffusionPipeline[[diffusers.DiffusionPipeline]]

diffusers.DiffusionPipeline[[diffusers.DiffusionPipeline]]

diffusers.DiffusionPipeline()

ソース

すべてのパイプラインの基底クラス。

DiffusionPipeline は、拡散パイプラインのすべてのコンポーネント（モデル、スケジューラ、プロセッサ）を保存し、モデルの読み込み、ダウンロード、保存を行うメソッドを提供します。また、以下のメソッドも含まれます。

• PyTorchのすべてのモジュールを、選択したデバイスに移動します
• デノイジング反復のプログレスバーを有効化/無効化

クラス属性:

• config_name (str) -- 拡散パイプラインのすべてのコンポーネントのクラス名とモジュール名を保存する設定ファイルの名前。
• _optional_components (List[str]) -- パイプラインの動作に必ずしも渡す必要のない、すべてのオプションコンポーネントのリスト（サブクラスでオーバーライドされるべきです）。

call[[diffusers.DiffusionPipeline.call]]

__call__(*args, **kwargs)

self を関数として呼び出します。

device[[diffusers.DiffusionPipeline.device]]

device()

ソース

戻り値: torch.device

パイプラインが配置されている torch デバイスです。コンポーネントが複数のデバイスに分割されている場合（例えば、テキストエンコーダーが CPU にあり、デノイジングのバックボーンがアクセラレーターで実行されている場合）、アクセラレーターデバイスが返されます。

へ[[diffusers.DiffusionPipeline.to]]

to(*args, **kwargs)

ソース

パラメータ:

dtype (torch.dtype、任意) : 指定されたdtypeを持つパイプラインを返します

device (torch.Device, 任意) : 指定された device を持つパイプラインを返します

silence_dtype_warnings (str、任意、デフォルトはFalse) : 対象のdtypeが対象のdeviceと互換性がない場合、警告を省略するかどうか。

戻り値: DiffusionPipeline

パイプラインは、指定されたdtypeおよび/またはdtypeに変換されました。

Performs Pipeline dtype and/or device conversion. A torch.dtype and torch.device are inferred from the arguments of self.to(*args, **kwargs).

> パイプラインがすでに正しい torch.dtype と torch.device を持っている場合、そのまま返されます。 それ以外の場合、> 返される pipeline は、指定された torch.dtype と torch.device を持つ self のコピーです。

toを呼び出す方法には、次のものがあります。

• to(dtype, silence_dtype_warnings=False) → DiffusionPipeline は、指定された dtype を持つパイプラインを返します
• to(device, silence_dtype_warnings=False) → DiffusionPipeline を呼び出すと、指定した device を持つパイプラインが返されます。
• to(device=None, dtype=None, silence_dtype_warnings=False) → DiffusionPipeline は、指定された device と dtype を持つパイプラインを返します。

コンポーネント[[diffusers.DiffusionPipeline.components]]

components()

ソース

self.components プロパティは、追加のメモリを再割り当てせずに、同じ重みと設定で異なるパイプラインを実行する際に有用です。

Returns (dict): パイプラインの初期化に必要なすべてのモジュールを含む辞書。

例:

>>> from diffusers import (
...     StableDiffusionPipeline,
...     StableDiffusionImg2ImgPipeline,
...     StableDiffusionInpaintPipeline,
... )

>>> text2img = StableDiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> img2img = StableDiffusionImg2ImgPipeline(**text2img.components)
>>> inpaint = StableDiffusionInpaintPipeline(**text2img.components)

disable_attention_slicing[[diffusers.DiffusionPipeline.disable_attention_slicing]]

disable_attention_slicing()

ソース

スライスされたアテンションの計算を無効にします。enable_attention_slicingが以前に呼び出されていた場合、アテンションは1ステップで計算されます。

disable_xformers_memory_efficient_attention[[diffusers.DiffusionPipeline.disable_xformers_memory_efficient_attention]]

disable_xformers_memory_efficient_attention()

ソース

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

ダウンロード[[diffusers.DiffusionPipeline.download]]

download(pretrained_model_name, **kwargs)

ソース

パラメータ:

pretrained_model_name (str または os.PathLike、任意) : Hub にホストされている事前学習済みパイプラインの文字列またはリポジトリ ID(例: CompVis/ldm-text2im-large-256)。

custom_pipeline (str, 任意) : 以下のいずれかです: - 文字列。Hub にホストされている事前学習済みパイプラインの リポジトリ ID（例: CompVis/ldm-text2im-large-256）。カスタムパイプラインを定義する pipeline.py というファイルを含むリポジトリである必要があります。 - 文字列。Community 配下の GitHub にホストされているコミュニティパイプラインの ファイル名。有効なファイル名は、パイプラインスクリプトではなくファイル名と一致する必要があります（clip_guided_stable_diffusion.py ではなく clip_guided_stable_diffusion）。コミュニティパイプラインは、常に GitHub の現在の main ブランチから読み込まれます。 - カスタムパイプラインを含む ディレクトリ（./my_pipeline_directory/）へのパス。そのディレクトリには、カスタムパイプラインを定義する pipeline.py というファイルを含む必要があります。 > [!WARNING] > 🧪 これは実験的な機能であり、将来変更される可能性があります。 カスタムパイプラインの読み込みと作成の詳細については、コミュニティパイプラインの貢献方法 をご覧ください。

force_download (bool, 任意, デフォルトは False) : モデルの重みと設定ファイルの(再)ダウンロードを強制するかどうか。キャッシュされたバージョンが存在する場合でも、それを上書きします。

proxies (Dict[str, str], 省略可) : プロトコルまたはエンドポイントごとに使用するプロキシサーバーの辞書です。例えば、{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'} のように指定します。これらのプロキシは、各リクエストで使用されます。

output_loading_info(bool, optional, デフォルトは False) : 欠落キー、予期しないキー、エラーメッセージを含む辞書を返すかどうか。

local_files_only (bool、任意、デフォルトはFalse) : ローカルのモデルの重みと設定ファイルのみを読み込むかどうかを指定します。Trueに設定すると、モデルは Hub からダウンロードされません。

token (str または bool、省略可能) : リモートファイルの HTTP ベアラ認証に使用するトークン。True の場合、diffusers-cli login で生成されたトークン（~/.huggingface に保存）が使用されます。

revision (str、任意、デフォルトは"main") : 使用する特定のモデルバージョンです。ブランチ名、タグ名、コミット ID、または Git で許可されている任意の識別子を使用できます。

custom_revision (str、任意、デフォルトは "main") : 使用する特定のモデルバージョンです。Hub からカスタムパイプラインを読み込む場合、revision と同様に、ブランチ名、タグ名、またはコミット ID を指定できます。GitHub からカスタムパイプラインを読み込む場合は、🤗 Diffusers のバージョンを指定でき、それ以外の場合は Hub から読み込む際にデフォルトで "main" が使用されます。

mirror (str, 任意) : 中国でモデルをダウンロードする場合、アクセシビリティの問題を解決するためのミラーソースを指定します。ソースの鮮度や安全性を保証するものではなく、詳細についてはミラーサイトをご参照ください。

variant (str, 任意) : "fp16" や "ema" のような指定されたバリアントファイル名から重みを読み込みます。

use_safetensors (bool、任意、デフォルトはNone) : Noneに設定されている場合、safetensors の重みが利用可能であり、かつ safetensors ライブラリがインストールされている場合に、safetensors の重みがダウンロードされます。Trueに設定されている場合、モデルは強制的に safetensors の重みから読み込まれます。Falseに設定されている場合、safetensors の重みは読み込まれません。

use_onnx (bool、任意、デフォルトはFalse) : Trueに設定すると、ONNX 重みが存在する場合、常にダウンロードされます。Falseに設定すると、ONNX 重みはダウンロードされません。デフォルトでは、use_onnx は _is_onnx クラス属性の値をデフォルトとしており、非 ONNX パイプラインでは False、ONNX パイプラインでは True になります。ONNX 重みには、.onnx および .pb で終わるファイルの両方が含まれます。

trust_remote_code (bool、任意、デフォルトはFalse) : Hub上の独自のファイルで定義されたカスタムパイプラインとコンポーネントを許可するかどうか。このオプションは、Hub上のコードがローカルマシンで実行されるため、信頼できるリポジトリで、かつコードを確認済みの場合にのみTrueに設定すべきです。

use_flashpack (bool、任意、デフォルトはFalse) : Trueに設定すると、FlashPackの重みが存在する場合、常にダウンロードされます。Falseに設定すると、FlashPackの重みはダウンロードされません。

戻り値: os.PathLike

ダウンロードされたパイプラインへのパス。

事前学習済みパイプラインの重みから、PyTorchの拡散パイプラインをダウンロードしてキャッシュします。

> プライベートモデルやゲート付きモデルを使用するには、ログインしてください hf > auth login

enable_attention_slicing[[diffusers.DiffusionPipeline.enable_attention_slicing]]

enable_attention_slicing(slice_size: str | int = 'auto')

ソース

パラメータ:

slice_size (str または int、任意、デフォルトは "auto") : "auto" の場合、アテンションヘッドへの入力を半分にし、アテンションを2段階で計算します。"max" の場合、一度に1つのスライスのみを実行することで、最大限のメモリを節約します。数値が指定された場合、attention_head_dim // slice_size 個のスライスを 사용합니다。この場合、attention_head_dim は slice_size の倍数である必要があります。

スライスされたアテンション計算を有効にします。このオプションを有効にすると、アテンションモジュールは入力テンソルをスライスに分割し、複数ステップでアテンションを計算します。アテンションヘッドが1つを超える場合、各ヘッドに対して計算が順次実行されます。これは、わずかな速度低下を代償にメモリを節約するために有用です。

> ⚠️ scaled_dot_product_attention（SDPA）をすでに使用している場合は、attention slicing を有効にしないでください PyTorch > 2.0 または xFormers から。これらのアテンション計算はすでに非常にメモリ効率が高いため、この機能を有効にする必要はありません。SDPA または xFormers でアテンションスライシングを有効にすると、重大なスローダウンを引き起こす可能性があります!

例:

>>> import torch
>>> from diffusers import StableDiffusionPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained(
...     "stable-diffusion-v1-5/stable-diffusion-v1-5",
...     dtype=torch.float16,
...     use_safetensors=True,
... )

>>> prompt = "a photo of an astronaut riding a horse on mars"
>>> pipe.enable_attention_slicing()
>>> image = pipe(prompt).images[0]

enable_group_offload[[diffusers.DiffusionPipeline.enable_group_offload]]

enable_group_offload(onload_device: device, offload_device: device = torch.device(), offload_type: str = 'block_level', num_blocks_per_group: int | None = None, non_blocking: bool = False, use_stream: bool = False, record_stream: bool = False, low_cpu_mem_usage = False, offload_to_disk_path: str | None = None, exclude_modules: str | list[str] | None = None)

ソース

パラメータ:

onload_device (torch.device) : モジュールのグループがロードされているデバイス。

offload_device (torch.device、デフォルトはtorch.device("cpu")) : モジュールのグループがオフロードされるデバイスです。通常はCPUを指定します。デフォルトはCPUです。

offload_type (str または GroupOffloadingType、デフォルトは "block_level") : 適用するオフローディングの種類です。"block_level" または "leaf_level" のいずれかです。デフォルトは "block_level" です。

offload_to_disk_path (str、任意、デフォルトはNone) : パラメータをオフロードするディレクトリのパスです。RAMが限られた環境で、速度とメモリ使用量のバランスを重視する場合に、このオプションを設定すると有用です。

num_blocks_per_group (int, 任意) : offload_type="block_level" を使用する場合のグループあたりのブロック数。offload_type="block_level" を使用する場合は必須です。

non_blocking (bool、デフォルトはFalse) : True の場合、オフローディングとオンローディングがブロッキングなしのデータ転送で実行されます。

use_stream (bool、デフォルトはFalse) : True の場合、CUDA ストリームを使用してオフロードとオンロードを非同期で実行します。これにより、計算とデータ転送のオーバーラップが可能になります。

record_stream (bool、デフォルトはFalse) : use_streamを有効にした場合、現在のテンソルがこのストリームによって使用されたことをマークします。メモリ使用量がわずかに増加する代わりに、処理が高速になります。詳細については、PyTorch 公式ドキュメントを参照してください。

low_cpu_mem_usage (bool、デフォルトはFalse) : True の場合、テンソルを事前にピン留めするのではなく、オンザフライでピン留めすることで CPU メモリ使用量を最小限に抑えます。このオプションは、ストリーミング CPU オフロード（つまり use_stream=True）を使用している場合にのみ意味があります。CPU メモリがボトルネックになる場合に有用ですが、ストリームを使用する利点を相殺する可能性があります。

exclude_modules (Union[str, List[str]]、デフォルトは None) : オフロードから除外するモジュールのリスト。

torch.nn.Module の内部レイヤーにグループオフロードを適用します。グループオフロードとは何か、またどのような場合に有効であるかを理解するには、まず他のサポートされているオフロード方式の仕組みについて、いくつかの背景情報を提供する必要があります。

通常、オフローディングは2つのレベルで行われます。

• モジュールレベル: Diffusers では、ModelMixin::enable_model_cpu_offload() メソッドを使用してこれを有効にできます。 は、パイプラインの各コンポーネントをCPUにオフロードして保存し、計算が必要なときにアクセラレーターデバイスにオンロードすることで動作します。この方法は、すべてのコンポーネントをアクセラレーター上に保持するよりもメモリ効率に優れていますが、メモリ要件は依然としてかなり高くなります。この方法を実行するには、フォワードパスを完了するために、ランタイムのdtypeでのモデルサイズと、最大の中間活性化テンソルのサイズに相当するメモリが必要です。
• リーフレベル: Diffusers では、ModelMixin::enable_sequential_cpu_offload() メソッドを使用することでこれを有効にできます。 は、計算グラフの最下層のリーフレベルのパラメータを CPU にオフロードして保存し、計算のためにリーフのみをアクセラレータデバイスにオンロードすることで動作します。これによりアクセラレータメモリ使用量が最小限に抑えられますが、デバイス同期の回数が多くなるため、速度が遅くなる可能性があります。

Group offloading は、上記2つの手法の中間的なアプローチです。torch.nn.ModuleList または torch.nn.Sequential として構成された内部レイヤーのグループ単位でオフロードを行うことで機能します。この手法は、モジュールレベルのオフロードよりもメモリ使用量が少なく、デバイス同期の回数が減るため、リーフレベル/シーケンシャルオフロードよりも高速です。

もう一つのサポートされている機能（非同期データ転送ストリームに対応する CUDA デバイス向け）は、データ転送と計算をオーバーラップさせることで、シーケンシャルなオフローディングと比較して全体の実行時間を短縮できる点です。これは、ストリームを用いたレイヤープリフェッチによって有効化されます。具体的には、現在のレイヤーが実行されている間に、次に実行されるレイヤーのオンローディングがアクセラレーターデバイス上で開始される仕組みです。これにより、メモリ要件はわずかに増加します。なお、この実装はリーフレベルのオフローディングにも対応していますが、ストリームを使用すると大幅に高速化されます。

例:

>>> from diffusers import DiffusionPipeline
>>> import torch

>>> pipe = DiffusionPipeline.from_pretrained("Qwen/Qwen-Image", dtype=torch.bfloat16)

>>> pipe.enable_group_offload(
...     onload_device=torch.device("cuda"),
...     offload_device=torch.device("cpu"),
...     offload_type="leaf_level",
...     use_stream=True,
... )
>>> image = pipe("a beautiful sunset").images[0]

enable_model_cpu_offload[[diffusers.DiffusionPipeline.enable_model_cpu_offload]]

enable_model_cpu_offload(gpu_id: int | None = None, device: typing.Union[torch.device, str] = None)

ソース

パラメータ:

gpu_id (int, optional) : 推論で使用するアクセラレータのIDです。指定しない場合、デフォルトで0になります。

device (torch.Device または str、任意、デフォルトは None) : 推論で使用するアクセラレータの PyTorch デバイスタイプです。指定しない場合、利用可能なアクセラレータを自動的に検出して使用します。

accelerate を使用してすべてのモデルを CPU にオフロードし、パフォーマンスへの影響を最小限に抑えながらメモリ使用量を削減します。enable_sequential_cpu_offload とは異なり、このメソッドでは、forward メソッドが呼び出されたときに、一度に 1 つのモデル全体をアクセラレーターに移動し、次のモデルが実行されるまでモデルはアクセラレーター上に保持されます。enable_sequential_cpu_offload と比較するとメモリ削減効果は低くなりますが、unet の反復的な実行により、パフォーマンスは大幅に向上します。

enable_sequential_cpu_offload[[diffusers.DiffusionPipeline.enable_sequential_cpu_offload]]

enable_sequential_cpu_offload(gpu_id: int | None = None, device: typing.Union[torch.device, str] = None)

ソース

パラメータ:

gpu_id (int, optional) : 推論で使用するアクセラレータのIDです。指定しない場合、デフォルトで0になります。

device (torch.Device または str、任意、デフォルトは None) : 推論で使用するアクセラレータの PyTorch デバイスタイプです。指定しない場合、利用可能なアクセラレータを自動的に検出して使用します。

🤗 Accelerate を使用してすべてのモデルを CPU にオフロードし、メモリ使用量を大幅に削減します。呼び出されると、torch.nn.Module コンポーネントのすべての状態辞書（self._exclude_from_cpu_offload に含まれるものを除く）が CPU に保存され、その後 torch.device('meta') に移動されます。特定のサブモジュールの forward メソッドが呼び出されたときにのみ、アクセラレーターに読み込まれます。オフロードはサブモジュール単位で行われます。enable_model_cpu_offload よりメモリ削減効果は高いですが、パフォーマンスは低くなります。

enable_xformers_memory_efficient_attention[[diffusers.DiffusionPipeline.enable_xformers_memory_efficient_attention]]

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

ソース

パラメータ:

attention_op (Callable、任意) : xFormers の memory_efficient_attention() 関数の op 引数として使用するために、デフォルトの None オペレーターをオーバーライドします。

xFormersからメモリ効率の高いアテンションを有効にします。このオプションを有効にすると、GPUメモリ使用量の低下と、推論時の処理速度の向上が期待できます。ただし、学習時の処理速度向上は保証されません。

> ⚠️ メモリ効率の良いアテンションとスライスされたアテンションの両方が有効な場合、メモリ効率 attention は > に優先します。

例:

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

>>> pipe = DiffusionPipeline.from_pretrained("stabilityai/stable-diffusion-2-1", dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> pipe.enable_xformers_memory_efficient_attention(attention_op=MemoryEfficientAttentionFlashAttentionOp)
>>> # Workaround for not accepting attention shape using VAE for Flash Attention
>>> pipe.vae.enable_xformers_memory_efficient_attention(attention_op=None)

from_pipe[[diffusers.DiffusionPipeline.from_pipe]]

from_pipe(pipeline, **kwargs)

ソース

パラメータ:

pipeline (DiffusionPipeline) : 新しいパイプラインを作成する元となるパイプライン。

戻り値: DiffusionPipeline

pipeline と同じ重みと設定を持つ新しいパイプライン。

与えられたパイプラインから新しいパイプラインを作成します。このメソッドは、追加のメモリを再割り当てせずに、既存のパイプラインのコンポーネントから新しいパイプラインを作成する場合に便利です。

例:

>>> from diffusers import StableDiffusionPipeline, StableDiffusionSAGPipeline

>>> pipe = StableDiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")
>>> new_pipe = StableDiffusionSAGPipeline.from_pipe(pipe)

from_pretrained[[diffusers.DiffusionPipeline.from_pretrained]]

from_pretrained(pretrained_model_name_or_path: str | os.PathLike, **kwargs)

ソース

パラメータ:

pretrained_model_name_or_path (str または os.PathLike、任意) : 以下のいずれかです。 - Hub にホストされている事前学習済みパイプラインの repo id（例: CompVis/ldm-text2im-large-256）を表す文字列。 - save_pretrained() を使用して保存されたパイプラインの重みを格納した ディレクトリ（例: ./my_pipeline_directory/）へのパス。

dtype (torch.dtype または dict[str, Union[str, torch.dtype]]、省略可) : デフォルトの torch.dtype を上書きし、別の dtype でモデルを読み込みます。異なる dtype でサブモデルを読み込む場合は、dict を渡します（例: {'transformer': torch.bfloat16, 'vae': torch.float16}）。指定されていないコンポーネントのデフォルト dtype は default で設定します（例: {'transformer': torch.bfloat16, 'default': torch.float16}）。コンポーネントが指定されておらず、デフォルトも設定されていない場合は、torch.float32 が使用されます。

custom_pipeline (str, 任意) : > [!WARNING] > 🧪 これは実験的な機能であり、将来変更される可能性があります。 以下のいずれかになります。 - Hub にホストされているカスタムパイプラインの repo id（例: hf-internal-testing/diffusers-dummy-pipeline）を示す文字列。リポジトリには、カスタムパイプラインを定義する pipeline.py というファイルが含まれている必要があります。 - GitHub の Community 配下にホストされているコミュニティパイプラインの ファイル名を示す文字列。有効なファイル名は、パイプラインスクリプトではなくファイル名と一致する必要があります（clip_guided_stable_diffusion.py ではなく clip_guided_stable_diffusion）。コミュニティパイプラインは、常に GitHub の現在の main ブランチから読み込まれます。 - カスタムパイプラインを含むディレクトリへのパス（./my_pipeline_directory/）。ディレクトリには、カスタムパイプラインを定義する pipeline.py というファイルが含まれている必要があります。 カスタムパイプラインの読み込みと作成の詳細については、カスタムパイプラインの読み込みと追加 をご覧ください。

force_download (bool, 任意, デフォルトは False) : モデルの重みと設定ファイルの(再)ダウンロードを強制するかどうか。キャッシュされたバージョンが存在する場合でも、それを上書きします。

cache_dir (Union[str, os.PathLike]、任意) : 標準のキャッシュを使用しない場合、ダウンロードした事前学習済みモデルの構成がキャッシュされるディレクトリのパス。

proxies (Dict[str, str], 省略可) : プロトコルまたはエンドポイントごとに使用するプロキシサーバーの辞書です。例えば、{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'} のように指定します。これらのプロキシは、各リクエストで使用されます。

output_loading_info(bool, optional, デフォルトは False) : 欠落キー、予期しないキー、エラーメッセージを含む辞書を返すかどうか。

local_files_only (bool、任意、デフォルトはFalse) : ローカルのモデルの重みと設定ファイルのみを読み込むかどうかを指定します。Trueに設定すると、モデルは Hub からダウンロードされません。

token (str または bool、省略可能) : リモートファイルの HTTP ベアラ認証に使用するトークン。True の場合、diffusers-cli login で生成されたトークン（~/.huggingface に保存）が使用されます。

revision (str、任意、デフォルトは"main") : 使用する特定のモデルバージョンです。ブランチ名、タグ名、コミット ID、または Git で許可されている任意の識別子を使用できます。

custom_revision (str, 任意) : 使用する特定のモデルバージョンです。Hubからカスタムパイプラインを読み込む場合のrevisionと同様に、ブランチ名、タグ名、またはコミットIDを指定できます。デフォルトでは、最新の安定版の🤗 Diffusersが使用されます。

mirror (str, 任意) : 中国でモデルをダウンロードする場合、アクセシビリティの問題を解決するためのミラーソースを指定します。ソースの鮮度や安全性は保証されませんので、詳細についてはミラーサイトをご参照ください。

device_map (str, 任意) : パイプラインの各コンポーネントを利用可能なデバイスに配置する方法を指定する戦略です。現在サポートされているのは "balanced" device_map のみです。詳細は こちら をご覧ください。

max_memory (Dict, 省略可) : 最大メモリに対するデバイスの識別子の辞書です。未設定の場合、各 GPU の利用可能な最大メモリと、利用可能な CPU RAM がデフォルトとして使用されます。

offload_folder (str または os.PathLike、省略可能) : "disk" が device_map に含まれる場合の、重みのオフロード先パス。

offload_state_dict (bool, 任意) : Trueの場合、CPU state dictの重みとチェックポイントの最大のシャードの合計がCPU RAMに収まらない場合に、CPU RAMの枯渇を避けるため、CPU state dictを一時的にハードドライブにオフロードします。ディスクオフロードが存在する場合、デフォルトはTrueです。

low_cpu_mem_usage (bool、任意、torch のバージョンが 1.9.0 以上ならデフォルトは True、それ未満なら False) : 重みの初期化を行わず、事前学習済み重みのみを読み込むことでモデルの読み込みを高速化します。また、モデルの読み込み時に CPU メモリ（ピークメモリを含む）をモデルサイズの 1 倍以下に抑えるよう試みます。PyTorch 1.9.0 以上でのみサポートされています。PyTorch の古いバージョンを使用している場合、この引数を True に設定するとエラーが発生します。

use_safetensors (bool、任意、デフォルトはNone) : Noneに設定されている場合、safetensors の重みが利用可能であり、かつ safetensors ライブラリがインストールされている場合に、safetensors の重みがダウンロードされます。Trueに設定されている場合、モデルは強制的に safetensors の重みから読み込まれます。Falseに設定されている場合、safetensors の重みは読み込まれません。

use_onnx (bool、任意、デフォルトはNone) : Trueに設定すると、ONNXの重みが存在する場合、常にダウンロードされます。Falseに設定すると、ONNXの重みはダウンロードされません。デフォルトではuse_onnxは_is_onnxクラス属性の値をデフォルトとし、非ONNXパイプラインではFalse、ONNXパイプラインではTrueになります。ONNXの重みには、.onnxおよび.pbで終わるファイルの両方が含まれます。

kwargs (残りのキーワード引数の辞書、任意) : 読み込みおよび保存可能な変数（特定の pipeline クラスの pipeline コンポーネント）を上書きするために使用できます。上書きされたコンポーネントは、pipeline の __init__ メソッドに直接渡されます。詳細は以下の例を参照してください。

variant (str, 任意) : "fp16" や "ema" のような指定されたバリアントファイル名から重みを読み込みます。

disable_mmap ('bool', optional, デフォルトは 'False') : Safetensors モデルの読み込み時に mmap を無効にするかどうかを指定します。モデルがネットワークマウントやハードドライブ上にあり、mmap のランダムアクセス（seek）を適切に処理できない可能性がある場合、このオプションを有効にするとパフォーマンスが向上することがあります。

事前学習済みのパイプライン重みから、PyTorchの拡散パイプラインをインスタンス化します。

パイプラインはデフォルトで評価モード(model.eval())に設定されます。

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

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.

> プライベートモデルやgatedモデルを使用するには、ログインしてください hf > auth login を使用します。

例:

>>> from diffusers import DiffusionPipeline

>>> # Download pipeline from huggingface.co and cache.
>>> pipeline = DiffusionPipeline.from_pretrained("CompVis/ldm-text2im-large-256")

>>> # Download pipeline that requires an authorization token
>>> # For more information on access tokens, please refer to this section
>>> # of the documentation](https://huggingface.co/docs/hub/security-tokens)
>>> pipeline = DiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")

>>> # Use a different scheduler
>>> from diffusers import LMSDiscreteScheduler

>>> scheduler = LMSDiscreteScheduler.from_config(pipeline.scheduler.config)
>>> pipeline.scheduler = scheduler

maybe_free_model_hooks[[diffusers.DiffusionPipeline.maybe_free_model_hooks]]

maybe_free_model_hooks()

ソース

以下の処理を実行するメソッドです：

• すべてのコンポーネントをオフロードします。
• enable_model_cpu_offload を使用した際に追加されたすべてのモデルフックを削除し、その後、それらを再度適用します。モデルがオフロードされていない場合、この関数は何もしません。
• register_hook() で追加された場合、denoiser コンポーネントの状態付き diffusers フックをリセットします。

enable_model_cpu_offload を適用した際に正しく機能するように、この関数をパイプラインの __call__ 関数の末尾に追加してください。

numpy_to_pil[[diffusers.DiffusionPipeline.numpy_to_pil]]

numpy_to_pil(images)

ソース

NumPyの画像または画像のバッチをPIL画像に変換します。

remove_all_hooks[[diffusers.DiffusionPipeline.remove_all_hooks]]

remove_all_hooks()

ソース

enable_sequential_cpu_offload または enable_model_cpu_offload を使用して追加されたすべてのフックを削除します。

reset_device_map[[diffusers.DiffusionPipeline.reset_device_map]]

reset_device_map()

ソース

デバイスマップ（存在する場合）を None にリセットします。

save_pretrained[[diffusers.DiffusionPipeline.save_pretrained]]

save_pretrained(save_directory: str | os.PathLike, safe_serialization: bool = True, variant: str | None = None, max_shard_size: int | str | None = None, push_to_hub: bool = False, use_flashpack: bool = False, **kwargs)

ソース

パラメータ:

save_directory (str または os.PathLike) : パイプラインを保存するディレクトリ。存在しない場合は作成されます。

safe_serialization (bool、任意、デフォルトはTrue) : モデルをsafetensorsで保存するか、pickleを用いた従来の PyTorch の方法で保存するかどうかを指定します。

variant (str, 任意) : 指定した場合、重みはpytorch_model.<variant>.binの形式で保存されます。

max_shard_size (int または str、デフォルトは None) : シャーディングされる前のチェックポイントの最大サイズ。シャーディングされた各チェックポイントのサイズは、このサイズ未満になります。文字列で指定する場合は、数字の後に単位（"5GB" など）を付ける必要があります。整数で指定する場合は、単位はバイトです。なお、diffusers の最新バージョンへのアップグレードをユーザーに促すため、この制限は一定期間後に引き下げられます（2024年10月から開始）。これは、Hugging Face エコシステム内の異なるライブラリ（transformers や accelerate など）で、この引数のデフォルトサイズを統一するためのものです。

push_to_hub (bool、任意、デフォルトはFalse) : モデルを保存した後、Hugging Face モデルハブにプッシュするかどうかを指定します。プッシュ先のリポジトリはrepo_idで指定できます（save_directoryの名前がデフォルトとして使用されます）。

kwargs (Dict[str, Any]、省略可) : push_to_hub() メソッドに渡される追加のキーワード引数。

パイプラインの保存可能なすべての変数をディレクトリに保存します。クラスが保存メソッドと読み込みメソッドの両方を実装している場合、そのパイプライン変数は保存および読み込みが可能です。パイプラインは、from_pretrained()クラスメソッドを使用して簡単に再読み込みできます。

diffusers.StableDiffusionMixin.enable_freeu[[diffusers.StableDiffusionMixin.enable_freeu]]

diffusers.StableDiffusionMixin.enable_freeu(s1: float, s2: float, b1: float, b2: float)

ソース

パラメータ:

s1 (float) : ステージ1におけるスキップ特徴の寄与を減衰させるためのスケーリング係数です。これは、強化されたノイズ除去プロセスにおける「過剰平滑化効果」を緩和するために使用されます。

s2 (float) : ステージ2におけるスキップ特徴の寄与を減衰させるためのスケーリング係数です。これは、強化されたノイズ除去プロセスにおける「過剰平滑化効果」を緩和するために使用されます。

b1 (float) : ステージ1のスケール係数。バックボーン特徴の寄与を強調するために使用します。

b2 (float) : ステージ2のスケール係数。バックボーン特徴の寄与を強調するために使用します。

https://huggingface.co/papers/2309.11497 に記載されている FreeU メカニズムを有効にします。

スケーリング係数の後ろの接尾辞は、それらが適用されるステージを表しています。

Stable Diffusion v1、v2、Stable Diffusion XL などの異なるパイプラインで良好に動作することが確認されている値の組み合わせについては、公式リポジトリを参照してください。

diffusers.StableDiffusionMixin.disable_freeu[[diffusers.StableDiffusionMixin.disable_freeu]]

diffusers.StableDiffusionMixin.disable_freeu()

ソース

有効化されている場合、FreeUメカニズムを無効にします。

PushToHubMixin[[diffusers.utils.PushToHubMixin]]

diffusers.utils.PushToHubMixin[[diffusers.utils.PushToHubMixin]]

diffusers.utils.PushToHubMixin()

ソース

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

push_to_hub[[diffusers.utils.PushToHubMixin.push_to_hub]]

push_to_hub(repo_id: str, commit_message: str | None = None, private: bool | None = None, token: str | None = None, create_pr: bool = False, safe_serialization: bool = True, variant: str | None = None, subfolder: str | None = None)

ソース

パラメータ:

repo_id (str) : モデル、スケジューラ、またはパイプラインのファイルをプッシュするリポジトリの名前です。組織にプッシュする場合は、組織名を含める必要があります。repo_id はローカルディレクトリへのパス也可以是。

commit_message (str, 任意) : push 時にコミットするメッセージ。デフォルトは "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")

コールバック[[diffusers.callbacks.PipelineCallback]]

diffusers.callbacks.PipelineCallback[[diffusers.callbacks.PipelineCallback]]

diffusers.callbacks.PipelineCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)

ソース

パイプラインで使用されるすべての公式コールバックの基底クラスです。このクラスは、カスタムコールバックを実装するための構造を提供し、すべてのコールバックが一貫したインターフェースを持つことを保証します。

以下を実装してください: tensor_inputs: これは、あなたのコールバックに固有のテンソル入力のリストを返す必要があります。パイプラインクラスの ._callback_tensor_inputs 属性にリストされている変数のみを包含できます。 callback_fn: このメソッドは、あなたのコールバックのコア機能を定義します。

diffusers.callbacks.SDCFGCutoffCallback[[diffusers.callbacks.SDCFGCutoffCallback]]

diffusers.callbacks.SDCFGCutoffCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)

ソース

Stable Diffusion パイプライン用のコールバック関数。cutoff_step_ratio または cutoff_step_index で設定された一定のステップ数に達した後、このコールバックは CFG を無効にします。

注: このコールバックは、cutoffステップ以降に_guidance_scale属性を0.0に変更することで、パイプラインを変更します。

diffusers.callbacks.SDXLCFGCutoffCallback[[diffusers.callbacks.SDXLCFGCutoffCallback]]

diffusers.callbacks.SDXLCFGCutoffCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)

ソース

ベースの Stable Diffusion XL パイプライン用のコールバック関数です。cutoff_step_ratio または cutoff_step_index で設定された一定のステップ数に達した後、このコールバックは CFG を無効にします。

注: このコールバックは、cutoffステップ以降に_guidance_scale属性を0.0に変更することで、パイプラインを変更します。

diffusers.callbacks.SDXLControlnetCFGCutoffCallback[[diffusers.callbacks.SDXLControlnetCFGCutoffCallback]]

diffusers.callbacks.SDXLControlnetCFGCutoffCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)

ソース

Controlnet Stable Diffusion XL パイプライン用のコールバック関数。cutoff_step_ratio または cutoff_step_index で設定された一定のステップ数に達した後、このコールバックは CFG を無効にします。

注: このコールバックは、cutoffステップ以降に_guidance_scale属性を0.0に変更することで、パイプラインを変更します。

diffusers.callbacks.IPAdapterScaleCutoffCallback[[diffusers.callbacks.IPAdapterScaleCutoffCallback]]

diffusers.callbacks.IPAdapterScaleCutoffCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)

ソース

IPAdapterMixin を継承するすべてのパイプライン用のコールバック関数です。cutoff_step_ratio または cutoff_step_index で設定された一定のステップ数に達した後、このコールバックは IP Adapter のスケールを 0.0 に設定します。

注: このコールバックは、cutoffステップ後にスケールを0.0に設定することで、IP Adapterのattentionプロセッサを変更します。

diffusers.callbacks.SD3CFGCutoffCallback[[diffusers.callbacks.SD3CFGCutoffCallback]]

diffusers.callbacks.SD3CFGCutoffCallback(cutoff_step_ratio = 1.0, cutoff_step_index = None)

ソース

Stable Diffusion 3 パイプライン用のコールバック関数。cutoff_step_ratio または cutoff_step_index で設定された一定のステップ数に達した後、このコールバックは CFG を無効にします。

注: このコールバックは、cutoffステップ以降に_guidance_scale属性を0.0に変更することで、パイプラインを変更します。