# 자동 docstring 및 매개변수 템플릿

모든 [ModularPipelineBlocks](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks)에는 `doc` 속성이 있으며, 이는 해당 블록의 `description`, `inputs`, `intermediate_outputs`, `expected_components`, `expected_configs`에서 자동으로 생성됩니다. 자동 docstring 시스템은 docstring이 블록의 실제 인터페이스와 항상 일치하도록 유지합니다. 파라미터 템플릿은 여러 파이프라인에 걸쳐 나타나는 파라미터에 대해 표준화된 설명을 제공합니다.

## 자동 문서 문자열

모듈형 파이프라인 블록은 조합이 가능합니다. 블록을 중첩하거나, 순서대로 연결하거나, 자유롭게 재배열할 수 있습니다. 이들의 docstring도 동일한 패턴을 따릅니다. [SequentialPipelineBlocks](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_blocks#diffusers.SequentialPipelineBlocks)가 하위 블록의 입력과 출력을 집계할 때, 수동으로 다시 작성하지 않아도 문서가 자동으로 업데이트되어야 합니다.

`# auto_docstring` 마커는 블록의 속성으로부터 docstring을 생성합니다. 클래스 정의 위에 추가하여 해당 클래스에 대한 자동 docstring 생성을 표시합니다.

```py
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...
```

…

```bash
python utils/modular_auto_docstring.py --fix_and_overwrite
```

이 유틸리티는 블록의 `doc` 속성을 읽고 이를 클래스 docstring으로 삽입합니다.

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

표시된 클래스 중 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을 직접 생성하기

```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.")
```

Templates는 `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`은 블록의 단일 출력을 설명합니다.

| 필드 | 유형 | 설명 |
|---|---|---|
| `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`와 같은 일반적인 매개변수를 포함합니다. 사용 가능한 템플릿 이름의 전체 목록은 소스 코드를 참조하세요.