diffusers/main/ja/api/modular_diffusers/pipeline_components.md

コンポーネントと設定

ComponentSpec[[diffusers.ComponentSpec]]

diffusers.ComponentSpec[[diffusers.ComponentSpec]]

diffusers.ComponentSpec(name: str | None = None, type_hint: typing.Optional[typing.Type] = None, description: str | None = None, config: diffusers.configuration_utils.FrozenDict | None = None, pretrained_model_name_or_path: str | list[str] | None = None, subfolder: str | None = '', variant: str | None = None, revision: str | None = None, default_creation_method: typing.Literal['from_config', 'from_pretrained'] = 'from_pretrained', repo: str | list[str] | None = None)

ソース

パラメータ:

name : コンポーネントの名前

type_hint : コンポーネントの型（例: UNet2DConditionModel）

description : コンポーネントの任意の説明

config : init の作成に使用する任意の設定辞書

pretrained_model_name_or_path : from_pretrained による生成に使用する、任意の pretrained_model_name_or_path パス

subfolder : pretrained_model_name_or_path 内の任意のサブフォルダ

variant : pretrained_model_name_or_path の任意のバリアント

revision : pretrained_model_name_or_path の任意のリビジョン

default_creation_method : 推奨される作成方法 - "from_config" または "from_pretrained"

パイプラインコンポーネントの仕様。

コンポーネントは2つの方法で作成できます。

1. 設定辞書を使用して__init__でゼロから
2. from_pretrained を使用して

作成[[diffusers.ComponentSpec.create]]

create(config: diffusers.configuration_utils.FrozenDict | dict[str, typing.Any] | None = None, **kwargs)

ソース

config を使用して from_config でコンポーネントを作成します。

decode_load_id[[diffusers.ComponentSpec.decode_load_id]]

decode_load_id(load_id: str)

ソース

パラメータ:

load_id : デコードする load_id 文字列。形式: "pretrained_model_name_or_path|subfolder|variant|revision"。None の値は "null" で表されます。

戻り値:

読み込みフィールド名とその値をマッピングする辞書。例: { "pretrained_model_name_or_path": "path/to/repo", "subfolder": "subfolder", "variant": "variant", "revision": "revision" } セグメントの値が "null" の場合、None に置き換えられます。load_id が "null" の場合は None を返します（コンポーネントが load メソッドで生成されなかったことを示します）。

load_id 文字列を読み取りフィールドと値の辞書に復号します。

from_component[[diffusers.ComponentSpec.from_component]]

from_component(name: str, component: Any)

ソース

パラメータ:

name : コンポーネントの名前

component : spec を作成するためのコンポーネントオブジェクト

戻り値:

ComponentSpec オブジェクト

例外: ValueError

• ValueError -- コンポーネントがサポートされていない場合（例: load_id がない nn.Module、ConfigMixin ではない場合）

Component から ComponentSpec を作成します。

現在サポートしているもの:

• ComponentSpec.load()メソッドで作成されたコンポーネント
• ConfigMixin のサブクラスでありながら nn.Module ではないコンポーネント（スケジューラやガイダーなど）

load[[diffusers.ComponentSpec.load]]

load(**kwargs)

ソース

from_pretrained を使用してコンポーネントを読み込みます。

loading_fields[[diffusers.ComponentSpec.loading_fields]]

loading_fields()

ソース

すべての読み込み関連フィールド（つまり、field.metadata["loading"]がTrueであるもの）の名前を返します。

ConfigSpec[[diffusers.ConfigSpec]]

diffusers.ConfigSpec[[diffusers.ConfigSpec]]

diffusers.ConfigSpec(name: str, default: Any, description: str | None = None)

ソース

パイプライン設定パラメータの仕様。

ComponentsManager[[diffusers.ComponentsManager]]

diffusers.ComponentsManager[[diffusers.ComponentsManager]]

diffusers.ComponentsManager()

ソース

複数のパイプラインにまたがるモデルコンポーネントの中央レジストリおよび管理システム。

ComponentsManager は、異なるモジュラーパイプライン間でモデルのコンポーネント（UNet、VAE、テキストエンコーダーなど）を登録、追跡、再利用するための統一的な方法を提供します。重複検出、メモリ管理、コンポーネントの整理といった機能が含まれています。

> これは実験的な機能であり、将来変更される可能性があります。

例:

from diffusers import ComponentsManager

# Create a components manager
cm = ComponentsManager()

# Add components
cm.add("unet", unet_model, collection="sdxl")
cm.add("vae", vae_model, collection="sdxl")

# Enable auto offloading
cm.enable_auto_cpu_offload()

# Retrieve components
unet = cm.get_one(name="unet", collection="sdxl")

追加[[diffusers.ComponentsManager.add]]

add(name: str, component: Any, collection: str | None = None)

ソース

パラメータ:

name (str) : コンポーネントの名前

component (Any) : 追加するコンポーネント

collection (str | None) : コンポーネントを追加するコレクション

戻り値: str

Pythonの組み込みのオブジェクト固有識別子であるid(component)を"{name}_{id(component)}"の形式で生成した、固有のコンポーネントID

ComponentsManager にコンポーネントを追加します。

disable_auto_cpu_offload[[diffusers.ComponentsManager.disable_auto_cpu_offload]]

disable_auto_cpu_offload()

ソース

すべてのコンポーネントに対して、CPUへの自動オフロードを無効にします。

enable_auto_cpu_offload[[diffusers.ComponentsManager.enable_auto_cpu_offload]]

enable_auto_cpu_offload(device: str | int | torch.device = None, memory_reserve_margin = '3GB', offload_strategy = None)

ソース

パラメータ:

device (str | int | torch.device) : モデルを移動してフォワードパスを実行するデバイス

memory_reserve_margin (str) : 使用するメモリリザーブマージン。デフォルトは3GBです。これは、モデル実行中にメモリ不足を避けるためにデバイス上で空きとして確保しておくメモリ量です（中間アクティベーション、勾配など）。

offload_strategy : (hooks, model_id, model, execution_device) -> hooks というシグネチャを持つ任意の呼び出し可能オブジェクト。読み込まれるモデルの前にオフロードする常駐モデルを返します。デフォルトは AutoOffloadStrategy で、最小限の十分な組み合わせを解放します。

すべてのコンポーネントに対して、CPU オフロードの自動有効化を有効にします。

アルゴリズムは次のように動作します:

1. すべてのモデルはデフォルトでCPUから起動します
2. モデルのフォワードパスが呼び出されると、実行デバイスに移動されます
3. メモリが不足している場合、デバイス上の他のモデルはCPUに移動されます
4. システムは、十分なメモリを解放できる最小のモデルの組み合わせをオフロードしようとします
5. モデルは、別のモデルがメモリを必要としてメモリを解放するよう強制されるまで、実行デバイス上に保持されます

グループオフロードされたモデルはこれに参加しますが、自分自身を配置します。他のモデルを退避させることでスペースを確保することはできますが、他のモデルのために退避させられることはありません。どちらの順序でも問題ありません。この機能を有効にする前にグループオフロードを行うか、後にグループオフロードを行うかのどちらでも構いません。AutoOffloadStrategy はモデルのメモリフットプリントに基づいて判断を決定しますが、これは一度に1つのグループを保持しているモデルを説明するものではないため、ワークフローに基づいて判断する offload_strategy を渡してください。

get_components_by_ids[[diffusers.ComponentsManager.get_components_by_ids]]

get_components_by_ids(ids: list[str], return_dict_with_names: bool | None = True)

ソース

パラメータ:

ids (list[str]) : コンポーネントIDのリスト

return_dict_with_names (bool | None) : コンポーネント名をキーとする辞書を返すかどうか:

戻り値: dict[str, Any]

コンポーネントの辞書。

• return_dict_with_names=True の場合、キーはコンポーネント名になります。
• If return_dict_with_names=False, keys are component IDs.

例外: ValueError

• ValueError -- If duplicate component names are found in the search results when return_dict_with_names=True

IDのリストでコンポーネントを取得します。

get_components_by_names[[diffusers.ComponentsManager.get_components_by_names]]

get_components_by_names(names: list[str], collection: str | None = None)

ソース

パラメータ:

names (list[str]) : コンポーネント名のリスト

collection (str | None) : 絞り込み用の任意のコレクション

戻り値: dict[str, Any]

コンポーネント名をキーとするコンポーネントの辞書

例外: ValueError

• ValueError -- 検索結果に重複するコンポーネント名が見つかった場合

名前の一覧でコンポーネントを取得します。必要に応じて、コレクションでフィルタリングできます。

get_ids[[diffusers.ComponentsManager.get_ids]]

get_ids(names: str | list[str] = None, collection: str | None = None)

ソース

パラメータ:

names (str | list[str]) : コンポーネント名のリスト

collection (str | None) : 絞り込み用の任意のコレクション

戻り値: list[str]

コンポーネントIDのリスト

…

get_model_info[[diffusers.ComponentsManager.get_model_info]]

get_model_info(component_id: str, fields: str | list[str] | None = None)

ソース

パラメータ:

component_id (str) : 情報取得対象のコンポーネント名

fields (str | list[str] | None) : 返すフィールド。単一のフィールドの場合は文字列、複数の場合はフィールドのリストを指定できます。None の場合、available_info_fields の設定を使用します。

戻り値:

要求されたコンポーネントのメタデータを含む辞書。fieldsが指定されている場合、そのフィールドのみを返します。それ以外の場合は、すべてのフィールドを返します。

コンポーネントに関する包括的な情報を取得します。

get_one[[diffusers.ComponentsManager.get_one]]

get_one(component_id: str | None = None, name: str | None = None, collection: str | None = None, load_id: str | None = None)

ソース

パラメータ:

component_id (str | None) : 取得するオプションのコンポーネントID

name (str | None) : コンポーネント名またはパターン

collection (str | None) : 絞り込み用の任意のコレクション

load_id (str | None) : 絞り込み用の任意の load_id

戻り値:

単一のコンポーネント

例外: ValueError

• ValueError -- コンポーネントが一致しない場合、または複数のコンポーネントが一致する場合

次のいずれかの方法で、単一のコンポーネントを取得します:

• 検索名（パターンマッチング）、コレクション、または load_id。
• component_id を渡す 複数のコンポーネントが一致した場合、または該当するコンポーネントが見つからなかった場合は、エラーを発生させます。

削除[[diffusers.ComponentsManager.remove]]

remove(component_id: str = None)

ソース

パラメータ:

component_id (str) : 削除するコンポーネントのID

ComponentsManagerからコンポーネントを削除します。

remove_from_collection[[diffusers.ComponentsManager.remove_from_collection]]

remove_from_collection(component_id: str, collection: str)

ソース

コレクションからコンポーネントを削除します。

search_components[[diffusers.ComponentsManager.search_components]]

search_components(names: str | None = None, collection: str | None = None, load_id: str | None = None, return_dict_with_names: bool = True)

ソース

パラメータ:

names : コンポーネント名またはパターン パターン: - "unet" : 基本名が "unet" のコンポーネントに一致 (例: unet_123abc) - "!unet" : 基本名が "unet" のコンポーネントを除くすべて - "unet*" : 基本名が "unet" で始まるものすべて - "!unet*" : 基本名が "unet" で始まらないものすべて - "unet" : 基本名に "unet" を含むものすべて - "!unet" : 基本名に "unet" を含まないものすべて - "refiner|vae|unet" : 基本名が "refiner"、"vae"、または "unet" に完全一致するものすべて - "!refiner|vae|unet" : 基本名が "refiner"、"vae"、または "unet" に完全一致しないものすべて - "unet*|vae*" : 基本名が "unet" で始まるか、"vae" で始まるものすべて

collection : 絞り込み用の任意のコレクション

load_id : 絞り込み用の任意の load_id

return_dict_with_names True の場合、コンポーネント名をキーとする辞書を返します。同名のコンポーネントが複数見つかった場合はエラーをスローします。 False の場合、コンポーネント ID をキーとする辞書を返します。

戻り値:

Dictionary mapping component names to components if return_dict_with_names=True, or a dictionary mapping component IDs to components if return_dict_with_names=False

名前の単純なパターンマッチングでコンポーネントを検索します。必要に応じて、collectionまたはload_idでフィルタリングできます。

set_offload_strategy[[diffusers.ComponentsManager.set_offload_strategy]]

set_offload_strategy(offload_strategy)

ソース

パラメータ:

offload_strategy : シグネチャが (hooks, model_id, model, execution_device) -> hooks である任意の呼び出し可能オブジェクト: デバイス上に現在存在するモデルの hooks を受け取り、読み込まれるモデルの前にオフロードすべき hooks を返します。デフォルトは AutoOffloadStrategy で、最小限の十分な組み合わせを解放します。

管理対象のすべてのモデルでオフロード戦略を置き換えます。CPU オートオフロードが有効な場合のみ有効です。

InsertableDict[[diffusers.modular_pipelines.InsertableDict]]

diffusers.modular_pipelines.InsertableDict[[diffusers.modular_pipelines.InsertableDict]]

ソース