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

---
id: workflow-json
title: "Workflow JSON"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["Workflow API JSON", "Frontend JSON"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.90
created_at: 2026-05-19
updated_at: 2026-05-19
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["ComfyUI/custom_nodes/ComfyUI-Manager", "ComfyUI/custom_nodes/ComfyUI-WorkflowGenerator", "ComfyUI/models/LLM/", "workflow_api.py"]
github_commit: "82df278, bc85382"
---

# [[Workflow JSON]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI의 Workflow JSON은 노드 기반 비순환 유향 그래프(DAG)를 직렬화하여 복잡한 생성형 AI 파이프라인을 휴대 가능한 데이터로 변환하고, 이를 통해 시각적 편집과 프로그래밍적 자동화를 연결하는 핵심 매개체이다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **이분화된 직렬화 포맷:** 사용자 인터페이스를 위한 **Frontend 포맷(workflow.json)**과 서버 측 실행에 최적화된 **API 포맷(workflow_api.json)**으로 나뉜다 [4-6].
- **Litegraph 기반 스키마 (v1.0):** 노드 ID, 유형, 위치, 크기, 위젯 값 및 노드 간의 링크 배열을 포함하는 표준화된 기술 규격을 따른다 [7-9].
- **메타데이터 임베딩 기술:** 생성된 PNG나 WebP 이미지의 tEXt/zTXt 청크 내에 JSON 데이터를 직접 삽입하여 이미지 파일 자체가 워크플로우 백업 역할을 수행하게 한다 [10, 11].
- **실행 모델 반전 (Execution Model Inversion):** 최종 출력 노드(Save Image 등)로부터 역추적하여 필요한 의존성 노드만 실행하는 최적화 구조를 가진다 [12].

## 🧩 추출된 패턴 (Extracted patterns)
- **UI-to-API 정제 패턴:** 시각적 메타데이터(좌표, 그룹, 색상)를 제거하고 노드 입력을 직접적인 노드 참조로 변환하여 파일 크기를 줄이고 실행 효율을 극대화한다 [4, 13].
- **LLM 기반 3단계 생성 파이프라인:** 자연어 설명 해석(Logical Synthesis) → 노드 존재 여부 검증(Semantic Validation) → 실행 가능한 JSON 컴파일(Graph Compilation) 과정을 통해 워크플로우를 자동 생성한다 [14-16].
- **의존성 복구 휴리스틱:** JSON 내 `class_type`을 로컬 레지스트리와 대조하여 누락된 커스텀 노드를 식별하고 ComfyUI Manager를 통해 일괄 설치를 제안한다 [17, 18].

## 📖 세부 내용 (Details)
ComfyUI 워크플로우 JSON은 생성적 AI 프로세스를 절차적 프레임워크로 추상화한 결과물이다 [1, 19]. 이 데이터 구조는 인간이 읽을 수 있는 형식이며, 대용량 모델 가중치와 독립적으로 공유 및 버전 관리가 가능하다 [2].

**1. 주요 포맷 상세 비교** [4, 5, 13, 20-22]:
- **Frontend JSON:** Litegraph 표준을 따르며 노드의 캔버스 좌표(`pos`), 크기(`size`), 그룹 정보 등 시각적 레이아웃 데이터를 모두 보존한다. 주로 시각적 편집과 공유를 목적으로 사용된다.
- **API JSON:** `/prompt` 엔드포인트 호출을 위한 정제된 형태이다. 시각적 정보는 삭제되며, 노드 간 연결은 별도의 링크 배열이 아닌 각 노드 입력부에 `[노드_ID, 출력_슬롯_인덱스]` 형태로 직접 임베딩된다.

**2. 생성 및 획득 방법** [23-27]:
- **수동 내보내기:** GUI의 제어판에서 `Ctrl + S`(Frontend)를 누르거나, 설정에서 'Dev mode' 활성화 후 'Save (API format)' 버튼을 클릭하여 생성한다.
- **이미지에서 추출:** 생성된 PNG 파일을 캔버스에 드래그 앤 드롭하면 내장된 JSON이 로드된다. 대량 추출 시 `exiftool`이나 `ComfyUI-Workflow-Extractor` 같은 CLI 도구를 사용하여 메타데이터 청크에서 직접 파싱할 수 있다.
- **LLM 생성:** `Qwen2.5-14B` 등 미세 조정된 모델을 사용하여 "SDXL용 텍스트-이미지 워크플로우 생성"과 같은 자연어 지시를 즉시 실행 가능한 JSON 그래프로 변환한다 [14, 28].

**3. 프로그래밍적 조작 및 자동화** [29-33]:
- 개발자는 Python의 `json` 라이브러리를 사용하여 노드 ID를 기반으로 프롬프트(`CLIPTextEncode`), 시드값, 체크포인트 이름 등을 동적으로 변경할 수 있다.
- `Comfy API Simplified`와 같은 래퍼 라이브러리는 숫자 ID 대신 노드 제목(Title)을 기준으로 파라미터를 설정할 수 있게 하여 코드 유지보수성을 높인다.
- 워크플로우 자체를 순수 Python 스크립트로 변환하여 서버리스 환경이나 단독 애플리케이션에서 실행할 수도 있다 [34].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **버전 호환성:** ComfyUI의 잦은 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있다는 경고가 존재한다 [35].
- **메타데이터 취약성:** 이미지 편집기, 소셜 미디어 플랫폼 등에서 파일 최적화 과정 중 워크플로우 정보가 포함된 메타데이터 청크를 삭제하는 경우가 많아 JSON 공유 시 주의가 필요하다 [10].
- **노드 명칭 충돌:** 서로 다른 제작자가 만든 커스텀 노드가 동일한 제목을 가질 수 있어, 프로그래밍적 접근 시 숫자 ID나 고유 클래스 타입 확인이 필수적이다 [33].

## 🛠️ 적용 사례 (Applied in summary)
- **DanielPFlorian/ComfyUI-WorkflowGenerator:** LLM을 이용해 자연어로 JSON을 생성하는 프로젝트로, 커밋 `82df278`에서 모델 경로 해결 및 중복 드롭다운 수정이 이루어졌다 [36, 37].
- **SethRobinson/comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측 JS 로직을 서버 측 Python으로 변환하여 Frontend JSON을 API 포맷으로 즉시 변환하는 엔드포인트를 구현했다 (커밋 `bc85382`) [38, 39].
- **ComfyUI Manager:** JSON 내부의 노드 정의를 분석하여 `ComfyUI/custom_nodes` 디렉토리에 필요한 의존성을 자동 설치하는 매커니즘을 제공한다 [17, 40].
- **Standalone Execution Scripts:** `sdxl_workflow_api.json`을 로드하여 독립적인 Python 환경에서 실행하는 `WorkflowExecutor` 사례가 확인되었다 [41, 42].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 오픈소스 프로젝트와 공식 문서의 구조가 일치함을 확인)
- **출처 신뢰도:** B (공식 문서 및 실제 구현 코드가 포함된 GitHub 저장소 기반)
- **중복 검사 결과:** 신규 생성 (New discovery)

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

### 상위/유사 개념
#### [아키텍처/기반 기술]
- [[Directed Acyclic Graph (DAG)]]
  - 연결 이유: 워크플로우의 노드 연결 구조를 정의하는 수학적 기반임 [1].
  - 이해 증진: 실행 순서 결정 및 의존성 해결 원리를 이해할 수 있음.
- [[Litegraph Standard]]
  - 연결 이유: Frontend JSON 포맷의 시각적 직렬화 규격임 [4, 20].
  - 이해 증진: 노드 위치, 크기 및 시각적 플래그 저장 방식을 파악할 수 있음.

#### [구현/활용 도구]
- [[ComfyUI Manager]]
  - 연결 이유: JSON 내 정의된 커스텀 노드 의존성을 해결하는 핵심 도구임 [17].
  - 이해 증진: 공유된 워크플로우의 실행 오류를 해결하는 프로세스를 이해할 수 있음.
- [[Large Language Models (LLM)]]
  - 연결 이유: 자연어를 JSON으로 변환하는 최신 자동화 기술의 핵심임 [14, 37].
  - 이해 증진: '대화형 프로그래밍'으로의 진화 방향을 이해할 수 있음.

### 심층 후속 질문 (Deeper Research Questions)
- Frontend JSON과 API JSON 사이의 변환 과정에서 손실되는 데이터가 실행 결과에 미치는 영향은 무엇인가? [4, 39]
- 이미지 메타데이터(tEXt/zTXt) 외에 워크플로우 정보를 보존하기 위한 더 견고한 아키텍처는 무엇인가? [10, 43]
- LLM 기반 생성기에서 '훈련 시점 이후 출시된 커스텀 노드'에 대한 환각(Hallucination) 문제를 어떻게 제어하는가? [44, 45]
- Execution Model Inversion이 대규모 복합 워크플로우에서 자원 효율성을 구체적으로 얼마나 개선하는가? [12]
- 모델 해싱(SHA-256)을 JSON 내에 포함시켜 파일명 불일치 문제를 해결하는 표준화된 방식은 무엇인가? [46]

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** Python의 `urllib`과 `websocket`을 사용하여 `/prompt` 엔드포인트에 JSON 페이로드를 전송하고 결과를 실시간으로 수신함 [32].
- **System Design:** 워크플로우를 JSON으로 관리함으로써 CI/CD 파이프라인을 통한 자동 테스트 및 버전 관리가 가능해짐 [47].
- **Operation / Maintenance:** 모델 파일 경로가 다른 환경으로 이전 시 JSON 내부의 파일명을 로컬 환경에 맞춰 수정하거나 ComfyUI Manager의 검색 기능을 활용함 [43].
- **Learning Path:** 기본 워크플로우 템플릿 로드 → 시각적 노드 연결 변경 → JSON 내보내기 및 구조 분석 순서로 학습 권장 [48].

### 인접 주변 주제 (Adjacent Topics)
- [[Model Hashing]]
  - 확장 방향: JSON 파일의 기기 간 이동 시 모델 파일명 불일치 문제를 해결하는 기술적 대안 [46].
- [[Workspace Packaging (.cpack.zip)]]
  - 확장 방향: JSON 단일 파일의 한계를 넘어 모델 해시와 노드 버전까지 패키징하는 미래 표준 [43].

## 📝 변경 이력 (Change history)
- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [1, 6, 14, 24, 25, 29, 30, 32, 37, 41, 43, 49-52]