diffusers/v0.43.0/ja/modular_diffusers/auto_docstring.md

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

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

自動ドキュメント文字列

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

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

# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...

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

python utils/modular_auto_docstring.py --fix_and_overwrite

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

# 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.
        ...
    """

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

# 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 を直接作成する

from diffusers.modular_pipelines import InputParam

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

テンプレートを使用する

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パラメータを使用して、フィールドをオーバーライドしたり、コンテキストを追加したりできます。

# 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を直接作成する

from diffusers.modular_pipelines import OutputParam

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

テンプレートを使用する

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 で定義されています。prompt、image、num_inference_steps、latents、prompt_embeds などの一般的なパラメータが含まれています。利用可能なテンプレート名の完全なリストについては、ソースを参照してください。