Files

T

koriweb a3f63e56e2 Add ComfyUI wikified docs and youtube extracts; tidy raw→Topics

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

2026-05-20 18:41:10 +09:00

7.0 KiB

Raw Blame History

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_radix, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

title

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)

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 본문에서 초안 생성.

7.0 KiB Raw Blame History