Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /ko /modular_diffusers /auto_docstring.md

mishig

about 10 hours ago

preview code

download

raw

5.74 kB

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

Xet Storage Details

Size:: 5.74 kB
Xet hash:: 18fc33d313851673151a34104bed69ec0826517ba930298c111608f7a6f3f352

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

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