koriweb
a3f63e56e2
- 10_Wiki/Comfyui/: ComfyUI docs generated via /wikify - 00_Raw/_youtube/: /youtube extraction outputs - Move some 00_Raw originals into 10_Wiki/Topics_meeting; remove empty canvases and stray files Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
105 lines
7.0 KiB
Markdown
105 lines
7.0 KiB
Markdown
---
|
|
id: v3-migration---comfyui
|
|
title: "V3 Migration - ComfyUI"
|
|
category: "10_Wiki/Topics"
|
|
status: "draft"
|
|
verification_status: "conceptual"
|
|
canonical_id: ""
|
|
aliases: []
|
|
duplicate_of: ""
|
|
source_radix: "B"
|
|
confidence_score: 0.8
|
|
created_at: 2026-05-20
|
|
updated_at: 2026-05-20
|
|
review_reason: ""
|
|
merge_history: []
|
|
tags: ["web", "wikify"]
|
|
raw_sources: ["https://docs.comfy.org/custom-nodes/v3_migration"]
|
|
applied_in: []
|
|
github_commit: ""
|
|
---
|
|
|
|
# [[V3 Migration - ComfyUI]]
|
|
|
|
## 🎯 한 줄 통찰 (One-line insight)
|
|
기존 V1(Legacy) 방식의 노드 정의 구조를 객체 중심의 새로운 V3 스키마로 전환하여, 더 체계적이고 확장 가능한 방식으로 마이그레이션하는 가이드.
|
|
|
|
## 🧠 핵심 개념 (Core concepts)
|
|
* **V3 Schema Architecture**: 기존의 딕셔너리 기반 정의에서 벗어나 [[io.Schema]] 객체를 사용하여 입력(Inputs)과 출력(Outputs)을 객체 단위로 정의함.
|
|
* **Class-based Execution**: 실행 메서드가 `execute`라는 이름의 클래 메서드로 고정되며, `comfy_entrypoint`를 통해 확장을 정의함.
|
|
* **Type Safety & Modernization**: `io.Int.Input`, `io.Image.Input` 등 클래스 기반의 타입 정의를 통해 강력한 타입 힌트와 구조화된 스키마 관리를 지원함.
|
|
* **API-driven Extension**: `ComfyExtension` 및 `ComfyAPI`를 사용하여 노드 교체, 진행률 보고, 확장 생명주기를 관리함.
|
|
|
|
## 🧩 추출된 패턴 (Extracted patterns)
|
|
* **V1 to V3 Transformation Pattern**: `INPUT_TYPES` 딕셔너리를 `define_schema` 메서드의 `io.Schema` 객체로 변환하고, `FUNCTION`을 `execute` 클래 메서드로 변경하는 일련의 문법적 전환 패턴.
|
|
* **Inheritance Pattern**: 모든 V3 노드는 반드시 `io.ComfyNode`를 상속받아야 하며, 상위 체인에 이 클래스가 포함되어야 함.
|
|
* **Schema-driven Configuration**: 노드의 ID, 표시 이름, 카테고리, 입출력 정의 등 모든 메타데이터가 하나의 스키마 객체 내로 통합되는 구조.
|
|
|
|
## 📖 세부 내용 (Details)
|
|
|
|
### 1. V3 Migration: 주요 변경 사항 비교
|
|
| 특징 | V1 (Legacy) | V3 (Modern) |
|
|
| :--- | :--- | :--- |
|
|
| **입력/출력 정의** | 딕셔니리(Dictionary) 방식 | 객체(Object) 기반 방식 |
|
|
| **실행 메서드** | `FUNCTION`에 지정된 이름 사용 | `execute`로 고정 (클래 메서드) |
|
|
| **노드 등록** | `NODE_CLASS_MAPPINGS` 사용 | `comfy_entrypoint` 및 `ComfyExtension` 사용 |
|
|
| **상태 관리** | `__init__` 등을 통한 상태 유지 가능성 | 클래 메서드 중심, `state` 노출 없음 |
|
|
|
|
### 2. Migration Steps (마이그레이션 단계)
|
|
* **Step 1: Base Class 변경**: 모든 V3 스키마 노드는 `io.ComfyNode`를 상속받아야 함.
|
|
* **Step 2: INPUT_TYPES를 define_schema로 전환**: `io.Schema` 객체를 반환하도록 구현하며, 입출력을 클래스 기반으로 정의함.
|
|
* **Step 3: Execute 메서드 업데이트**: 실행 함수 이름을 `execute`로 변경하고 클래 메서드로 선언함.
|
|
* **Step 4: 노드 속성 변환**: `RETURN_TYPES`, `CATEGORY`, `FUNCTION` 등의 기존 속성을 `io.Schema` 내의 필드로 재배치함.
|
|
* **Step 5: 특수 메서드 처리**: `validate_inputs` (기존 `VALIDATE_INPUTS`), `fingerprint_inputs` (기존 `IS_CHANGED`) 등 변경된 명칭 적용.
|
|
* **Step 6: Extension 및 Entry Point 생성**: `ComfyExtension` 클래스를 정의하고 `comfy_entrypoint`를 구현함.
|
|
|
|
### 3. Schema Reference (Schema 데이터클래스 필드)
|
|
| 필드 | 타입 | 필수/선택 | 제약·설명 |
|
|
| :--- | :--- | :--- | :--- |
|
|
| node_id | str | 필수 | 노드의 글로벌 고유 ID (충돌 방지를 위해 접두사/접미사 권장) |
|
|
| display_name | str | 선택 | UI에 표시될 이름. 미설정 시 `node_id` 사용 |
|
|
| category | str | 선택 | "Add Node" 메뉴 내 카테록 (예: "sd") |
|
|
| description | str | 선택 | 마우스 호버 시 표시되는 툴팁 |
|
|
| inputs | list[Input] | 선택 | 입력 정의 리스트 |
|
|
| outputs | list[Output] | 선택 | 출력 정의 리스트 |
|
|
| hidden | list[Hidden] | 선택 | 요청할 숨겨진 입력(Hidden Inputs) 리스트 |
|
|
| search_aliases | list[str] | 선택 | 검색을 위한 대체 이름 목록 |
|
|
| is_output_node | bool | 선택 | True일 경우 노드가 출력 노드로 표시됨 |
|
|
| is_input_list | bool | 선택 | True일 경우 모든 입력이 `list[type]`로 처리됨 |
|
|
| is_deprecated | bool | 선택 | 노드 폐기 여부 플래[Flag] |
|
|
| is_experimental | bool | 선택 | 실험적 기능 여부 표시 |
|
|
| is_dev_only | bool | 선택 | 개발 모드에서만 보이도록 설정 |
|
|
| is_api_node | bool | 선택 | Comfy API 서비스용 노드로 지정 |
|
|
| not_idempotent | bool | 선택 | True일 경우 캐싱된 출력을 재사용하지 않고 항상 재실행함 |
|
|
| enable_expand | bool | 선택 | NodeOutput에 확장 속성 포함 가능 여부 |
|
|
| accept_all_inputs | bool | 선택 | 스키마에 정의되지 않은 입력도 kwargs로 전달 허용 |
|
|
|
|
### 4. Advanced Features (고급 기능)
|
|
* **Hidden Inputs**: `cls.hidden`을 통해 접근하며, `unique_id`, `prompt`, `extra_pnginfo` 등을 포함함.
|
|
* **UI Helpers**: `ui.PreviewImage`, `ui.AudioSaveHelper` 등을 사용하여 노드 출력 시 UI 데이터를 반환할 수 있음.
|
|
* **Custom Types**: `@io.comfytype` 데코레이터나 `io.Custom` 함수를 통해 사용자 정의 타입을 생성 가능함.
|
|
* **Dynamic Inputs**: `Autogrow`(입력 자동 증가) 및 `DynamicCombo`(옵션에 따라 입력 변경) 기능을 지원함.
|
|
|
|
## ⚖️ 모래 및 업데이트 (Contradictions & updates)
|
|
* **업데이트 사항**: V1의 `IS_CHANGED` 함수가 V3에서는 `fingerprint_inputs`로 명칭이 변경됨 (개발자의 혼동을 방지하기 위함).
|
|
* **업데이트 사항**: 입력 검증 메서드가 `VALIDATE_INPUTS`에서 `validate_inputs`로 소문자화되어 변경됨.
|
|
|
|
## 🛠️ 적용 사례 (Applied in summary)
|
|
* **노드 마이그레이션 프로젝트**: 기존에 운영 중인 V1 기반 커스텀 노드를 최신 ComfyUI 스키마 표준에 맞춰 업데이트할 때 이 가이드를 참조함.
|
|
* **확장 프로그램 개발**: `ComfyExtension`을 사용하여 새로운 노드 세트를 등록하고, `comfy_entrypoint`를 통해 실행 환경을 구축하는 데 사용됨.
|
|
|
|
## ✅ 검증 상태 및 신뢰도
|
|
- **상태:** draft
|
|
- **검증 단계:** conceptual
|
|
- **출처 신뢰도:** B (Primary Source — 웹사이트 본문 직접 추출)
|
|
- **중복 검사 결과:** 신규 생성 (New discovery)
|
|
|
|
## 🔗 관련 문서 링크 (Related document links)
|
|
* [[io.Schema]] - V3 노드의 핵심 정의 구조체.
|
|
* [[ComfyExtension]] - 확장의 생명주기와 노드 등록을 관리하는 클래스.
|
|
* [[io.NodeOutput]] - 실행 결과와 UI 데이터를 반환하기 위한 표준 객체.
|
|
* [[comfy_api.latest]] - 최신 안정화된 API 참조를 위한 패키지.
|
|
* [[V1 (Legacy)]] - 마이그레이션의 대상이 되는 이전 방식의 노드 구조.
|
|
|
|
## 📝 변경 이력 (Change history)
|
|
- 2026-05-20: Astra /wikify 로 https://docs.comfy.org/custom-nodes/v3_migration 본문에서 초안 생성. |