- 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>
ComfyUI Workflow JSON은 복잡한 노드 기반 생성 프로세스를 유향 비순환 그래프(DAG) 형태로 직렬화한 청사진으로, 시각적 편집을 위한 프론트엔드 포맷과 무두(Headless) 실행 및 자동화를 위한 API 포맷으로 이원화되어 관리된다 [1-3].
🧠 핵심 개념 (Core concepts)
프론트엔드 포맷 (workflow.json): 시각적 편집과 사용자 상호작용을 위해 설계된 포맷으로, 노드의 좌표(pos), 크기(size), 그룹 구조 및 색상과 같은 UI 메타데이터를 모두 포함한다 [2-4].
API 포맷 (workflow_api.json): 백엔드 실행 엔진 최적화를 위해 UI 관련 메타데이터를 제거한 스트림라인드 포맷으로, 노드 입력부 내에 연결 정보가 직접 삽입되는 구조를 가진다 [2, 5, 6].
메타데이터 임베딩 (Metadata Embedding): 생성된 PNG/WebP 파일의 tEXt 또는 zTXt 청크에 JSON 데이터를 주입하여 이미지 자체가 실행 로직을 포함하는 컨테이너 역할을 수행하게 한다 [7, 8].
JSON 스키마 v1.0: 유효한 워크플로우를 보장하기 위한 기술적 제약 조건으로, 고유 ID, 클래스 타입, 위젯 값 등의 속성을 정의한다 [9-11].
🧩 추출된 패턴 (Extracted patterns)
이원화 저장 패턴: 사용자는 UI에서 수정한 내용을 Save로 저장(프론트엔드)하고, 외부 연동을 위해 Dev Mode를 활성화하여 Save (API Format)으로 내보낸다 [12-15].
역방향 그래프 탐색 (Execution Model Inversion): 백엔드 엔진이 출력 노드(Save Image 등)로부터 역방향으로 의존성을 추적하여 실제 실행에 필요한 노드만 식별하고 나머지는 무시하는 최적화 패턴을 사용한다 [16].
입력값 교체 패턴 (Prompt Injection): Python 등 프로그래밍 환경에서 템플릿 JSON을 로드한 후, 특정 노드 ID의 inputs 딕셔너리를 직접 수정하여 시드(seed)나 프롬프트를 동적으로 변경한다 [17-19].
📖 세부 내용 (Details)
1. 생성 및 추출 방법론
GUI 기반 생성: 기본 인터페이스의 컨트롤 패널에서 Ctrl + S를 통해 프론트엔드 JSON을 저장할 수 있다 [12]. API 포맷을 생성하려면 설정 메뉴에서 'Enable Dev mode Options'를 활성화해야 한다 [13, 14, 20].
이미지 메타데이터 추출: ComfyUI에서 생성된 이미지를 캔버스에 드래그 앤 드롭하거나 [21-23], ExifTool을 사용하여 exiftool -b -workflow input.png > workflow.json 명령어로 바이너리 데이터를 추출할 수 있다 [24, 25].
자동화 도구:comfyui-workflow-to-api-converter-endpoint와 같은 커스텀 노드는 서버 측에서 프론트엔드 형식을 API 형식으로 실시간 변환하는 엔드포인트를 제공한다 [26-28].
2. 프로그래밍적 제어 및 변환
Python 통합: 워크플로우 JSON은 중첩된 딕셔너리 구조이므로 Python의 json 라이브러리로 쉽게 조작 가능하다 [17]. ComfyUI-to-Python-Extension은 JSON을 아예 독립적인 실행 파일(.py)로 변환해주기도 한다 [29-31].
LLM 기반 생성:ComfyUI-WorkflowGenerator는 자연어 설명을 입력받아 LLM(Qwen2.5 등)이 논리 구조를 합성하고, 유효성 검사(Validator)를 거쳐 최종 JSON을 빌드하는 3단계 파이프라인을 사용한다 [32-35].
3. 데이터 구조 분석 (v1.0 기준)
노드 객체 속성: 각 노드는 고유 id, 노드 클래스 매핑을 위한 type, 실행 순서를 결정하는 order, 그리고 사용자 입력값인 widgets_values를 보유한다 [4, 9].
연결 구조: 프론트엔드에서는 별도의 links 배열을 통해 연결을 정의하지만, API 포맷에서는 노드의 inputs 내부에 [origin_id, output_slot_index] 형태의 참조를 직접 기록한다 [2, 3, 36, 37].
⚖️ 모순 및 업데이트 (Contradictions & updates)
버전 호환성: ComfyUI가 빈번하게 업데이트됨에 따라 구버전 JSON 파일이 최신 UI에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [38].
메타데이터 손실: 소셜 미디어 플랫폼이나 이미지 압축 소프트웨어는 종종 이미지 내의 JSON 메타데이터 청크를 삭제하여 워크플로우 정보를 소실시킨다 [8, 38].
API 포맷의 비가역성: API 포맷으로 내보낸 JSON을 다시 UI로 불러올 경우 시각적 레이아웃 정보(좌표, 그룹 등)가 유실되어 편집이 매우 어려워진다 [26, 39].
🛠️ 적용 사례 (Applied in summary)
comfyui-workflow-to-api-converter-endpoint (SethRobinson):/workflow/convert 엔드포인트를 통해 비 API 워크플로우를 API 포맷으로 서버사이드 변환 수행. **commit bc85382**에서 콤보 위젯 대소문자 정규화 로직 적용 [40-42].
ComfyUI-WorkflowGenerator (DanielPFlorian): LLM을 활용하여 자연어 지시문을 워크플로우 JSON으로 변환하는 파이프라인 구현. **commit 82df278**에서 드롭다운 중복 모델 문제 해결 [34, 43, 44].
ComfyUI-to-Python-Extension (pydn): JSON 워크플로우를 실행 가능한 Python 코드로 번역. **commit 6cdcc23**에서 설치 문제 해결 및 README 업데이트 [30, 31, 45].
comfy_api_simplified: 노드 제목(title)을 기반으로 파라미터를 설정하여 숫자 ID에 의존하지 않는 안정적인 API 제어 방식 구현 [29, 46, 47].
✅ 검증 상태 및 신뢰도
상태: draft
검증 단계: conceptual (실제 적용 사례 다수 발견으로 검증 수준 높음)
출처 신뢰도: B (Official Documentation / Primary Source via NotebookLM)
중복 검사 결과: 신규 생성 (New discovery)
📝 변경 이력 (Change history)
2026-05-20: Initial draft generated via Datacollector_MAC P-Reinforce engine.
koriweb
a3f63e56e2