Buckets:

hf-doc-build
/

doc

Files
xet
hf-doc-build/doc / diffusers /main /ja /api /pipelines /overview.md
mishig
about 4 hours ago
preview code
download
raw
55.1 kB
# パイプライン

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

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

> [!WARNING]
> [DiffusionPipeline](/docs/diffusers/main/ja/api/pipelines/overview#diffusers.DiffusionPipeline) クラスは学習には使用しないでください。拡散パイプラインの個別コンポーネント（[UNet2DModel](/docs/diffusers/main/ja/api/models/unet2d#diffusers.UNet2DModel) や [UNet2DConditionModel](/docs/diffusers/main/ja/api/models/unet2d-cond#diffusers.UNet2DConditionModel) など）は通常、個別に学習されるため、それらを直接扱うことをお勧めします。
>
> 
>
> Pipelinesには学習機能は提供されていません。[`torch.no_grad`](https://pytorch.org/docs/stable/generated/torch.no_grad.html)デコレーターで`__call__()`メソッドを装飾しているため、PyTorchのautogradが無効化されていることに気づくでしょう。これは、Pipelinesは学習に使用すべきではないためです。学習について興味がある場合は、代わりに[Training](../../training/overview)ガイドをご覧ください。

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

## DiffusionPipeline[[diffusers.DiffusionPipeline]]

#### diffusers.DiffusionPipeline[[diffusers.DiffusionPipeline]]

```python
diffusers.DiffusionPipeline()
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L198)

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

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

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

クラス属性:

- **config_name** (`str`) -- 拡散パイプラインのすべてのコンポーネントのクラス名とモジュール名を保存する設定ファイルの名前。
- **_optional_components** (`List[str]`) -- パイプラインの動作に必ずしも渡す必要のない、すべてのオプションコンポーネントのリスト（サブクラスでオーバーライドされるべきです）。
#### __call__[[diffusers.DiffusionPipeline.__call__]]
```python
__call__(*args, **kwargs)
```
self を関数として呼び出します。
#### device[[diffusers.DiffusionPipeline.device]]
```python
device()
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L600)
**戻り値:** `torch.device`
パイプラインが配置されている torch デバイスです。コンポーネントが複数のデバイスに分割されている場合（例えば、テキストエンコーダーが CPU にあり、デノイジングのバックボーンがアクセラレーターで実行されている場合）、アクセラレーターデバイスが返されます。
#### へ[[diffusers.DiffusionPipeline.to]]
```python
to(*args, **kwargs)
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L397)
**パラメータ:**
dtype (`torch.dtype`、*任意*) : 指定された[`dtype`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.dtype)を持つパイプラインを返します
device (`torch.Device`, *任意*) : 指定された [`device`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.device) を持つパイプラインを返します
silence_dtype_warnings (`str`、*任意*、デフォルトは`False`) : 対象の`dtype`が対象の`device`と互換性がない場合、警告を省略するかどうか。
**戻り値:** [DiffusionPipeline](/docs/diffusers/main/ja/api/pipelines/overview#diffusers.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).`
> [!TIP] > パイプラインがすでに正しい torch.dtype と torch.device を持っている場合、そのまま返されます。
それ以外の場合、> 返される pipeline は、指定された torch.dtype と torch.device を持つ self のコピーです。
`to`を呼び出す方法には、次のものがあります。
- `to(dtype, silence_dtype_warnings=False) → DiffusionPipeline` は、指定された [`dtype`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.dtype) を持つパイプラインを返します
- `to(device, silence_dtype_warnings=False) → DiffusionPipeline` を呼び出すと、指定した [`device`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.device) を持つパイプラインが返されます。
- `to(device=None, dtype=None, silence_dtype_warnings=False) → DiffusionPipeline` は、指定された [`device`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.device) と [`dtype`](https://pytorch.org/docs/stable/tensor_attributes.html#torch.dtype) を持つパイプラインを返します。
#### コンポーネント[[diffusers.DiffusionPipeline.components]]
```python
components()
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L1907)
`self.components` プロパティは、追加のメモリを再割り当てせずに、同じ重みと設定で異なるパイプラインを実行する際に有用です。
Returns (`dict`): パイプラインの初期化に必要なすべてのモジュールを含む辞書。
例:
```py
>>> 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]]
```python
disable_attention_slicing()
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L2067)
スライスされたアテンションの計算を無効にします。`enable_attention_slicing`が以前に呼び出されていた場合、アテンションは1ステップで計算されます。
#### disable_xformers_memory_efficient_attention[[diffusers.DiffusionPipeline.disable_xformers_memory_efficient_attention]]
```python
disable_xformers_memory_efficient_attention()
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L2006)
[xFormers](https://facebookresearch.github.io/xformers/)からのメモリ効率の高いアテンションを無効にします。
#### ダウンロード[[diffusers.DiffusionPipeline.download]]
```python
download(pretrained_model_name, **kwargs)
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L1483)
**パラメータ:**
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](https://github.com/huggingface/diffusers/tree/main/examples/community) 配下の GitHub にホストされているコミュニティパイプラインの *ファイル名*。有効なファイル名は、パイプラインスクリプトではなくファイル名と一致する必要があります（`clip_guided_stable_diffusion.py` ではなく `clip_guided_stable_diffusion`）。コミュニティパイプラインは、常に GitHub の現在の `main` ブランチから読み込まれます。  - カスタムパイプラインを含む *ディレクトリ*（`./my_pipeline_directory/`）へのパス。そのディレクトリには、カスタムパイプラインを定義する `pipeline.py` というファイルを含む必要があります。  > [!WARNING] > 🧪 これは実験的な機能であり、将来変更される可能性があります。  カスタムパイプラインの読み込みと作成の詳細については、[コミュニティパイプラインの貢献方法](https://huggingface.co/docs/diffusers/main/en/using-diffusers/contribute_pipeline) をご覧ください。
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の拡散パイプラインをダウンロードしてキャッシュします。
> [!TIP] > プライベートモデルや[ゲート付きモデル](https://huggingface.co/docs/hub/models-gated#gated-models)を使用するには、ログインしてください
hf > auth login
#### enable_attention_slicing[[diffusers.DiffusionPipeline.enable_attention_slicing]]
```python
enable_attention_slicing(slice_size: str | int = 'auto')
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L2030)
**パラメータ:**
slice_size (`str` または `int`、*任意*、デフォルトは `"auto"`) : `"auto"` の場合、アテンションヘッドへの入力を半分にし、アテンションを2段階で計算します。`"max"` の場合、一度に1つのスライスのみを実行することで、最大限のメモリを節約します。数値が指定された場合、`attention_head_dim // slice_size` 個のスライスを 사용합니다。この場合、`attention_head_dim` は `slice_size` の倍数である必要があります。

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

> [!WARNING] > ⚠️ `scaled_dot_product_attention`（SDPA）をすでに使用している場合は、attention slicing を有効にしないでください
PyTorch > 2.0 または xFormers から。これらのアテンション計算はすでに非常にメモリ効率が高いため、この機能を有効にする必要はありません。SDPA または xFormers でアテンションスライシングを有効にすると、重大なスローダウンを引き起こす可能性があります!
例:
```py
>>> 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]]
```python
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)
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L1343)
**パラメータ:**
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 公式ドキュメント](https://pytorch.org/docs/stable/generated/torch.Tensor.record_stream.html)を参照してください。
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 デバイス向け）は、データ転送と計算をオーバーラップさせることで、シーケンシャルなオフローディングと比較して全体の実行時間を短縮できる点です。これは、ストリームを用いたレイヤープリフェッチによって有効化されます。具体的には、現在のレイヤーが実行されている間に、次に実行されるレイヤーのオンローディングがアクセラレーターデバイス上で開始される仕組みです。これにより、メモリ要件はわずかに増加します。なお、この実装はリーフレベルのオフローディングにも対応していますが、ストリームを使用すると大幅に高速化されます。
例:
```python
>>> 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]]
```python
enable_model_cpu_offload(gpu_id: int | None = None, device: typing.Union[torch.device, str] = None)
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L1152)
**パラメータ:**
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]]
```python
enable_sequential_cpu_offload(gpu_id: int | None = None, device: typing.Union[torch.device, str] = None)
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L1273)
**パラメータ:**
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]]
```python
enable_xformers_memory_efficient_attention(attention_op: typing.Optional[typing.Callable] = None)
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L1975)
**パラメータ:**
attention_op (`Callable`、*任意*) : xFormers の [`memory_efficient_attention()`](https://facebookresearch.github.io/xformers/components/ops.html#xformers.ops.memory_efficient_attention) 関数の `op` 引数として使用するために、デフォルトの `None` オペレーターをオーバーライドします。

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

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

例:

```py
>>> 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]]

```python
from_pipe(pipeline, **kwargs)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L2083)

**パラメータ:**

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

**戻り値:** `DiffusionPipeline`

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

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

例:

```py
>>> 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]]

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

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L638)

**パラメータ:**

pretrained_model_name_or_path (`str` または `os.PathLike`、*任意*) : 以下のいずれかです。 - Hub にホストされている事前学習済みパイプラインの *repo id*（例: `CompVis/ldm-text2im-large-256`）を表す文字列。 - [save_pretrained()](/docs/diffusers/main/ja/api/pipelines/overview#diffusers.DiffusionPipeline.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](https://github.com/huggingface/diffusers/tree/main/examples/community) 配下にホストされているコミュニティパイプラインの *ファイル名*を示す文字列。有効なファイル名は、パイプラインスクリプトではなくファイル名と一致する必要があります（`clip_guided_stable_diffusion.py` ではなく `clip_guided_stable_diffusion`）。コミュニティパイプラインは、常に GitHub の現在の main ブランチから読み込まれます。 - カスタムパイプラインを含むディレクトリへのパス（`./my_pipeline_directory/`）。ディレクトリには、カスタムパイプラインを定義する `pipeline.py` というファイルが含まれている必要があります。  カスタムパイプラインの読み込みと作成の詳細については、[カスタムパイプラインの読み込みと追加](https://huggingface.co/docs/diffusers/using-diffusers/custom_pipeline_overview) をご覧ください。
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` のみです。詳細は [こちら](https://huggingface.co/docs/diffusers/main/en/tutorials/inference_with_big_models#device-placement) をご覧ください。

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.
```
> [!TIP] > プライベートモデルや[gated](https://huggingface.co/docs/hub/models-gated#gated-models)モデルを使用するには、ログインしてください
`hf > auth login` を使用します。
例:
```py
>>> 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]]
```python
maybe_free_model_hooks()
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L1250)
以下の処理を実行するメソッドです：
- すべてのコンポーネントをオフロードします。
- `enable_model_cpu_offload` を使用した際に追加されたすべてのモデルフックを削除し、その後、それらを再度適用します。モデルがオフロードされていない場合、この関数は何もしません。
- `register_hook()` で追加された場合、denoiser コンポーネントの状態付き diffusers フックをリセットします。
`enable_model_cpu_offload` を適用した際に正しく機能するように、この関数をパイプラインの `__call__` 関数の末尾に追加してください。
#### numpy_to_pil[[diffusers.DiffusionPipeline.numpy_to_pil]]
```python
numpy_to_pil(images)
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L1945)
NumPyの画像または画像のバッチをPIL画像に変換します。
#### remove_all_hooks[[diffusers.DiffusionPipeline.remove_all_hooks]]
```python
remove_all_hooks()
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L1143)
`enable_sequential_cpu_offload` または `enable_model_cpu_offload` を使用して追加されたすべてのフックを削除します。
#### reset_device_map[[diffusers.DiffusionPipeline.reset_device_map]]
```python
reset_device_map()
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L1470)
デバイスマップ（存在する場合）を None にリセットします。
#### save_pretrained[[diffusers.DiffusionPipeline.save_pretrained]]
```python
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)
```
[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L254)
**パラメータ:**

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()](/docs/diffusers/main/ja/api/schedulers/overview#diffusers.utils.PushToHubMixin.push_to_hub) メソッドに渡される追加のキーワード引数。

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

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

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

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L2267)

**パラメータ:**

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 などの異なるパイプラインで良好に動作することが確認されている値の組み合わせについては、[公式リポジトリ](https://github.com/ChenyangSi/FreeU)を参照してください。

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

```python
diffusers.StableDiffusionMixin.disable_freeu()
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L2289)

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

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

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

```python
diffusers.utils.PushToHubMixin()
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/hub_utils.py#L491)

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

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

```python
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)
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/utils/hub_utils.py#L526)

**パラメータ:**

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にアップロードします。

例:

```python
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]]

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

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/callbacks.py#L7)

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

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

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

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

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/callbacks.py#L69)

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

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

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

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

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/callbacks.py#L98)

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

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

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

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

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/callbacks.py#L140)

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

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

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

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

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/callbacks.py#L188)

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

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

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

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

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/callbacks.py#L212)

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

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

Size:: 55.1 kB
Xet hash:: 0f0d3b7a665223068bb20dec3362429240de4a6c4114772266c3ad9c48c67d65
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.