Buckets:

hf-doc-build
/

doc

Files

xet

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

mishig

2 days ago

preview code

download

raw

5.23 kB

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

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

## 自动文档字符串

模块化流水线块是可组合的——你可以将它们嵌套、按顺序串联，并自由地重新排列。它们的文档字符串遵循相同的模式。当 [SequentialPipelineBlocks](/docs/diffusers/v0.43.0/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` 等常用参数。有关可用模板名称的完整列表，请参阅源代码。

Xet Storage Details

Size:: 5.23 kB
Xet hash:: b11573e706029457eb55d53ccbf26c6cc6885f1babaa3b86cc29ba66d47de954

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

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

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

	## 自动文档字符串

	模块化流水线块是可组合的——你可以将它们嵌套、按顺序串联，并自由地重新排列。它们的文档字符串遵循相同的模式。当 [SequentialPipelineBlocks](/docs/diffusers/v0.43.0/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` 等常用参数。有关可用模板名称的完整列表，请参阅源代码。