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

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

Update on GitHub

Diffusers

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