# コンポーネントと設定

## ComponentSpec[[diffusers.ComponentSpec]]

#### diffusers.ComponentSpec[[diffusers.ComponentSpec]]

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

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

**パラメータ:**

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

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

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

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

#### decode_load_id[[diffusers.ComponentSpec.decode_load_id]]

```python
decode_load_id(load_id: str)
```

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

**パラメータ:**

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

```python
from_component(name: str, component: Any)
```

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

**パラメータ:**

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

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

**戻り値:**

ComponentSpec オブジェクト

**例外:** ``ValueError``

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

Component から ComponentSpec を作成します。

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

#### load[[diffusers.ComponentSpec.load]]

```python
load(**kwargs)
```

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

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

#### loading_fields[[diffusers.ComponentSpec.loading_fields]]

```python
loading_fields()
```

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

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

## ConfigSpec[[diffusers.ConfigSpec]]

#### diffusers.ConfigSpec[[diffusers.ConfigSpec]]

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

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

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

## ComponentsManager[[diffusers.ComponentsManager]]

#### diffusers.ComponentsManager[[diffusers.ComponentsManager]]

```python
diffusers.ComponentsManager()
```

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

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

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

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

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

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

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

**パラメータ:**

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

```python
disable_auto_cpu_offload()
```

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

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

#### enable_auto_cpu_offload[[diffusers.ComponentsManager.enable_auto_cpu_offload]]

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

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

**パラメータ:**

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

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

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

**パラメータ:**

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

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

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

**パラメータ:**

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

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

**戻り値:** dict[str, Any]

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

**例外:** ``ValueError``

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

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

#### get_ids[[diffusers.ComponentsManager.get_ids]]

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

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

**パラメータ:**

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

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

**戻り値:** list[str]

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

…

#### get_model_info[[diffusers.ComponentsManager.get_model_info]]

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

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

**パラメータ:**

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

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

**戻り値:**

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

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

#### get_one[[diffusers.ComponentsManager.get_one]]

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

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

**パラメータ:**

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

```python
remove(component_id: str = None)
```

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

**パラメータ:**

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

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

#### remove_from_collection[[diffusers.ComponentsManager.remove_from_collection]]

```python
remove_from_collection(component_id: str, collection: str)
```

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

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

#### search_components[[diffusers.ComponentsManager.search_components]]

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

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

**パラメータ:**

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

```python
set_offload_strategy(offload_strategy)
```

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

**パラメータ:**

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

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