ディフュージョンパイプライン (Diffusion Pipelines)

Hugging Face Diffusion Pipeline ノードを使用するためのセットアップ手順

このノードを完全に機能させるには、Hugging Face アカウントの開設、アクセストークンの発行、および必要なモデルのインストールが必要です。詳細は Hugging Face 連携ガイドを参照してください。

概要 (What are they?)

Diffusion Pipeline システムは、効率的な画像生成を実現するために連携する 2 つの相補的なノードで構成されています：

Diffusion Pipeline Builder: 複数の実行ノード間で再利用できるように 🤗 Diffusers パイプラインを構築・キャッシュ
Generate Image (Diffusion Pipeline): キャッシュされたパイプラインを使用して画像を生成

このモジュール式アプローチにより、パイプラインの設定を 1 回行うだけで何度も再利用でき、パフォーマンスとリソース効率が大幅に向上します。動的パラメータを通じて、広範なプロバイダーおよびモデルをサポートします。

サポートされているプロバイダー (Supported Providers)

Diffusion Pipeline Builder は、複数の AI モデルプロバイダーをサポートしています：

Flux: 高品質な Text-to-Image 生成
Qwen: マルチモーダル機能
Stable Diffusion: 人気のオープンソース拡散モデル群
Allegro: 動画生成機能
Amused: 効率的なマスク画像モデリング
AudioLDM: テキストからの音声生成
WAN: 特化型画像生成
Wuerstchen: 効率的なディフュージョンアーキテクチャ
Custom: カスタムパイプライン設定および自身で用意したモデルのサポート

使用する場面 (When would I use it?)

以下のような場面でこれらのノードを使用します：

多様なモデルアーキテクチャを使用してテキスト記述から画像を生成したい場合
クリエイティブなプロジェクトに高度な画像生成モデルを活用したい場合
異なるプロバイダーやモデル構成を試行・実験したい場合
キャッシュされたパイプラインを複数の生成処理で再利用してパフォーマンスを最適化したい場合
音声、動画、マルチモーダル生成に特化したモデルを利用したい場合

使い方 (How to use it)

基本セットアップ

Diffusion Pipeline システムは 2 ノード連携ワークフローを採用しています：

ビルダーの設定:
- ワークフローに "Diffusion Pipeline Builder" ノードを追加します
- 希望するプロバイダー（Flux, Stable Diffusion など）を選択します
- プロバイダー固有のパラメータ（モデル、LoRA、最適化設定）を設定します
- ビルダーを実行してパイプラインをキャッシュします
画像の生成:
- "Generate Image (Diffusion Pipeline)" ノードを追加します
- ビルダーノードのパイプライン出力をランタイムノードに接続します
- 生成パラメータ（プロンプト、解像度、ステップ数など）を設定します
- ランタイムノードを実行して画像を生成します

Pipeline Builder パラメータ

ビルダーノードには、選択したプロバイダーに応じて動的に変化するパラメータがあります：

provider: サポートされているプロバイダーから選択（Flux, Stable Diffusion など）
プロバイダー固有パラメータ: モデル選択、LoRA 設定、最適化設定
pipeline: キャッシュされたパイプライン設定を含む出力接続

ランタイムパラメータ (Runtime Parameters)

ランタイムノードのパラメータは、接続されたパイプラインに基づいて動的に生成されます：

pipeline: ビルダーノードからの入力接続
動的生成パラメータ: プロンプト、解像度、推論ステップ数、ガイダンススケール
output_image: 生成された画像（ImageArtifact）
seed: 乱数生成用の整数シード値
logs: 生成プロセスの詳細ログ

動的パラメータ (Dynamic Parameters)

両ノードとも、選択内容に応じて自動調整される動的パラメータを使用しています。プロバイダーの変更や異なるパイプラインの接続を行うと、利用可能なパラメータが即座に切り替わります。

高度な機能 (Advanced Features)

パイプラインキャッシュ: 構築されたパイプラインは設定ハッシュによってキャッシュされ、効率的に再利用されます
LoRA サポート: モデルのカスタマイズのために LoRA アダプタをロード・設定可能
最適化オプション: パフォーマンス向上のための各種最適化トグルを装備
リアルタイムプレビュー: 生成中の中間画像プレビュー（推論速度が低下する場合があります）
接続の保持: パイプライン変更時も、一致するパラメータ接続を自動的に維持

手動メモリ設定 (Manual Memory Settings)

Diffusion Pipeline Builder では、デフォルトで memory_optimization_strategy が Manual に設定されています。Automatic モードは非常に保守的であり、モデルを収めるために必要なすべての最適化を一括で有効化してしまうため、ハイスペックな GPU の性能を制限し生成速度を落としてしまうためです。Manual モードではきめ細やかな調整が可能ですが、🤗 Diffusers メモリ最適化の概念に対する理解が必要です。

以下に各手動パラメータの詳細とトレードオフを解説します：

`attention_slicing`

機能: Attention 演算を一度に行わず逐次的なスライスに分割して計算し、ピーク時の VRAM 使用量を抑えます。
トレードオフ: メモリを節約できますが、速度が低下します（通常 5〜20% 遅延）。
有効化の目安: 生成中にメモリ不足（OOM）エラーが発生した場合（特に 8GB 未満の VRAM の GPU、64GB 未満の Apple Silicon、CPU 実行時）。余裕がある場合は OFF にしておきます。

`vae_slicing`

機能: VAE 潜在変数を単一テンソルではなくバッチスライスに分割してデコードします。
トレードオフ: VAE デコード時のピークメモリを大幅に削減できます。速度低下はごくわずかです。
有効化の目安: 1 つのバッチで複数画像を生成する場合や、高解像度デコード時に最終ステップで VRAM が枯渇する場合。常時有効にしておいて問題ありません。

`transformer_layerwise_casting`

機能: Transformer（または UNet）の重みを fp8（float8_e4m3fn）で保持し、計算時のみ各レイヤーを bfloat16 にアップキャストします。
トレードオフ: bfloat16 と比較して重みのメモリ使用量を約半減させますが、レイヤーごとのキャストによるわずかな速度低下とモデルによっては若干の画質低下が生じます。
有効化の目安: 重みを圧縮しないと VRAM に収まらないが、完全な量子化は避けたい場合。

`cpu_offload_strategy`

機能: パイプラインコンポーネントを CPU RAM と GPU VRAM の間で動的に退避・ロードし、常駐 GPU メモリを削減します。
選択肢:
- None: すべてのコンポーネントが GPU 上に常駐。最速ですが最大量の VRAM が必要。
- Model: 一度に 1 つのサブモデル（テキストエンコーダー、Transformer、VAE など）のみを GPU に配置し、他は CPU RAM に退避。適度な VRAM 節約、適度な速度低下。
- Sequential: レイヤー単位で nn.Module をオンデマンドで GPU にストリーミング。最大の VRAM 節約効果が得られますが、大幅に遅くなります（数倍遅延）。
使い分け:
- 余裕がある場合は None
- 数 GB 足りない場合は Model
- 他の方法ではロードすらできないモデルを動かす最後の手段として Sequential

`quantization_mode`

機能: 推論前に optimum-quanto を介して重みを fp8, int8, または int4 に量子化します。
トレードオフ: 劇的なメモリ削減（int4 は bfloat16 の約 1/4）が得られますが、ビット幅を下げるほど画質低下のリスクが高まります。初回実行時に量子化のオーバーヘッドが発生します。
有効化の目安: オフロードを行ってもモデルが収まらない場合や、他のタスク（大容量バッチ、追加 LoRA）のために VRAM を空けたい場合。通常は fp8 から試すことを推奨します。

メモリ不足（OOM）が発生した場合の推奨ステップ

以下の順序で 1 つずつノブを段階的に有効化してください： vae_slicing を有効化 → attention_slicing を有効化 → cpu_offload_strategy を Model に変更 → transformer_layerwise_casting を有効化 → quantization_mode を下げる（fp8 → int8 → int4） → cpu_offload_strategy を Sequential に変更。

判断に迷った場合: Automatic に切り替え

Automatic モードは、検出されたデバイス上でモデルを動作させるために必要な最適化のみを自動判定して適用します。手動でチューニングした場合よりも速度は控えめになりますが、確実に動作させたい場合の安全な選択肢となります。

パフォーマンスの最適化 (Performance Optimization)

パイプラインの再利用: 1 つのビルダーに複数のランタイムノードを接続し、1 回のビルドで複数回の生成を行う
キャッシュ管理: パイプラインはワークフローの実行間で自動的にキャッシュ・再利用されます
メモリ管理: ご使用のハードウェアに合わせてビルダーの最適化設定を適切に構成する
プレビュー設定: 生成速度を優先する場合は中間プレビューを無効化する

よくある問題 (Common Issues)

API キーの未設定: Hugging Face API トークンが HUGGINGFACE_HUB_ACCESS_TOKEN として設定されているか確認してください（手順はガイドを参照）
パイプラインが見つからない: キャッシュエラーが表示される場合は、ビルダーノードが事前に正常実行されているか確認してください
メモリ制約: 大型モデルや高解像度生成には十分な GPU メモリが必要です
プロバイダーの互換性: 選択したモデルが指定のパイプライン種別と互換性があることを確認してください