Hugging Face's logo

Diffusers documentation

DiffusionPipeline

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

DiffusionPipeline

Diffusionモデルは、UNetやdiffusion transformer（DiT）、テキストエンコーダー、変分オートエンコーダー（VAE）、スケジューラーといった複数のコンポーネントで構成されています。DiffusionPipelineは、これらのすべてのコンポーネントを単一の使いやすいAPIにまとめつつ、コンポーネントを修正する柔軟性を失いません。

このガイドでは、DiffusionPipelineを読み込む方法について説明します。

パイプラインの読み込み

DiffusionPipelineは、model_index.jsonファイル内のクラス名をスキャンして、QwenImagePipelineなどのモデルのパイプラインサブクラスのインスタンスを自動的に選択して返す、ベースのパイプラインクラスです。

パイプラインを読み込むには、from_pretrained()にモデルIDを渡します。

import torch
from diffusers import DiffusionPipeline

pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

すべてのモデルには、DiffusionPipelineを継承する特定のpipelineサブクラスがあります。サブクラスは通常、狭い焦点を持ち、タスクに特化しています。例として、以下の表を参照してください。

pipeline サブクラスタスク
QwenImagePipelineテキストから画像
QwenImageImg2ImgPipelineimage-to-image
QwenImageInpaintPipelineinpaint

モデルIDをfrom_pretrained()に渡すことで、サブクラスを直接使用できます。

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

単一ファイルモデルの読み込み方法については、Single file formatのドキュメントを参照してください。

ローカルパイプライン

Pipelines はローカルでも実行できます。snapshot_download を使用してモデルリポジトリをダウンロードします。

from huggingface_hub import snapshot_download

local_dir = snapshot_download(repo_id="Qwen/Qwen-Image")

そのパスをfrom_pretrained()に渡して読み込みます。

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  local_dir, dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

from_pretrained() メソッドは、ローカルパスを検出すると、Hub からファイルをダウンロードしません。ただし、これにはモデルに対して行われた更新もダウンロード・キャッシュされないという点も含まれます。

Pipelineのデータ型

dtype 引数を使用して from_pretrained() を呼び出すことで、特定のデータ型でモデルを読み込むことができます。これにより、異なる精度で異なるモデルを読み込むことが可能になります。例えば、大規模な Transformer モデルを半精度で読み込むと、必要なメモリ量を削減できます。

dtype に、各モデルのデータ型を辞書として渡します。default キーを使用して、デフォルトのデータ型を設定します。モデルが辞書に存在せず、default も指定されていない場合、フルプレシション（torch.float32）で読み込まれます。

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype={"transformer": torch.bfloat16, "default": torch.float16},
)
print(pipeline.transformer.dtype, pipeline.vae.dtype)

すべてのモデルを同じデータ型で読み込む場合は、辞書を使用する必要はありません。

import torch
from diffusers import QwenImagePipeline

pipeline = QwenImagePipeline.from_pretrained(
  "Qwen/Qwen-Image", dtype=torch.bfloat16
)
print(pipeline.transformer.dtype, pipeline.vae.dtype)

デバイスの配置

device_map 引数は、パイプラインをデバイスに配置します。実行時において、Diffusers は "balanced"、"cpu"、およびお使いのマシンのアクセラレータ文字列（通常は "cuda"、"mps"、または "xpu"）を受け入れます。

パラメータ説明
accelerator 文字列そのデバイスにパイプラインを配置します。マシンがサポートするアクセラレーター、例えば"cuda"、"mps"、または"xpu"を指定します。
"balanced"パイプラインのコンポーネントを、表示可能な GPU に分散配置します。デバイスごとの上限が必要な場合は、max_memory と併せて使用してください。
"cpu"パイプラインをCPUに配置します。

from_pretrained() の max_memory 引数を使用して、各デバイスで使用するメモリ量の上限を割り当てます。デフォルトでは、Diffusers は利用可能な最大メモリ量を使用します。

import torch
from diffusers import DiffusionPipeline

max_memory = {0: "16GB", 1: "16GB"}
pipeline = DiffusionPipeline.from_pretrained(
  "Qwen/Qwen-Image",
  dtype=torch.bfloat16,
  device_map="balanced",
  max_memory=max_memory,
)

hf_device_map 属性を使用すると、device_map にアクセスして表示できます。

print(pipeline.hf_device_map)
# {'transformer': 1, 'vae': 1, 'text_encoder': 0}

reset_device_map() メソッドを使用して、パイプラインの device_map をリセットします。.to()、enable_sequential_cpu_offload()、enable_model_cpu_offload() のようなメソッドを使用する場合は、この操作が必要です。

pipeline.reset_device_map()

並列読み込み

大規模モデルは、読み込みを容易にするため、多くの場合、より小さなファイルにシャード分割されています。Diffusers は、読み込みプロセスを高速化するために、シャードの並列読み込みをサポートしています。

HF_ENABLE_PARALLEL_LOADING を "YES" に設定すると、シャードの並列読み込みが有効になります。

device_map 引数は、モデルサイズに基づいて大きなメモリ領域を事前確保するために "cuda" に設定する必要があります。これにより、メモリアロケータのウォームアップ時に後続の小さなアロケータ呼び出しを多数回避できるため、モデルの読み込み時間が大幅に短縮されます。

import os
import torch
from diffusers import DiffusionPipeline

os.environ["HF_ENABLE_PARALLEL_LOADING"] = "YES"

pipeline = DiffusionPipeline.from_pretrained(
  "Wan-AI/Wan2.2-I2V-A14B-Diffusers", dtype=torch.bfloat16, device_map="cuda"  # or "mps", "xpu", "cpu"
)

パイプライン内のモデルの置き換え

DiffusionPipelineは柔軟性があり、他のモデルやスケジューラーの読み込みにも対応しています。生成速度や品質の最適化のために異なるスケジューラーを試すことができ、より高性能なモデルに置き換えることもできます。

以下の例では、より安定したVAEのバージョンを使用しています。

import torch
from diffusers import DiffusionPipeline, AutoModel

vae = AutoModel.from_pretrained(
  "madebyollin/sdxl-vae-fp16-fix", dtype=torch.float16
)

pipeline = DiffusionPipeline.from_pretrained(
  "stabilityai/stable-diffusion-xl-base-1.0",
  vae=vae,
  dtype=torch.float16,
  device_map="cuda"  # or "mps", "xpu", "cpu"
)

複数のパイプラインでモデルを再利用する

同じモデルを使用する複数のパイプラインを扱う場合、from_pipe() メソッドにより、モデルを毎回読み込む代わりに再利用できます。これにより、メモリ使用量を増やすことなく複数のパイプラインを使用できます。

メモリ使用量は、パイプラインの数がいくつであっても、最もメモリ要件の高いパイプラインによって決定されます。

The example below loads a pipeline and then loads a second pipeline with from_pipe() to use perturbed-attention guidance (PAG) to improve generation quality.

DiffusionPipeline は PAG をサポートしていないため、AutoPipelineForText2Image を使用してください。詳細については、AutoPipeline のドキュメントを参照してください。

import torch
from diffusers import AutoPipelineForText2Image

pipeline_sdxl = AutoPipelineForText2Image.from_pretrained(
  "stabilityai/stable-diffusion-xl-base-1.0", dtype=torch.float16, device_map="cuda"  # or "mps", "xpu", "cpu"
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
image = pipeline_sdxl(prompt).images[0]
print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB")
# Max memory reserved: 10.47 GB

2番目のパイプラインでenable_pag=Trueを設定してPAGを有効にします。2番目のパイプラインは1番目とモデルの重みを共有するため、使用するメモリ量は同じです。

pipeline = AutoPipelineForText2Image.from_pipe(
  pipeline_sdxl, enable_pag=True
)
prompt = """
cinematic film still of a cat sipping a margarita in a pool in Palm Springs, California
highly detailed, high budget hollywood movie, cinemascope, moody, epic, gorgeous, film grain
"""
image = pipeline(prompt).images[0]
print(f"Max memory reserved: {torch.cuda.max_memory_allocated() / 1024**3:.2f} GB")
# Max memory reserved: 10.47 GB

from_pipe() で作成されたパイプラインは、同じモデルと state を共有します。あるパイプラインでモデルの状態を変更すると、同じモデルを共有する他のすべてのパイプラインにも影響します。

Some methods may not work correctly on pipelines created with from_pipe(). For example, enable_model_cpu_offload() relies on a unique model execution order, which may differ in the new pipeline. To ensure proper functionality, reapply these methods on the new pipeline.

次のステップ

パイプラインが読み込まれた後、通常はデノイジングスケジュールの調整、重み形式の切り替え、またはアダプターの付与を行います。

  • Schedulersでは、デノイジングアルゴリズムの切り替えと設定について説明しています。
  • モデル形式では、GGUF、単一ファイルのチェックポイント、その他の重みのレイアウトについて説明しています。
  • メモリ使用量の削減では、オフローディングやその他のメモリ関連ツールについて説明しています。
  • LoRAでは、パイプラインにアダプターを読み込む方法について説明しています。
  • Legacy checkpointsでは、旧バージョンのStable Diffusionチェックポイント向けのセーフティチェッカーについて説明しています。
Update on GitHub

←コマンドラインインターフェース AutoPipeline→