2nd/10_Wiki/Topics/Comfyui/Node Definitions.md

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

id	title	category	status	verification_status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	created_at	updated_at	review_reason	merge_history	tags	raw_sources	applied_in	github_commit
node-definitions	Node Definitions	10_Wiki/Topics	draft	conceptual		Node Schema ComfyUI Node Structure		B	0.90	2026-05-20	2026-05-20			research Comfyui workflow json 생성 방법 Node Definitions	NotebookLM Synthesis	workflow.json workflow_api.json object_info.json comfyui-workflow-to-api-converter-endpoint ComfyUI-WorkflowGenerator	bc85382, 82df278

Node Definitions

🎯 한 줄 통찰 (One-line insight)

노드 정의는 ComfyUI 워크플로우의 기능적 논리와 시각적 레이아웃을 결정하는 핵심 원자 단위로, 고유 ID와 입출력 스키마를 통해 복잡한 AI 프로세스를 유향 비순환 그래프(DAG)로 구조화한다 [1-3].

🧠 핵심 개념 (Core concepts)

• 고유 식별자 (Node ID): 워크플로우 내에서 각 노드를 구분하는 고유한 숫자 또는 문자열 키(예: "#37")로, 그래프 순회 및 데이터 참조의 기준이 된다 [4, 5].
• 클래스 매핑 (Type/Class Type): JSON의 type 또는 class_type 필드는 ComfyUI 백엔드 레지스트리에 등록된 특정 Python 클래스와 노드를 연결하여 실행 로직을 정의한다 [2, 6, 7].
• 입출력 슬롯 (I/O Slots): 데이터 흐름을 위한 인터페이스로, inputs는 상위 노드의 출력을 참조하고 outputs는 하위 노드로 전달될 데이터 링크 정보를 포함한다 [4, 8].
• 위젯 및 속성 (Widgets & Properties): 슬라이더, 텍스트 박스, 체크박스 등 사용자가 직접 입력한 값(widgets_values)과 노드의 내부 동작 설정을 저장한다 [2, 4, 9].

🧩 추출된 패턴 (Extracted patterns)

• 형식의 이분화 (Serialization Bifurcation): 시각적 정보(위치, 크기, 그룹)를 포함하는 **Frontend 형식(workflow.json)**과 실행에 필요한 논리 정보만 남긴 **API 형식(workflow_api.json)**으로 나뉘어 관리된다 [10-12].
• 실행 모델 역전 (Execution Model Inversion): 엔진은 모든 노드를 실행하는 대신 'Save Image'와 같은 출력 노드에서 역방향으로 그래프를 탐색하여 필요한 의존성 노드만 실행 리스트에 포함시킨다 [13].
• 메타데이터 임베딩 패턴: 생성된 미디어(PNG, WebP)의 tEXt/zTXt 청크 내에 노드 그래프 JSON을 주입하여 파일 자체가 워크플로우 컨테이너 역할을 수행하도록 설계한다 [14-16].

📖 세부 내용 (Details)

ComfyUI 노드는 JSON v1.0 스키마에 따라 정밀하게 정의되며, 각 노드 객체는 다음과 같은 필수 속성을 보유해야 한다 [2, 17]:

• id: 그래프 순회를 위한 유효한 정수 또는 문자열 식별자 [2, 5].
• type/class_type: 노드의 기능을 결정하는 레지스트리 클래스명 [2, 6].
• pos & size: UI 캔버스 렌더링을 위한 좌표 [x, y] 및 차원 [width, height] 정보 (Frontend 전용) [2, 4].
• widgets_values: 사용자가 입력한 위젯 상태 값의 배열 또는 객체 [2, 4].
• order: 노드의 실행 또는 렌더링 우선순위를 나타내는 인덱스 [2].
• mode: 노드의 작동 상태(활성, 우회/Bypass 등)를 결정하는 수치 [2, 18].

연결 구조(Connectivity): 연결은 inputs와 outputs 배열을 통해 정의된다. inputs 내부의 link 속성은 들어오는 와이어의 고유 ID를 가리키며, API 형식에서는 이를 소스 노드 ID와 슬롯 인덱스의 쌍(예: [19, 20])으로 직접 포함하기도 한다 [8, 9]. 슬롯 인덱싱은 다중 출력을 가진 노드(예: VAE Loader)에서 특정 데이터를 선택하는 데 필수적이다 [8].

스키마 카탈로그 (object_info.json): 실행 중인 인스턴스에서 사용 가능한 모든 노드의 입력/출력 타입, 필수/선택적 입력 항목, 기본값 및 툴팁 정보를 포함하는 레지스트리 역할을 한다 [21, 22]. 이는 워크플로우를 동적으로 생성하거나 검증하는 도구에서 참조 모델로 사용된다 [23].

⚖️ 모순 및 업데이트 (Contradictions & updates)

• JSON 버전 차이: 소스 데이터는 최신 버전인 v1.0을 언급하지만, 이전 버전인 0.4와의 호환성 문제나 업데이트 논의가 여전히 진행 중임을 암시한다 [17, 24].
• 대소문자 민감도 이슈: ComfyUI 검증기가 콤보 위젯 값의 대소문자(예: "True" vs "true") 차이로 인해 실행을 거부하는 경우가 발생하여, 최신 변환 엔진에서는 이를 정규화(Normalization)하는 로직이 추가되었다 [25].
• 노드 식별 키의 차이: Frontend JSON은 수치형 문자열을 ID로 사용하는 반면, API JSON은 이를 기능적 키로 활용하며 UI 메타데이터를 완전히 제거한다 [10, 11, 26].

🛠️ 적용 사례 (Applied in summary)

• workflow.json / workflow_api.json: 노드 정의가 실제로 구현되는 표준 파일 형식으로, RunComfy 및 Replicate와 같은 서비스에서 배포의 기초로 사용된다 [12, 21, 27].
• object_info.json: 실행 중인 서버의 /object_info 엔드포인트를 통해 실시간 노드 스키마를 제공한다 [23].
• comfyui-workflow-to-api-converter-endpoint (v2.3.0): 비-API 워크플로우를 API 형식으로 변환할 때 COMFY_DYNAMICCOMBO_V3 위젯 및 하위 입력을 처리하고 대소문자 문제를 해결하는 로직이 적용되었다 (Commit: bc85382) [25, 28-30].
• ComfyUI-WorkflowGenerator: 자연어 설명을 기반으로 WorkflowGenerator -> NodeValidator -> WorkflowBuilder 단계를 거쳐 노드 그래프를 동적으로 생성하며, UpdateNodeCatalog 노드를 통해 로컬 노드 레지스트리를 스캔한다 (Commit: 82df278) [31-34].

✅ 검증 상태 및 신뢰도

• 상태: draft
• 검증 단계: conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능)
• 출처 신뢰도: B (Official Documentation / Primary Source via NotebookLM)
• 중복 검사 결과: 신규 생성 (New discovery)

📝 변경 이력 (Change history)

• 2026-05-20: Initial draft generated via Datacollector_MAC P-Reinforce engine.