Buckets:

hf-doc-build
/

doc

Files

xet

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

mishig

about 10 hours ago

preview code

download

raw

11.4 kB

## Mellon에서 사용자 정의 블록 사용

[Mellon](https://github.com/cubiq/Mellon)은 Modular Diffusers와 통합되는 시각적 워크플로 인터페이스로, 노드 기반 워크플로를 위해 설계되었습니다.

> [!WARNING]
> Mellon은 초기 개발 단계에 있으며 아직 프로덕션 사용에 적합하지 않습니다. 이 내용을 통합이 어떻게 작동하는지에 대한 미리보기로 생각해 주세요!

Mellon에서는 커스텀 블록이 기본적으로 작동합니다 - 저장소에 `mellon_pipeline_config.json`만 추가하면 됩니다. 이 설정 파일은 Mellon이 블록의 매개변수를 UI 컴포넌트로 렌더링하는 방법을 알려줍니다.

[Gemini Prompt Expander](https://huggingface.co/diffusers/gemini-prompt-expander-mellon) 블록을 사용한 실제 동작은 다음과 같습니다:

![Mellon custom block demo](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/modular_demo_dynamic.gif)

Mellon에서 모듈형 diffusers 커스텀 블록을 사용하려면:
1. ModularDiffusers 섹션에서 **Dynamic Block Node**를 드래그합니다
2. `repo_id`를 입력하세요 (예: `diffusers/gemini-prompt-expander-mellon`)
3. **커스텀 블록 로드**를 클릭하세요
4. 노드는 블록의 입력과 출력을 표시하도록 변환됩니다

자신만의 커스텀 블록에 대해 이 config를 생성하는 방법을 살펴보겠습니다.

## Mellon 설정을 만드는 단계

1. **파라미터에 Mellon 유형 지정** - 각 `InputParam`/`OutputParam`에는 Mellon이 어떤 UI 컴포넌트를 렌더링할지 알려주는 유형(예: `"textbox"`, `"dropdown"`, `"image"`)이 필요합니다.
2. **`mellon_pipeline_config.json` 생성** - 유틸리티를 사용하여 설정 템플릿을 생성하고 Hub 저장소에 푸시합니다.
3. **(선택 사항) config 수동 조정** - 특정 요구 사항에 맞게 생성된 config를 세밀하게 조정합니다.

## 매개변수에 대한 Mellon 유형 지정

Mellon 타입은 각 파라미터가 UI에서 어떻게 렌더링되는지를 결정합니다. 파라미터의 타입을 지정하지 않으면 `"custom"`로 기본 설정되며, 이는 단순한 연결 점으로 렌더링됩니다. 생성된 config에서 나중에 언제든지 이 값을 조정할 수 있습니다.

| 유형 | 입력/출력 | 설명 |
|------|--------------|-------------|
| `image` | 둘 다 | 이미지 (PIL Image) |
| `video` | 둘 다 | Video |
| `text` | 둘 다 | 텍스트 표시 |
| `textbox` | 입력 | 텍스트 입력 |
| `dropdown` | 입력 | 드롭다운 선택 메뉴 |
| `slider` | 입력 | 숫자 값을 위한 슬라이더 |
| `number` | 입력 | 숫자 입력 |
| `checkbox` | 입력 | Boolean 토글 |

추가 구성이 필요한 파라미터(옵션이 있는 드롭다운, min/max 값이 있는 슬라이더 등)의 경우, 문자열 대신 `MellonParam` 인스턴스를 직접 전달합니다. 아래 클래스 메서드 중 하나를 사용하거나, `MellonParam(name, label, type, ...)`으로 완전히 사용자 정의된 인스턴스를 생성할 수 있습니다.

| 메서드 | 설명 |
|--------|-------------|
| `MellonParam.Input.image(name)` | 이미지 입력 |
| `MellonParam.Input.textbox(name, default)` | textarea로 텍스트 입력 |
| `MellonParam.Input.dropdown(name, options, default)` | 드롭다운 선택 |
| `MellonParam.Input.slider(name, default, min, max, step)` | 숫자 값을 위한 슬라이더 |
| `MellonParam.Input.number(name, default, min, max, step)` | 숫자 입력 (슬라이더 없음) |
| `MellonParam.Input.seed(name, default)` | randomize 버튼으로 시드 입력 |
| `MellonParam.Input.checkbox(name, default)` | Boolean 체크박스 |
| `MellonParam.Input.model(name)` | diffusers 구성 요소의 모델 입력 |
| `MellonParam.Output.image(name)` | 이미지 출력 |
| `MellonParam.Output.video(name)` | 비디오 출력 |
| `MellonParam.Output.text(name)` | 텍스트 출력 |
| `MellonParam.Output.model(name)` | diffusers 구성 요소의 모델 출력 |

Mellon 유형을 지정하려면 아래 방법 중 하나를 선택하세요.

### `metadata`를 블록 정의에 사용하는 방법

사용자가 처음부터 커스텀 블록을 정의하는 경우, `metadata={"mellon": "<type>"}`을 `InputParam` 및 `OutputParam` 정의에 직접 추가하세요. Hub의 기존 커스텀 블록을 편집하는 경우, 로컬로 다운로드하는 방법은 [커스텀 블록 편집](./custom_blocks#editing-custom-blocks)을 참고하세요.

```python
class GeminiPromptExpander(ModularPipelineBlocks):
    
    @property
    def inputs(self) -> List[InputParam]:
        return [
            InputParam(
                "prompt",
                type_hint=str,
                required=True,
                description="Prompt to use",
                metadata={"mellon": "textbox"},  # Text input
            )
        ]
    
    @property
    def intermediate_outputs(self) -> List[OutputParam]:
        return [
            OutputParam(
                "prompt",
                type_hint=str,
                description="Expanded prompt by the LLM",
                metadata={"mellon": "text"},  # Text output
            ),
            OutputParam(
                "old_prompt",
                type_hint=str,
                description="Old prompt provided by the user",
<CopyLLMTxtMenu containerStyle="float: inline-end; margin-inline-start: 10px; display: inline-flex; position: relative; z-index: 10;"></CopyLLMTxtMenu>
                # No metadata - we don't want to render this in UI
            )
        ]
```

UI 구성에 대한 완전한 제어를 위해 `MellonParam` 인스턴스를 직접 전달합니다:
```python
from diffusers.modular_pipelines.mellon_node_utils import MellonParam
InputParam(
    "mode",
    type_hint=str,
    default="balanced",
    metadata={"mellon": MellonParam.Input.dropdown("mode", options=["fast", "balanced", "quality"])},
)
```

### `input_types`와 `output_types`를 사용하여 설정 생성

기존 파이프라인을 사용 중이거나 블록 정의를 깔끔하게 유지하기를 원한다면, `input_types/output_types` 인수를 사용하여 설정을 생성할 때 유형을 지정하세요:
```python
from diffusers.modular_pipelines.mellon_node_utils import MellonPipelineConfig
mellon_config = MellonPipelineConfig.from_custom_block(
    blocks,
    input_types={"prompt": "textbox"},
    output_types={"prompt": "text"}
)
```

> [!NOTE]
> `metadata`와 `input_types`/`output_types`가 모두 지정된 경우, 인수가 `metadata`를 덮어씁니다.

## Mellon 설정을 생성하고 push합니다

블록에 메타데이터를 추가한 후, 기본 Mellon 구성 템플릿을 생성하여 Hub에 push합니다:

```python
from diffusers import ModularPipelineBlocks
from diffusers.modular_pipelines.mellon_node_utils import MellonPipelineConfig
# load your custom blocks from your local dir
blocks = ModularPipelineBlocks.from_pretrained("/path/local/folder", trust_remote_code=True)
# Generate the default config template
mellon_config = MellonPipelineConfig.from_custom_block(blocks)
# push the default template to `repo_id`, you will need to pass the same local folder path so that it will save the config locally first
mellon_config.save(
    local_dir="/path/local/folder",
    repo_id= repo_id,
    push_to_hub=True
)
```

이 작업은 저장소에 `mellon_pipeline_config.json` 파일을 생성합니다.

## config 검토 및 조정

생성된 템플릿은 시작점일 뿐이며, 필요에 맞게 조정할 수 있습니다. Gemini Prompt Expander의 생성된 설정을 함께 살펴보겠습니다:

```json
{
  "label": "Gemini Prompt Expander",
  "default_repo": "",
  "default_dtype": "",
  "node_params": {
    "custom": {
      "params": {
        "prompt": {
          "label": "Prompt",
          "type": "string",
          "display": "textarea",
          "default": ""
        },
        "out_prompt": {
          "label": "Prompt",
          "type": "string",
          "display": "output"
        },
        "old_prompt": {
          "label": "Old Prompt",
          "type": "custom",
          "display": "output"
        },
        "doc": {
          "label": "Doc",
          "type": "string",
          "display": "output"
        }
      },
      "input_names": ["prompt"],
      "model_input_names": [],
      "output_names": ["out_prompt", "old_prompt", "doc"],
      "block_name": "custom",
      "node_type": "custom"
    }
  }
}
```

### 구조 이해하기

`params` 딕셔너리는 각 UI 요소가 어떻게 렌더링되는지 정의합니다. `input_names`, `model_input_names`, `output_names` 목록은 이러한 UI 요소를 [ModularPipelineBlocks](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks)의 I/O 인터페이스에 매핑합니다:

| Mellon 설정 | ModularPipelineBlocks |
|---------------|----------------------|
| `input_names` | `inputs` 속성 |
| `model_input_names` | `expected_components` 속성 |
| `output_names` | `intermediate_outputs` 속성 |

이 예시에서: `prompt`가 유일한 입력입니다. 모델 구성 요소는 없으며, 출력에는 `out_prompt`, `old_prompt`, `doc`가 포함됩니다.

이제 `params` 딕셔너리를 살펴보겠습니다:

- **`prompt`**: `display: "textarea"` (텍스트 입력 박스로 렌더링됨), `label: "Prompt"` (UI에 표시됨), `default: ""` (빈 상태로 시작)를 가진 입력 매개변수입니다. Mellon에서 `type: "string"` 필드는 어떤 노드끼리 연결될 수 있는지를 결정하기 때문에 중요합니다. 동일한 타입끼리만 "noodles"로 연결할 수 있습니다.

- **`out_prompt`**: 확장된 프롬프트 출력입니다. 입력과 출력이 동일한 이름(`prompt`)을 공유하므로 설정에서 이름 충돌을 피하기 위해 `out_` 접두사가 자동으로 추가되었습니다. `display: "output"`를 가지고 있어 출력 소켓으로 렌더링됩니다.
- **`old_prompt`**: 메타데이터를 지정하지 않았기 때문에 `type: "custom"`입니다. UI에서는 단순한 점으로 표시됩니다. 실제로 UI에 노출할 의도가 없으므로 제거할 수 있습니다.
- **`doc`**: 문서 출력으로, 모든 커스텀 블록에 자동으로 추가됩니다.
### 조절하기
더 이상 사용하지 않으므로 `old_prompt`를 `params`와 `output_names` 양쪽에서 제거하세요.
```json
{
  "label": "Gemini Prompt Expander",
  "default_repo": "",
  "default_dtype": "",
  "node_params": {
    "custom": {
      "params": {
        "prompt": {
          "label": "Prompt",
          "type": "string",
          "display": "textarea",
          "default": ""
        },
        "out_prompt": {
          "label": "Prompt",
          "type": "string",
          "display": "output"
        },
        "doc": {
          "label": "Doc",
          "type": "string",
          "display": "output"
        }
      },
      "input_names": ["prompt"],
      "model_input_names": [],
      "output_names": ["out_prompt", "doc"],
      "block_name": "custom",
      "node_type": "custom"
    }
  }
}
```
최종 설정은 [diffusers/gemini-prompt-expander-mellon](https://huggingface.co/diffusers/gemini-prompt-expander-mellon)에서 확인하세요.

Xet Storage Details

Size:: 11.4 kB
Xet hash:: 26304cc1de0668ad17a5ed1ae83a0639d89b27d9d73ba41d3c5af34eb1ac7ab9

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

	## Mellon에서 사용자 정의 블록 사용

	[Mellon](https://github.com/cubiq/Mellon)은 Modular Diffusers와 통합되는 시각적 워크플로 인터페이스로, 노드 기반 워크플로를 위해 설계되었습니다.

	> [!WARNING]
	> Mellon은 초기 개발 단계에 있으며 아직 프로덕션 사용에 적합하지 않습니다. 이 내용을 통합이 어떻게 작동하는지에 대한 미리보기로 생각해 주세요!

	Mellon에서는 커스텀 블록이 기본적으로 작동합니다 - 저장소에 `mellon_pipeline_config.json`만 추가하면 됩니다. 이 설정 파일은 Mellon이 블록의 매개변수를 UI 컴포넌트로 렌더링하는 방법을 알려줍니다.

	[Gemini Prompt Expander](https://huggingface.co/diffusers/gemini-prompt-expander-mellon) 블록을 사용한 실제 동작은 다음과 같습니다:

	![Mellon custom block demo](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/modular_demo_dynamic.gif)

	Mellon에서 모듈형 diffusers 커스텀 블록을 사용하려면:
	1. ModularDiffusers 섹션에서 Dynamic Block Node를 드래그합니다
	2. `repo_id`를 입력하세요 (예: `diffusers/gemini-prompt-expander-mellon`)
	3. 커스텀 블록 로드를 클릭하세요
	4. 노드는 블록의 입력과 출력을 표시하도록 변환됩니다

	자신만의 커스텀 블록에 대해 이 config를 생성하는 방법을 살펴보겠습니다.

	## Mellon 설정을 만드는 단계

	1. 파라미터에 Mellon 유형 지정 - 각 `InputParam`/`OutputParam`에는 Mellon이 어떤 UI 컴포넌트를 렌더링할지 알려주는 유형(예: `"textbox"`, `"dropdown"`, `"image"`)이 필요합니다.
	2. `mellon_pipeline_config.json` 생성 - 유틸리티를 사용하여 설정 템플릿을 생성하고 Hub 저장소에 푸시합니다.
	3. (선택 사항) config 수동 조정 - 특정 요구 사항에 맞게 생성된 config를 세밀하게 조정합니다.

	## 매개변수에 대한 Mellon 유형 지정

	Mellon 타입은 각 파라미터가 UI에서 어떻게 렌더링되는지를 결정합니다. 파라미터의 타입을 지정하지 않으면 `"custom"`로 기본 설정되며, 이는 단순한 연결 점으로 렌더링됩니다. 생성된 config에서 나중에 언제든지 이 값을 조정할 수 있습니다.

	\| 유형 \| 입력/출력 \| 설명 \|
	\|------\|--------------\|-------------\|
	\| `image` \| 둘 다 \| 이미지 (PIL Image) \|
	\| `video` \| 둘 다 \| Video \|
	\| `text` \| 둘 다 \| 텍스트 표시 \|
	\| `textbox` \| 입력 \| 텍스트 입력 \|
	\| `dropdown` \| 입력 \| 드롭다운 선택 메뉴 \|
	\| `slider` \| 입력 \| 숫자 값을 위한 슬라이더 \|
	\| `number` \| 입력 \| 숫자 입력 \|
	\| `checkbox` \| 입력 \| Boolean 토글 \|

	추가 구성이 필요한 파라미터(옵션이 있는 드롭다운, min/max 값이 있는 슬라이더 등)의 경우, 문자열 대신 `MellonParam` 인스턴스를 직접 전달합니다. 아래 클래스 메서드 중 하나를 사용하거나, `MellonParam(name, label, type, ...)`으로 완전히 사용자 정의된 인스턴스를 생성할 수 있습니다.

	\| 메서드 \| 설명 \|
	\|--------\|-------------\|
	\| `MellonParam.Input.image(name)` \| 이미지 입력 \|
	\| `MellonParam.Input.textbox(name, default)` \| textarea로 텍스트 입력 \|
	\| `MellonParam.Input.dropdown(name, options, default)` \| 드롭다운 선택 \|
	\| `MellonParam.Input.slider(name, default, min, max, step)` \| 숫자 값을 위한 슬라이더 \|
	\| `MellonParam.Input.number(name, default, min, max, step)` \| 숫자 입력 (슬라이더 없음) \|
	\| `MellonParam.Input.seed(name, default)` \| randomize 버튼으로 시드 입력 \|
	\| `MellonParam.Input.checkbox(name, default)` \| Boolean 체크박스 \|
	\| `MellonParam.Input.model(name)` \| diffusers 구성 요소의 모델 입력 \|
	\| `MellonParam.Output.image(name)` \| 이미지 출력 \|
	\| `MellonParam.Output.video(name)` \| 비디오 출력 \|
	\| `MellonParam.Output.text(name)` \| 텍스트 출력 \|
	\| `MellonParam.Output.model(name)` \| diffusers 구성 요소의 모델 출력 \|

	Mellon 유형을 지정하려면 아래 방법 중 하나를 선택하세요.

	### `metadata`를 블록 정의에 사용하는 방법

	사용자가 처음부터 커스텀 블록을 정의하는 경우, `metadata={"mellon": "<type>"}`을 `InputParam` 및 `OutputParam` 정의에 직접 추가하세요. Hub의 기존 커스텀 블록을 편집하는 경우, 로컬로 다운로드하는 방법은 [커스텀 블록 편집](./custom_blocks#editing-custom-blocks)을 참고하세요.

	```python
	class GeminiPromptExpander(ModularPipelineBlocks):

	@property
	def inputs(self) -> List[InputParam]:
	return [
	InputParam(
	"prompt",
	type_hint=str,
	required=True,
	description="Prompt to use",
	metadata={"mellon": "textbox"}, # Text input
	)
	]

	@property
	def intermediate_outputs(self) -> List[OutputParam]:
	return [
	OutputParam(
	"prompt",
	type_hint=str,
	description="Expanded prompt by the LLM",
	metadata={"mellon": "text"}, # Text output
	),
	OutputParam(
	"old_prompt",
	type_hint=str,
	description="Old prompt provided by the user",
	<CopyLLMTxtMenu containerStyle="float: inline-end; margin-inline-start: 10px; display: inline-flex; position: relative; z-index: 10;"></CopyLLMTxtMenu>

	# No metadata - we don't want to render this in UI
	)
	]
	```

	UI 구성에 대한 완전한 제어를 위해 `MellonParam` 인스턴스를 직접 전달합니다:
	```python
	from diffusers.modular_pipelines.mellon_node_utils import MellonParam

	InputParam(
	"mode",
	type_hint=str,
	default="balanced",
	metadata={"mellon": MellonParam.Input.dropdown("mode", options=["fast", "balanced", "quality"])},
	)
	```

	### `input_types`와 `output_types`를 사용하여 설정 생성

	기존 파이프라인을 사용 중이거나 블록 정의를 깔끔하게 유지하기를 원한다면, `input_types/output_types` 인수를 사용하여 설정을 생성할 때 유형을 지정하세요:
	```python
	from diffusers.modular_pipelines.mellon_node_utils import MellonPipelineConfig

	mellon_config = MellonPipelineConfig.from_custom_block(
	blocks,
	input_types={"prompt": "textbox"},
	output_types={"prompt": "text"}
	)
	```

	> [!NOTE]
	> `metadata`와 `input_types`/`output_types`가 모두 지정된 경우, 인수가 `metadata`를 덮어씁니다.

	## Mellon 설정을 생성하고 push합니다

	블록에 메타데이터를 추가한 후, 기본 Mellon 구성 템플릿을 생성하여 Hub에 push합니다:

	```python
	from diffusers import ModularPipelineBlocks
	from diffusers.modular_pipelines.mellon_node_utils import MellonPipelineConfig

	# load your custom blocks from your local dir
	blocks = ModularPipelineBlocks.from_pretrained("/path/local/folder", trust_remote_code=True)

	# Generate the default config template
	mellon_config = MellonPipelineConfig.from_custom_block(blocks)
	# push the default template to `repo_id`, you will need to pass the same local folder path so that it will save the config locally first
	mellon_config.save(
	local_dir="/path/local/folder",
	repo_id= repo_id,
	push_to_hub=True
	)
	```

	이 작업은 저장소에 `mellon_pipeline_config.json` 파일을 생성합니다.

	## config 검토 및 조정

	생성된 템플릿은 시작점일 뿐이며, 필요에 맞게 조정할 수 있습니다. Gemini Prompt Expander의 생성된 설정을 함께 살펴보겠습니다:

	```json
	{
	"label": "Gemini Prompt Expander",
	"default_repo": "",
	"default_dtype": "",
	"node_params": {
	"custom": {
	"params": {
	"prompt": {
	"label": "Prompt",
	"type": "string",
	"display": "textarea",
	"default": ""
	},
	"out_prompt": {
	"label": "Prompt",
	"type": "string",
	"display": "output"
	},
	"old_prompt": {
	"label": "Old Prompt",
	"type": "custom",
	"display": "output"
	},
	"doc": {
	"label": "Doc",
	"type": "string",
	"display": "output"
	}
	},
	"input_names": ["prompt"],
	"model_input_names": [],
	"output_names": ["out_prompt", "old_prompt", "doc"],
	"block_name": "custom",
	"node_type": "custom"
	}
	}
	}
	```

	### 구조 이해하기

	`params` 딕셔너리는 각 UI 요소가 어떻게 렌더링되는지 정의합니다. `input_names`, `model_input_names`, `output_names` 목록은 이러한 UI 요소를 [ModularPipelineBlocks](/docs/diffusers/main/ko/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks)의 I/O 인터페이스에 매핑합니다:

	\| Mellon 설정 \| ModularPipelineBlocks \|
	\|---------------\|----------------------\|
	\| `input_names` \| `inputs` 속성 \|
	\| `model_input_names` \| `expected_components` 속성 \|
	\| `output_names` \| `intermediate_outputs` 속성 \|

	이 예시에서: `prompt`가 유일한 입력입니다. 모델 구성 요소는 없으며, 출력에는 `out_prompt`, `old_prompt`, `doc`가 포함됩니다.

	이제 `params` 딕셔너리를 살펴보겠습니다:

	- `prompt`: `display: "textarea"` (텍스트 입력 박스로 렌더링됨), `label: "Prompt"` (UI에 표시됨), `default: ""` (빈 상태로 시작)를 가진 입력 매개변수입니다. Mellon에서 `type: "string"` 필드는 어떤 노드끼리 연결될 수 있는지를 결정하기 때문에 중요합니다. 동일한 타입끼리만 "noodles"로 연결할 수 있습니다.

	- `out_prompt`: 확장된 프롬프트 출력입니다. 입력과 출력이 동일한 이름(`prompt`)을 공유하므로 설정에서 이름 충돌을 피하기 위해 `out_` 접두사가 자동으로 추가되었습니다. `display: "output"`를 가지고 있어 출력 소켓으로 렌더링됩니다.

	- `old_prompt`: 메타데이터를 지정하지 않았기 때문에 `type: "custom"`입니다. UI에서는 단순한 점으로 표시됩니다. 실제로 UI에 노출할 의도가 없으므로 제거할 수 있습니다.

	- `doc`: 문서 출력으로, 모든 커스텀 블록에 자동으로 추가됩니다.

	### 조절하기

	더 이상 사용하지 않으므로 `old_prompt`를 `params`와 `output_names` 양쪽에서 제거하세요.

	```json
	{
	"label": "Gemini Prompt Expander",
	"default_repo": "",
	"default_dtype": "",
	"node_params": {
	"custom": {
	"params": {
	"prompt": {
	"label": "Prompt",
	"type": "string",
	"display": "textarea",
	"default": ""
	},
	"out_prompt": {
	"label": "Prompt",
	"type": "string",
	"display": "output"
	},
	"doc": {
	"label": "Doc",
	"type": "string",
	"display": "output"
	}
	},
	"input_names": ["prompt"],
	"model_input_names": [],
	"output_names": ["out_prompt", "doc"],
	"block_name": "custom",
	"node_type": "custom"
	}
	}
	}
	```

	최종 설정은 [diffusers/gemini-prompt-expander-mellon](https://huggingface.co/diffusers/gemini-prompt-expander-mellon)에서 확인하세요.