自动文档字符串和参数模板

每个 ModularPipelineBlocks 都有一个 doc 属性，该属性会根据其 description、inputs、intermediate_outputs、expected_components 和 expected_configs 自动生成。自动文档字符串系统可确保文档字符串与该 block 的实际接口保持同步。参数模板为在多个 pipeline 中出现的参数提供标准化的描述。

自动文档字符串

模块化流水线块是可组合的——你可以将它们嵌套、按顺序串联，并自由地重新排列。它们的文档字符串遵循相同的模式。当 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/

如果任何已标记的类缺少文档字符串，该检查将失败并列出需要更新的类。

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 用于定义一个块的输入和输出。您可以直接创建它们，或使用 .template() 来为 prompt、num_inference_steps 或 latents 等常见参数提供标准化的定义。

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 描述一个 block 的单个输出。

字段	类型	描述
`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

自动文档字符串和参数模板