Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /v0.43.0 /ja /modular_diffusers /auto_docstring.md

mishig

2 days ago

preview code

download

raw

6.53 kB

# 自動ドキュメント文字列とパラメータのテンプレート

すべての [ModularPipelineBlocks](/docs/diffusers/v0.43.0/ja/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks) には、`doc` プロパティがあり、これは `description`、`inputs`、`intermediate_outputs`、`expected_components`、および `expected_configs` から自動的に生成されます。自動ドキュメント文字列システムにより、ドキュメント文字列はブロックの実際のインターフェースと常に同期が保たれます。パラメータテンプレートは、多くのパイプラインに共通して出現するパラメータに対して、標準化された説明を提供します。

## 自動ドキュメント文字列

モジュール化されたパイプラインブロックは組み合わせ可能であり、ネストしたり、シーケンスとして連結したり、自由に再配置したりできます。そのドキュメント文字列（docstring）も同じパターンに従います。[SequentialPipelineBlocks](/docs/diffusers/v0.43.0/ja/api/modular_diffusers/pipeline_blocks#diffusers.SequentialPipelineBlocks)がサブブロックからの入力と出力を集約する場合、手動での書き換えなしにドキュメントが自動的に更新されるべきです。

`# auto_docstring` マーカーは、ブロックのプロパティからドキュメント文字列を生成します。クラス定義の上に追加することで、そのクラスを自動ドキュメント文字列生成の対象としてマークします。

```py
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...
```

ドキュメント文字列を生成して挿入するには、次のコマンドを実行します。

```bash
python utils/modular_auto_docstring.py --fix_and_overwrite
```

このユーティリティは、ブロックの`doc`プロパティを読み取り、クラスドキュメント文字列として挿入します。

```py
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    """
    Text input processing step that standardizes text embeddings for the pipeline.
    Inputs:
        prompt_embeds (`torch.Tensor`) *required*:
            text embeddings used to guide the image generation.
        ...
    Outputs:
        prompt_embeds (`torch.Tensor`):
            text embeddings used to guide the image generation.
        ...
    """
```

上書きせずに確認することも、特定のファイルやディレクトリを対象とすることもできます。

```bash
# Check that all marked classes have up-to-date docstrings
python utils/modular_auto_docstring.py
# Check a specific file or directory
python utils/modular_auto_docstring.py src/diffusers/modular_pipelines/flux/
```

マークされたクラスにdocstringが欠けている場合、チェックは失敗し、更新が必要なクラスをリストします。

```
Found the following # auto_docstring markers that need docstrings:
- src/diffusers/modular_pipelines/flux/encoders.py: FluxTextEncoderStep at line 42
Run `python utils/modular_auto_docstring.py --fix_and_overwrite` to fix them.
```

## パラメータテンプレート

`InputParam` と `OutputParam` は、ブロックの入力と出力を定義します。直接作成するか、`prompt`、`num_inference_steps`、`latents` などの一般的なパラメータの標準的な定義には `.template()` を使用します。

### InputParam

`InputParam`は、ブロックへの単一の入力を記述します。

| フィールド | 型 | 説明 |
|---|---|---|
| `name` | `str` | パラメータの名前 |
| `type_hint` | `Any` | 型アノテーション（例: `str`、`torch.Tensor`） |
| `default` | `Any` | デフォルト値（設定されていない場合、パラメータにはデフォルト値がありません） |
| `required` | `bool` | パラメータが必須かどうか |
| `description` | `str` | 人間が読める説明 |
| `kwargs_type` | `str` | 関連するパラメータのグループ名(例:`"denoiser_input_fields"`) |
| `metadata` | `dict` | 任意の追加情報 |

#### InputParam を直接作成する

```py
from diffusers.modular_pipelines import InputParam
InputParam(
    name="guidance_scale",
    type_hint=float,
    default=7.5,
    description="Scale for classifier-free guidance.",
)
```

#### テンプレートを使用する

```py
InputParam.template("prompt")
# Equivalent to:
# InputParam(name="prompt", type_hint=str, required=True,
#            description="The prompt or prompts to guide image generation.")
```

テンプレートは`name`、`type_hint`、`default`、`required`、`description`を自動的に設定します。`note`パラメータを使用して、フィールドをオーバーライドしたり、コンテキストを追加したりできます。

```py
# Override the default value
InputParam.template("num_inference_steps", default=28)
# Add a note to the description
InputParam.template("prompt_embeds", note="batch-expanded")
# description becomes: "text embeddings used to guide the image generation. ... (batch-expanded)"
```

### OutputParam

`OutputParam`は、ブロックからの単一の出力を記述します。

| フィールド | 型 | 説明 |
|---|---|---|
| `name` | `str` | パラメータの名前 |
| `type_hint` | `Any` | 型アノテーション |
| `description` | `str` | 人間が読める説明 |
| `kwargs_type` | `str` | 関連するパラメータのグループ名 |
| `metadata` | `dict` | 任意の追加情報 |

#### OutputParamを直接作成する

```py
from diffusers.modular_pipelines import OutputParam
OutputParam(name="image_latents", type_hint=torch.Tensor, description="Encoded image latents.")
```

#### テンプレートを使用する

```py
OutputParam.template("latents")
# Add a note to the description
OutputParam.template("prompt_embeds", note="batch-expanded")
```

## 利用可能なテンプレート

`INPUT_PARAM_TEMPLATES` と `OUTPUT_PARAM_TEMPLATES` は [modular_pipeline_utils.py](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py) で定義されています。`prompt`、`image`、`num_inference_steps`、`latents`、`prompt_embeds` などの一般的なパラメータが含まれています。利用可能なテンプレート名の完全なリストについては、ソースを参照してください。

Xet Storage Details

Size:: 6.53 kB
Xet hash:: 8f115928f8b9ef43a0d3dae450b88445893359f1ebc7755ce1c678785ea1e406

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	# 自動ドキュメント文字列とパラメータのテンプレート

	すべての [ModularPipelineBlocks](/docs/diffusers/v0.43.0/ja/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks) には、`doc` プロパティがあり、これは `description`、`inputs`、`intermediate_outputs`、`expected_components`、および `expected_configs` から自動的に生成されます。自動ドキュメント文字列システムにより、ドキュメント文字列はブロックの実際のインターフェースと常に同期が保たれます。パラメータテンプレートは、多くのパイプラインに共通して出現するパラメータに対して、標準化された説明を提供します。

	## 自動ドキュメント文字列

	モジュール化されたパイプラインブロックは組み合わせ可能であり、ネストしたり、シーケンスとして連結したり、自由に再配置したりできます。そのドキュメント文字列（docstring）も同じパターンに従います。[SequentialPipelineBlocks](/docs/diffusers/v0.43.0/ja/api/modular_diffusers/pipeline_blocks#diffusers.SequentialPipelineBlocks)がサブブロックからの入力と出力を集約する場合、手動での書き換えなしにドキュメントが自動的に更新されるべきです。

	`# auto_docstring` マーカーは、ブロックのプロパティからドキュメント文字列を生成します。クラス定義の上に追加することで、そのクラスを自動ドキュメント文字列生成の対象としてマークします。

	```py
	# auto_docstring
	class FluxTextEncoderStep(SequentialPipelineBlocks):
	...
	```

	ドキュメント文字列を生成して挿入するには、次のコマンドを実行します。

	```bash
	python utils/modular_auto_docstring.py --fix_and_overwrite
	```

	このユーティリティは、ブロックの`doc`プロパティを読み取り、クラスドキュメント文字列として挿入します。

	```py
	# auto_docstring
	class FluxTextEncoderStep(SequentialPipelineBlocks):
	"""
	Text input processing step that standardizes text embeddings for the pipeline.

	Inputs:
	prompt_embeds (`torch.Tensor`) required:
	text embeddings used to guide the image generation.
	...

	Outputs:
	prompt_embeds (`torch.Tensor`):
	text embeddings used to guide the image generation.
	...
	"""
	```

	上書きせずに確認することも、特定のファイルやディレクトリを対象とすることもできます。

	```bash
	# Check that all marked classes have up-to-date docstrings
	python utils/modular_auto_docstring.py

	# Check a specific file or directory
	python utils/modular_auto_docstring.py src/diffusers/modular_pipelines/flux/
	```

	マークされたクラスにdocstringが欠けている場合、チェックは失敗し、更新が必要なクラスをリストします。

	```
	Found the following # auto_docstring markers that need docstrings:
	- src/diffusers/modular_pipelines/flux/encoders.py: FluxTextEncoderStep at line 42

	Run `python utils/modular_auto_docstring.py --fix_and_overwrite` to fix them.
	```

	## パラメータテンプレート

	`InputParam` と `OutputParam` は、ブロックの入力と出力を定義します。直接作成するか、`prompt`、`num_inference_steps`、`latents` などの一般的なパラメータの標準的な定義には `.template()` を使用します。

	### InputParam

	`InputParam`は、ブロックへの単一の入力を記述します。

	\| フィールド \| 型 \| 説明 \|
	\|---\|---\|---\|
	\| `name` \| `str` \| パラメータの名前 \|
	\| `type_hint` \| `Any` \| 型アノテーション（例: `str`、`torch.Tensor`） \|
	\| `default` \| `Any` \| デフォルト値（設定されていない場合、パラメータにはデフォルト値がありません） \|
	\| `required` \| `bool` \| パラメータが必須かどうか \|
	\| `description` \| `str` \| 人間が読める説明 \|
	\| `kwargs_type` \| `str` \| 関連するパラメータのグループ名(例:`"denoiser_input_fields"`) \|
	\| `metadata` \| `dict` \| 任意の追加情報 \|

	#### InputParam を直接作成する

	```py
	from diffusers.modular_pipelines import InputParam

	InputParam(
	name="guidance_scale",
	type_hint=float,
	default=7.5,
	description="Scale for classifier-free guidance.",
	)
	```

	#### テンプレートを使用する

	```py
	InputParam.template("prompt")
	# Equivalent to:
	# InputParam(name="prompt", type_hint=str, required=True,
	# description="The prompt or prompts to guide image generation.")
	```

	テンプレートは`name`、`type_hint`、`default`、`required`、`description`を自動的に設定します。`note`パラメータを使用して、フィールドをオーバーライドしたり、コンテキストを追加したりできます。

	```py
	# Override the default value
	InputParam.template("num_inference_steps", default=28)

	# Add a note to the description
	InputParam.template("prompt_embeds", note="batch-expanded")
	# description becomes: "text embeddings used to guide the image generation. ... (batch-expanded)"
	```

	### OutputParam

	`OutputParam`は、ブロックからの単一の出力を記述します。

	\| フィールド \| 型 \| 説明 \|
	\|---\|---\|---\|
	\| `name` \| `str` \| パラメータの名前 \|
	\| `type_hint` \| `Any` \| 型アノテーション \|
	\| `description` \| `str` \| 人間が読める説明 \|
	\| `kwargs_type` \| `str` \| 関連するパラメータのグループ名 \|
	\| `metadata` \| `dict` \| 任意の追加情報 \|

	#### OutputParamを直接作成する

	```py
	from diffusers.modular_pipelines import OutputParam

	OutputParam(name="image_latents", type_hint=torch.Tensor, description="Encoded image latents.")
	```

	#### テンプレートを使用する

	```py
	OutputParam.template("latents")

	# Add a note to the description
	OutputParam.template("prompt_embeds", note="batch-expanded")
	```

	## 利用可能なテンプレート

	`INPUT_PARAM_TEMPLATES` と `OUTPUT_PARAM_TEMPLATES` は [modular_pipeline_utils.py](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py) で定義されています。`prompt`、`image`、`num_inference_steps`、`latents`、`prompt_embeds` などの一般的なパラメータが含まれています。利用可能なテンプレート名の完全なリストについては、ソースを参照してください。