2nd/10_Wiki/Comfyui/Nodes.md

---
id: nodes
title: "Nodes"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: []
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.85
created_at: 2026-05-20
updated_at: 2026-05-20
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["ComfyUI-WorkflowGenerator", "ComfyUI-to-Python-Extension", "comfyui-workflow-to-api-converter-endpoint"]
github_commit: "82df278, bc85382"
---

# [[Nodes]]

## 🎯 한 줄 통찰 (One-line insight)
노드는 ComfyUI의 핵심 엔진이자 기능적 단위로서, 고유한 메타데이터와 입출력 연결을 통해 생성형 AI 프로세스를 유향 비순환 그래프(DAG)로 추상화한다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **노드 객체 (Node Object):** ID, 타입, 위치 정보를 포함하며 특정 기능을 수행하는 독립적인 프로그램 모듈이다 [3-5].
- **입출력 슬롯 및 링크 (I/O Slots & Links):** 노드 간 데이터를 전달하는 통로로, 입력(inputs)은 들어오는 와이어의 ID를, 출력(outputs)은 하나 이상의 하류 노드로 연결되는 링크 ID 배열을 포함한다 [4, 6].
- **노드 레지스트리 (Node Registry):** 설치된 모든 노드의 클래스 이름과 입출력 스키마(object_info)를 관리하는 중앙 카탈로그이다 [4, 7, 8].
- **실행 모드 (Mode):** 노드의 활성화 상태(active), 우회(bypass) 등을 결정하며, 백엔드 엔진은 이를 기반으로 실행 경로를 계산한다 [4, 5, 9].

## 🧩 추출된 패턴 (Extracted patterns)
- **실행 모델 역전 (Execution Model Inversion):** 엔진이 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색, 결과 도출에 필요한 의존성 노드만 실행하여 효율성을 극대화한다 [10].
- **형식별 노드 직렬화:** 프론트엔드 형식(workflow.json)은 노드의 좌표, 크기 등 시각적 메타데이터를 유지하는 반면, API 형식(workflow_api.json)은 실행에 필요한 로직과 직접적인 노드 입력 참조만 남긴다 [11-13].
- **자동 검증 및 보정:** 생성된 워크플로의 노드 이름을 로컬 설치 환경이나 시맨틱 임베딩과 대조하여 유효성을 검사하고 오류를 수정한다 [14-16].

## 📖 세부 내용 (Details)

### 노드 객체의 기술적 사양 (v1.0 Schema)
ComfyUI 워크플로 JSON 내에서 각 노드는 다음과 같은 속성을 필수적으로 정의해야 한다 [4, 5]:
- **id:** 그래프 탐색을 위한 고유 식별자 (정수 또는 문자열) [17].
- **type / class_type:** 노드 레지스트리의 클래스 이름과 매핑되는 식별자 [5, 18].
- **pos & size:** 캔버스 좌표 [x, y] 및 시각적 크기 [width, height] (프론트엔드 전용) [4, 19].
- **widgets_values:** 슬라이더, 텍스트 박스, 토글 등 사용자 입력 값을 저장하는 배열 [4, 20].
- **order:** 노드의 실행 또는 렌더링 순서 인덱스 [4].

### 주요 노드 카테고리 및 기능
- **로더 (Loaders):** Checkpoint, LoRA, VAE, ControlNet 등 외부 모델 가중치를 워크플로로 불러온다 [21, 22].
- **샘플러 (Samplers):** KSampler, SamplerCustom 등 잠재 공간(Latent space)에서 노이즈를 제거하여 이미지를 생성한다 [23, 24].
- **조건화 및 인코딩 (Conditioning & Encoding):** CLIP Text Encode(프롬프트 처리), VAE Encode/Decode(픽셀과 잠재 공간 간 변환) 등을 수행한다 [20, 21, 24].
- **유틸리티 (Utils):** Reroute(선 정리), Primitive, Note 등 워크플로의 조직화와 가독성을 돕는다 [23, 25].

### API 및 자동화 환경의 노드 처리
API 기반 실행 시, 노드는 **API JSON 형식**으로 직렬화되어 시각적 정보가 제거된다 [11, 26]. 이때 노드 간 연결은 별도의 링크 배열이 아닌 `inputs` 필드 내에 상류 노드 ID와 슬롯 인덱스 형태로 직접 임베딩된다 [11, 20]. 독립 실행형 스크립트나 외부 앱 연동 시에는 `Load Image (Base64)` 노드를 통해 이미지를 JSON 내에 직접 포함시키거나, `SaveImageWebsocket`을 통해 결과를 실시간으로 수신하는 패턴이 사용된다 [17, 27, 28].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **노드 식별 방식:** 프론트엔드 JSON은 시각적 ID를 사용하지만, API JSON은 기능적 키(Functional keys)를 사용하여 백엔드와 매핑한다 [12].
- **커스텀 노드 의존성:** 소스 간 공통적으로 지적되는 문제로, 워크플로 JSON에 포함된 노드가 로컬에 설치되어 있지 않으면 '빨간 박스(Missing Nodes)' 오류가 발생하며 ComfyUI Manager를 통한 해결이 권장된다 [29-31].

## 🛠️ 적용 사례 (Applied in summary)
- **ComfyUI-WorkflowGenerator [32, 33]:** 자연어 설명을 기반으로 `Generator` -> `Validator` -> `Builder` 단계를 거쳐 노드 그래프를 자동으로 생성하고 검증하는 시스템을 구현함.
- **comfyui-workflow-to-api-converter-endpoint [8, 25, 34]:** `/workflow/convert` 엔드포인트를 통해 프론트엔드 노드 데이터를 API 규격으로 변환하며, `reroute` 노드 무시 및 `INPUT_TYPES()` 기반 기본값 보정 기능을 포함함 (Commit: `bc85382`).
- **ComfyUI-to-Python-Extension [35, 36]:** UI의 노드 그래프를 실행 가능한 Python 스크립트로 변환하여 자동화 환경에서 노드 로직을 재사용할 수 있게 함.
- **RunComfy API [7, 37]:** `object_info.json`을 통해 인스턴스 내 모든 노드의 입력/출력 스키마를 제공하여 외부 툴의 유효성 검사에 활용함.

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 프로젝트 및 공식 문서 내 스펙 확인됨)
- **출처 신뢰도:** B (공식 문서 및 오픈소스 프로젝트 기술 명세 기반)
- **중복 검사 결과:** 신규 생성 (New discovery)

## 📝 변경 이력 (Change history)
- 2026-05-20: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Sources: [1-6, 8, 11, 33])