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

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

## 自动文档字符串

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

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

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

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

| 字段 | 类型 | 描述 |
|---|---|---|
| `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` 等常用参数。有关可用模板名称的完整列表，请参阅源代码。