2nd/10_Wiki/Topics/Comfyui/ComfyUI Workflow JSON.md

---
id: comfyui-workflow-json
title: "ComfyUI Workflow JSON"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["워크플로우 JSON", "workflow_api.json"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.85
created_at: 2026-05-19
updated_at: 2026-05-19
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법", "ComfyUI", "JSON"]
raw_sources: ["NotebookLM Synthesis"]
applied_in:
  - "DanielPFlorian/ComfyUI-WorkflowGenerator/README.md"
  - "comfyui-workflow-to-api-converter-endpoint/README.md"
  - "pydn/ComfyUI-to-Python-Extension/README.md"
github_commit: "82df278, bc85382, 6cdcc23"
---

# [[ComfyUI Workflow JSON]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI Workflow JSON은 복잡한 노드 기반 생성 AI 프로세스를 직렬화하여 가시적인 UI 레이아웃과 프로그램적 실행 로직 간의 상호 운용성을 보장하는 핵심 청사진이다 [1, 2].

## 🧠 핵심 개념 (Core concepts)
1.  **포맷의 이분화 (Bifurcation):** 사용자의 시각적 편집을 위한 '프런트엔드 포맷(workflow.json)'과 서버 실행에 최적화된 '백엔드/API 포맷(workflow_api.json)'으로 나뉜다 [3-6].
2.  **메타데이터 임베딩 (Metadata Embedding):** 생성된 PNG 이미지의 tEXt/zTXt 청크 내에 워크플로우 데이터를 숨겨 저장함으로써 이미지 자체가 백업 및 공유 수단이 된다 [7-9].
3.  **노드 레지스트리 기반 스키마:** 각 노드는 고유 ID, 클래스 타입, 입력/출력 슬롯 및 연결 정보를 담고 있으며, 이는 JSON Schema v1.0 규격을 따른다 [10-12].
4.  **프로그램적 제어 (Programmatic Automation):** JSON 구조를 직접 수정하거나 전용 라이브러리를 통해 워크플로우를 동적으로 생성 및 실행할 수 있다 [13-15].

## 🧩 추출된 패턴 (Extracted patterns)
-   **실행 모델 역전 (Execution Model Inversion):** 엔진은 출력 노드(Save Image 등)에서 시작하여 역방향으로 그래프를 탐색하며 필요한 의존성만 식별하여 실행한다 [16].
-   **3단계 생성 파이프라인 (LLM):** 자연어 설명을 기반으로 논리적 구조 합성(Generator), 노드 이름 검증(Validator), 실행 가능한 JSON 컴파일(Builder) 순으로 워크플로우를 자동 생성한다 [17-19].
-   **헤드리스 변환 패턴:** 시각적 노드 그래프를 순수 Python 스크립트(.py)로 변환하여 GUI 없이 독립적으로 실행하는 구조를 가진다 [20, 21].

## 📖 세부 내용 (Details)
ComfyUI 워크플로우는 AI 이미지 생성 프로세스를 설명하는 노드 네트워크를 직렬화한 데이터이다 [22, 23]. 주요 생성 및 관리 방법은 다음과 같다.

**1. 포맷별 특성 및 생성**
*   **프런트엔드 JSON:** 노드 위치, 크기, 그룹, 색상 등 시각적 정보를 포함하며 Litegraph 표준을 따른다 [3, 5, 24]. 일반적인 'Save' 버튼이나 `Ctrl+S`로 생성한다 [8, 25].
*   **API JSON:** UI 메타데이터를 제거하고 실행 로직(노드 타입, 입력값, 연결 관계)만 남긴 효율적인 포맷이다 [3, 6, 26]. 설정에서 'Dev mode Options'를 활성화한 후 'Save (API Format)'를 통해 추출할 수 있다 [27-30].

**2. 이미지 메타데이터 활용 및 추출**
ComfyUI에서 생성된 모든 이미지는 워크플로우 데이터를 내부 메타데이터에 포함한다 [31, 32]. 사용자는 PNG 파일을 캔버스에 드래그 앤 드롭하여 워크플로우를 즉시 복원할 수 있다 [7, 33, 34]. 대량의 이미지에서 JSON을 추출하기 위해 `exiftool`이나 전용 CLI 도구, 웹 기반 추출기(`Weird Wonderful AI Art` 등)가 사용된다 [35-37].

**3. 자동화 및 변환 도구**
*   **Python API 연동:** `json` 라이브러리를 사용하여 시드, 프롬프트 등 특정 노드 파라미터를 직접 수정하고 `/prompt` 엔드포인트로 전송할 수 있다 [13, 15].
*   **변환 엔드포인트:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드는 비-API 포맷을 API 포맷으로 서버 측에서 변환하는 기능을 제공한다 [38, 39].
*   **코드 변환:** `ComfyUI-to-Python-Extension`은 JSON 워크플로우를 독립 실행 가능한 Python 코드로 번역하여 자동화 및 실험의 효율성을 높인다 [14, 21].

**4. LLM 기반 동적 생성**
`ComfyUI-WorkflowGenerator`는 Qwen2.5와 같은 거대언어모델을 활용하여 "SDXL을 이용한 텍스트 투 이미지 워크플로우 생성"과 같은 자연어 명령을 즉시 노드 그래프로 구축한다 [40-42]. 이 과정에서 로컬 노드 카탈로그를 스캔하여 유효성을 검증한다 [43, 44].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
*   **버전 호환성:** ComfyUI의 잦은 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있다는 경고가 존재한다 [33].
*   **메타데이터 소실:** 압축 소프트웨어나 소셜 미디어 플랫폼을 통해 이미지를 전송할 경우 임베딩된 워크플로우 정보가 삭제될 수 있다 [9, 33].
*   **API 포맷의 단점:** API 포맷으로만 저장된 파일은 UI 정보를 포함하지 않아 캔버스에 로드 시 노드가 겹치거나 시각적 구조가 무너진 '스켈레톤' 상태로 나타난다 [45].

## 🛠️ 적용 사례 (Applied in summary)
*   **DanielPFlorian/ComfyUI-WorkflowGenerator:** LLM을 이용해 자연어 설명을 실행 가능한 워크플로우 JSON으로 변환하는 파이프라인 구현 (커밋: `82df278`) [19, 42, 46].
*   **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 사이드 자바스크립트 로직을 파이썬으로 이식하여 `/workflow/convert` 엔드포인트를 통해 JSON 포맷을 변환 (커밋: `bc85382`) [38, 39, 47].
*   **pydn/ComfyUI-to-Python-Extension:** JSON 워크플로우를 `.py` 파일로 내보내어 단독 실행 가능한 스크립트 생성 환경 구축 (커밋: `6cdcc23`) [48, 49].
*   **Mystic Pipeline:** 사용자의 커스텀 워크플로우 JSON을 서버리스 엔드포인트에 배포하여 API 형태로 서빙 [50, 51].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (다양한 오픈소스 프로젝트 및 공식 문서에서 적용 사례 확인됨)
- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM)
- **중복 검사 결과:** 신규 생성 (New discovery)

## 🔗 관련 문서 링크 (Related document links)

### 상위/유사 개념
#### [아키텍처/기반 기술]
- [[Nodes]]
  - 연결 이유: 워크플로우 JSON의 기본 구성 단위 [22, 52].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간의 링크 연결 방식 및 데이터 흐름 구조 [23, 53].
- [[Litegraph]]
  - 연결 이유: 프런트엔드 JSON 포맷의 시각적 직렬화 표준 [3, 5].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 캔버스 레이아웃과 노드 좌표 관리 원리 [4].

#### [구현/활용 도구]
- [[ComfyUI Manager]]
  - 연결 이유: JSON 로드 시 누락된 커스텀 노드를 감지하고 설치하는 도구 [54-56].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 워크플로우 공유 시 발생하는 의존성 해결 방법 [55].
- [[Comfy GPT]]
  - 연결 이유: LLM 기반 워크플로우 생성의 원형이 되는 연구 [19, 40].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 자연어-그래프 변환 알고리즘의 발전 방향 [57].

### 심층 후속 질문 (Deeper Research Questions)
- 프런트엔드 JSON과 API JSON 간의 구조적 차이가 실제 서버 실행 성능에 미치는 정량적 차이는 무엇인가? [3, 4]
- PNG 외에 WebP나 MP4 메타데이터에 워크플로우를 효율적으로 내장하고 추출하는 기술적 표준은 어떻게 정의되는가? [58]
- 'Execution Model Inversion'이 복잡한 루프 구조를 가진 워크플로우에서도 일관된 순서를 보장하는가? [16]
- LLM 기반 생성기에서 새로운 커스텀 노드 출현 시 실시간으로 카탈로그를 업데이트하고 반영하는 효율적인 전략은 무엇인가? [57, 59]
- `.cpack.zip`과 같은 워크플로우 패키징 방식이 기존 JSON 방식의 모델 경로 문제를 어떻게 완전히 해결할 수 있는가? [60]

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** `/prompt` 엔드포인트를 호출할 때 API JSON의 특정 노드 ID 값을 가로채어 동적으로 파라미터를 삽입함 [13, 15].
- **System Design:** 시각적 편집 환경(프런트엔드)과 배포 환경(백엔드)을 분리하여 효율적인 AI 프로덕션 파이프라인 구축 [3, 50, 61].
- **Operation / Maintenance:** `ComfyUI Manager`를 통해 외부 공유 워크플로우의 커스텀 노드 누락 문제를 모니터링하고 해결 [54, 55].
- **Learning Path:** 기본 워크플로우 템플릿 로드에서 시작하여, 메타데이터 추출을 통한 타인 워크플로우 분석, 최종적으로 API 기반 자동화 단계로 발전 [62-64].

### 인접 주변 주제 (Adjacent Topics)
- [[Custom Nodes]]
  - 확장 방향: JSON 내 `class_type`이 참조하는 실제 기능 구현체 및 의존성 관리 [8, 55, 65].
- [[Model Hashing]]
  - 확장 방향: JSON 파일 내 하드코딩된 모델 경로 문제를 SHA-256 해시를 이용해 해결하는 방법 [66].

## 📝 변경 이력 (Change history)
- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source indices: [1-186])