IP-Adapter

IP-Adapterは、画像で拡散モデルをプロンプトできる軽量なアダプターです。この手法では、画像特徴とテキスト特徴のクロスアテンション層を分離します。画像特徴は画像エンコーダーから生成されます。

IP-Adapterのチェックポイントと画像を読み込んで使用する方法は、IP-Adapterガイドを参照してください。

IPAdapterMixin

class diffusers.loaders.IPAdapterMixin

< source >

( )

IP Adapterを処理するためのMixin。

load_ip_adapter

< source >

パラメータ

pretrained_model_name_or_path_or_dict (str または list[str] または os.PathLike または list[os.PathLike] または dict または list[dict]) — 以下のいずれかです:
- Hub にホストされている事前学習済みモデルの model id（例: google/ddpm-celebahq-256）を表す文字列。
- ./my_model_directory のように、ModelMixin.save_pretrained() で保存されたモデルの重みを含むディレクトリへのパス。
- torch state dictです。
subfolder (str または list[str]) — Hub またはローカル上のより大きなモデルリポジトリ内でのモデルファイルのサブフォルダの場所です。リストが渡される場合、weight_name と同じ長さである必要があります。
weight_name (str または list[str]) — 読み込む重みファイルの名前です。リストが渡される場合、その長さは subfolder と同じである必要があります。
image_encoder_folder (str, 任意、デフォルトは image_encoder) — Hub またはローカル上のより大きなモデルリポジトリ内における、画像エンコーダーのサブフォルダーの場所です。画像エンコーダーを読み込まない場合は None を渡します。画像エンコーダーが subfolder 内のフォルダーにある場合、画像エンコーダーの重みを格納しているフォルダーの名前のみを渡す必要があります。例えば、image_encoder_folder="image_encoder" のようにします。画像エンコーダーが subfolder 以外のフォルダーにある場合、画像エンコーダーの重みを格納しているフォルダーへのパスを渡す必要があります。例えば、image_encoder_folder="different_subfolder/image_encoder" のようにします。
cache_dir (str | os.PathLike, 任意) — 標準のキャッシュを使用しない場合、ダウンロードした事前学習モデルの構成がキャッシュされるディレクトリのパス。
force_download (bool、任意、デフォルトは False) — モデルの重みおよび設定ファイルを（再）ダウンロードすることを強制するかどうか。キャッシュされたバージョンが存在する場合でも、それらを無視してダウンロードします。
proxies (dict[str, str]、省略可) — プロトコルまたはエンドポイントごとに使用するプロキシサーバーの辞書です。例えば、{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'} のように指定します。各リクエストでこれらのプロキシが使用されます。
local_files_only (bool、任意、デフォルトは False) — ローカルのモデル重みと設定ファイルのみを読み込むかどうかを指定します。True に設定すると、モデルは Hub からダウンロードされません。
token (str または bool、省略可能) — リモートファイルの HTTP ベアラ認証に使用するトークンです。True の場合、diffusers-cli login で生成されたトークン（~/.huggingface に保存されています）が使用されます。
revision (str、任意、デフォルトは"main") — 使用する特定のモデルのバージョンです。ブランチ名、タグ名、コミット ID、または Git によって許可される任意の識別子を使用できます。
low_cpu_mem_usage (bool、任意、torch のバージョンが 1.9.0 以上の場合デフォルトは True、それ以外の場合は False) — 重みの初期化を行わず、事前学習済み重みのみを読み込むことで、モデルの読み込みを高速化します。また、モデルの読み込み中に CPU メモリ（ピークメモリを含む）をモデルサイズの 1 倍以下に抑えるよう試みます。PyTorch 1.9.0 以上でのみサポートされています。PyTorch の古いバージョンを使用している場合、この引数を True に設定するとエラーが発生します。

set_ip_adapter_scale

< source >

( scale )

IP-Adapterのスケーリングをトランスフォーマーブロックごとに設定します。入力scaleは単一の設定または設定のリストであり、各IP-Adapterの動作を細かく制御できます。設定は浮動小数点数または辞書です。

例:

# To use original IP-Adapter
scale = 1.0
pipeline.set_ip_adapter_scale(scale)

# To use style block only
scale = {
    "up": {"block_0": [0.0, 1.0, 0.0]},
}
pipeline.set_ip_adapter_scale(scale)

# To use style+layout blocks
scale = {
    "down": {"block_2": [0.0, 1.0]},
    "up": {"block_0": [0.0, 1.0, 0.0]},
}
pipeline.set_ip_adapter_scale(scale)

# To use style and layout from 2 reference images
scales = [{"down": {"block_2": [0.0, 1.0]}}, {"up": {"block_0": [0.0, 1.0, 0.0]}}]
pipeline.set_ip_adapter_scale(scales)

unload_ip_adapter

< source >

( )

IP Adapterの重みをアンロードします

例:

>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.unload_ip_adapter()
>>> ...

SD3IPAdapterMixin

クラス diffusers.loaders.SD3IPAdapterMixin

< source >

( )

StableDiffusion 3 IP Adapterの処理を担うMixinです。

is_ip_adapter_active

< source >

( ) → bool

戻り値

bool

IP-Adapterが読み込まれており、いずれかのレイヤーのscaleが0より大きい場合にTrueになります。

IP-Adapterが読み込まれており、scaleが0より大きいかどうかを確認します。

IP-Adapter scaleは、画像プロンプトとテキストプロンプトの相対的な影響度を制御します。この値が0に設定されている場合、画像コンテキストは無関係になります。

load_ip_adapter

< source >

( pretrained_model_name_or_path_or_dict: str | dict[str, torch.Tensor]weight_name: str = 'ip-adapter.safetensors'subfolder: str | None = Noneimage_encoder_folder: str | None = 'image_encoder'**kwargs )

パラメータ

pretrained_model_name_or_path_or_dict (str または os.PathLike または dict) — 以下のいずれかです:
- Hub にホストされている事前学習済みモデルの model id（例: google/ddpm-celebahq-256）を表す文字列。
- ./my_model_directory のように、ModelMixin.save_pretrained() で保存されたモデルの重みを含むディレクトリへのパス。
- torch state dictです。
weight_name (str、デフォルト値は “ip-adapter.safetensors”) — 読み込む重みファイルの名前です。リストが渡される場合、その長さは subfolder と同じである必要があります。
subfolder (str, 任意) — Hub またはローカル上のより大きなモデルリポジトリ内でのモデルファイルのサブフォルダの場所です。リストが渡される場合、weight_name と同じ長さである必要があります。
image_encoder_folder (str, 任意、デフォルトは image_encoder) — Hub またはローカル上のより大きなモデルリポジトリ内における、画像エンコーダーのサブフォルダーの場所です。画像エンコーダーを読み込まない場合は None を渡します。画像エンコーダーが subfolder 内のフォルダーにある場合、画像エンコーダーの重みを格納しているフォルダーの名前のみを渡す必要があります。例えば、image_encoder_folder="image_encoder" のようにします。画像エンコーダーが subfolder 以外のフォルダーにある場合、画像エンコーダーの重みを格納しているフォルダーへのパスを渡す必要があります。例えば、image_encoder_folder="different_subfolder/image_encoder" のようにします。
cache_dir (str | os.PathLike, 任意) — 標準のキャッシュを使用しない場合、ダウンロードした事前学習モデルの構成がキャッシュされるディレクトリのパス。
force_download (bool、任意、デフォルトは False) — モデルの重みおよび設定ファイルを（再）ダウンロードすることを強制するかどうか。キャッシュされたバージョンが存在する場合でも、それらを無視してダウンロードします。
proxies (dict[str, str]、省略可) — プロトコルまたはエンドポイントごとに使用するプロキシサーバーの辞書です。例えば、{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'} のように指定します。各リクエストでこれらのプロキシが使用されます。
local_files_only (bool、任意、デフォルトは False) — ローカルのモデル重みと設定ファイルのみを読み込むかどうかを指定します。True に設定すると、モデルは Hub からダウンロードされません。
token (str または bool、省略可能) — リモートファイルの HTTP ベアラ認証に使用するトークンです。True の場合、diffusers-cli login で生成されたトークン（~/.huggingface に保存されています）が使用されます。
revision (str、任意、デフォルトは"main") — 使用する特定のモデルのバージョンです。ブランチ名、タグ名、コミット ID、または Git によって許可される任意の識別子を使用できます。
low_cpu_mem_usage (bool、任意、torch のバージョンが 1.9.0 以上の場合デフォルトは True、それ以外の場合は False) — 重みの初期化を行わず、事前学習済み重みのみを読み込むことで、モデルの読み込みを高速化します。また、モデルの読み込み中に CPU メモリ（ピークメモリを含む）をモデルサイズの 1 倍以下に抑えるよう試みます。PyTorch 1.9.0 以上でのみサポートされています。PyTorch の古いバージョンを使用している場合、この引数を True に設定するとエラーが発生します。

set_ip_adapter_scale

< source >

( scale: float )

パラメータ

scale (float) — 設定する IP-Adapter のスケール。

画像プロンプトの条件付けを制御するIP-Adapterのスケールを設定します。値が1.0の場合、モデルは画像プロンプトのみで条件付けられ、0.0の場合、テキストプロンプトのみで条件付けられます。この値を下げると、モデルにより多様な画像を生成するよう促されますが、画像プロンプトとの整合性が低くなる可能性があります。

例:

>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.set_ip_adapter_scale(0.6)
>>> ...

unload_ip_adapter

< source >

( )

IP Adapterの重みをアンロードします。

例:

>>> # Assuming `pipeline` is already loaded with the IP Adapter weights.
>>> pipeline.unload_ip_adapter()
>>> ...

IPAdapterMaskProcessor

クラス diffusers.IPAdapterMaskProcessor

< source >

( do_resize: bool = Truevae_scale_factor: int = 8resample: str = 'lanczos'do_normalize: bool = Falsedo_binarize: bool = Truedo_convert_grayscale: bool = True )

パラメータ

do_resize (bool、省略可能、デフォルトはTrue) — 画像の (高さ、幅) 次元を vae_scale_factor の倍数に縮小するかどうかを指定します。
vae_scale_factor (int、任意、デフォルトは8) — VAEのスケール係数。do_resizeがTrueの場合、画像はこの係数の倍数に自動的にリサイズされます。
resample (str、任意、デフォルトはlanczos) — 画像のリサイズ時に使用するリサンプリングフィルタ。
do_normalize (bool、省略可能、デフォルトはFalse) — 画像を[-1,1]に正規化するかどうかを指定します。
do_binarize (bool、省略可能、デフォルトはTrue) — 画像を0/1にバイナリ化するかどうかを指定します。
do_convert_grayscale (bool、省略可能、デフォルトはTrue) — 画像をグレースケール形式に変換するかどうかを指定します。

IP Adapterの画像マスク用の画像プロセッサ。

ダウンサンプル

< source >

( mask: Tensorbatch_size: intnum_queries: intvalue_embed_dim: int ) → torch.Tensor

パラメータ

mask (torch.Tensor) — IPAdapterMaskProcessor.preprocess() で生成された入力マスクテンソル。
batch_size (int) — バッチサイズ。
num_queries (int) — クエリの数。
value_embed_dim (int) — バリュー埋め込みの次元数。

戻り値

torch.Tensor

ダウンサンプリングされたマスクテンソル。

指定されたマスクテンソルをダウンサンプリングし、スケーリングドットプロダクトアテンションの期待される次元に一致させます。マスクのアスペクト比が出力画像のアスペクト比と一致しない場合、警告が発行されます。

Update on GitHub

Diffusers

IP-Adapter

IPAdapterMixin

class diffusers.loaders.IPAdapterMixin

load_ip_adapter

set_ip_adapter_scale

unload_ip_adapter

SD3IPAdapterMixin

クラス diffusers.loaders.SD3IPAdapterMixin

is_ip_adapter_active

load_ip_adapter

set_ip_adapter_scale

unload_ip_adapter

IPAdapterMaskProcessor

クラス diffusers.IPAdapterMaskProcessor

ダウンサンプル