ComfyUI 워크플로우의 서버리스 배포는 시각적 메타데이터를 제거하고 실행 로직만 남긴 **API 포맷 JSON(Backend Format)**을 통해 워크플로우를 독립적인 실행 가능한 프로그램으로 변환하는 과정이다 [1-4].
🧠 핵심 개념 (Core concepts)
API 포맷 JSON (workflow_api.json): 서버 사이드 실행에 최적화된 스트림라인드 그래프로, 노드 위치나 크기 같은 UI 메타데이터를 제외하고 오직 노드 타입, 입력값, 연결 정보만을 포함한다 [1, 4].
서버리스 엔드포인트 (Serverless Endpoint): GPU 관리, 오토스케일링, 플랫폼 최적화가 포함된 확장 가능한 API 지점으로, 사용자는 인프라 관리 없이 워크플로우를 실행할 수 있다 [3].
입력 오버라이드 (Input Overrides): 배포된 워크플로우를 호출할 때 프롬프트, 시드, 이미지 경로 등 특정 파라미터만을 동적으로 변경하여 전송하는 방식이다 [5, 6].
종속성 패키징 (Dependency Packaging): 서버리스 환경에서 워크플로우가 작동하도록 필요한 커스텀 노드, 모델 가중치, Python 라이브러리를 도커 이미지나 YAML 설정으로 정의하는 과정이다 [7, 8].
🧩 추출된 패턴 (Extracted patterns)
Bifurcation(이분화) 패턴: 사용자 편집용 'Frontend JSON'과 실행 전용 'API JSON'을 분리하여 관리하며, API 요청 시에는 반드시 후자를 사용해야 한다 [1, 9, 10].
Pipeline-as-Code: 워크플로우 실행 로직을 Python 스크립트(new_pipeline.py)로, 환경 설정을 YAML(pipeline.yaml)로 작성하여 인프라를 코드로 관리한다 [7].
Remote Asset Referencing: 로컬 파일을 직접 사용하는 대신 URL 참조나 ZIP/TAR 압축 파일 업로드를 통해 서버리스 환경에 데이터를 공급한다 [11, 12].
📖 세부 내용 (Details)
API 포맷 획득 프로토콜: 서버리스 배포를 위한 JSON을 얻으려면 ComfyUI 설정(Settings) 메뉴에서 **'Enable Dev mode Options'**를 활성화해야 한다 [2, 11, 13, 14]. 이후 제어판에 나타나는 'Save (API format)' 또는 'Export (API)' 버튼을 통해 추출할 수 있다 [2, 15].
플랫폼별 배포 방식:
Mystic:pipeline.yaml에 CUDA 및 Python 의존성을 정의하고, new_pipeline.py에서 ComfyUI 서버 시작 및 워크플로우 로드 로직을 구현한다 [7, 8]. 도커 이미지를 빌드하여 Mystic 계정에 푸시하면 엔드포인트가 생성된다 [8, 16].
Replicate:fofr/any-comfyui-workflow와 같은 범용 모델을 활용하거나 전용 API 토큰을 사용하여 Python/JavaScript 클라이언트로 워크플로우 JSON을 전송한다 [17-19].
RunComfy: 워크플로우를 'Serverless API (ComfyUI)'로 배포하며, 플랫폼이 내부적으로 workflow_api.json을 저장하고 API 호출 시 오버라이드 값만 적용하여 효율적으로 실행한다 [4, 6, 20].
데이터 처리 및 통신:
입력: 이미지 입력 시 Load Image (Base64) 노드를 사용하여 JSON 내에 데이터를 직접 포함하거나, URL을 통해 클라우드 저장소의 자원을 참조한다 [11, 21].
출력: 결과물 확인을 위해 SaveImageWebsocket 노드를 사용하여 웹소켓 통신으로 이미지 바이너리를 수신하거나, 서버리스 플랫폼의 출력 디렉토리에 저장된 파일을 반환받는다 [21, 22].
자동화 및 변환 도구:comfyui-workflow-to-api-converter-endpoint를 설치하면 /workflow/convert 엔드포인트를 통해 일반 workflow.json을 API 포맷으로 서버사이드에서 즉시 변환하여 실행할 수 있다 [10, 23, 24].
⚖️ 모순 및 업데이트 (Contradictions & updates)
호환성 문제: 표준 workflow.json을 API 엔드포인트(prompt)에 직접 전송하면 백엔드 엔진이 시각적 메타데이터를 해석하지 못해 오류가 발생한다 [10, 13].
가독성 손실: API JSON은 노드 위치 정보가 제거되었으므로, 이를 다시 ComfyUI UI로 드래그하면 노드들이 겹쳐진 '뼈대만 남은' 상태가 되어 편집이 극도로 어렵다 [25]. 따라서 원본 'Full Workflow' JSON을 반드시 별도로 보관해야 한다 [25].
종속성 취약점: 배포된 환경에 필요한 커스텀 노드가 누락되면 'Red Boxes' 에러가 발생하며, 이를 해결하기 위해 ComfyUI-Manager를 통한 의존성 해결이나 도커 기반의 환경 구성이 필수적이다 [8, 26, 27].
🛠️ 적용 사례 (Applied in summary)
new_pipeline.py: Mystic 플랫폼에서 서버리스 엔드포인트를 정의하는 핵심 파이썬 파일로, 입력 프롬프트를 JSON 워크플로우에 주입하고 실행하는 템플릿 역할을 한다 [7, 22].
pipeline.yaml: Mystic 배포 시 CUDA 버전, Python 라이브러리 종속성, 오토스케일링 설정을 포함하는 구성 파일이다 [7, 8].
fofr/any-comfyui-workflow: Replicate에서 어떤 API 포맷 JSON이든 수용하여 실행할 수 있도록 설계된 범용 서버리스 모델이다 [17, 19].
GitHub Commit bc85382: comfyui-workflow-to-api-converter-endpoint에서 콤보 위젯의 대소문자 표기 오류(예: True vs true)를 수정하여 유효성 검사 실패 문제를 해결한 기록이 확인된다 [28, 29].
✅ 검증 상태 및 신뢰도
상태: draft
검증 단계: conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능)
출처 신뢰도: B (Official Documentation / Primary Source via NotebookLM)
중복 검사 결과: 신규 생성 (New discovery)
📝 변경 이력 (Change history)
2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine.
