AI Server

이 문서는 ComfyUI와 ai-node-agent로 구성된 생성 실행부의 역할, 환경 설정 및 주요 동작 방식을 설명합니다.

개요

AI Server는 ComfyUI 컨테이너와 ai-node-agent 컨테이너를 함께 실행하는 generation node입니다. 현재 기본 방향은 workflow 안의 API 노드를 통해 외부 이미지/비디오 생성 provider를 호출하는 구조입니다. ComfyUI는 로컬 추론 서버가 아니라 workflow 실행 엔진과 provider orchestration 계층으로 사용합니다.

환경별 실행 방식은 다음과 같습니다.

환경	실행 방식
local	MacBook Docker Compose에서 `comfyui`와 `ai-node-agent` 컨테이너 실행
dev	EC2 Docker Compose에서 `comfyui`와 `ai-node-agent` 컨테이너 실행
prod	Kubernetes에서 `comfyui`와 `ai-node-agent`를 같은 Pod의 sidecar 컨테이너로 실행하는 구성을 우선 고려

`ai-node-agent`의 역할

ai-node-agent는 생성 orchestration worker입니다. ComfyUI가 workflow 실행 엔진이라면, ai-node-agent는 SQS, S3, backend, realtime relay와 ComfyUI를 연결하는 서비스 로직 계층입니다.

SQS generation queue polling: 환경별 computation queue를 polling하여 generation job을 수신합니다.
Input media 준비: workflow 안의 S3 input path를 감지해 ComfyUI input directory로 다운로드하고 workflow 값을 로컬 파일명으로 치환합니다.
ComfyUI 연동: 수신한 workflow JSON을 ComfyUI API에 전달하고 WebSocket으로 진행 이벤트를 수신합니다.
실시간 상태 보고: queued, processing, progress, finalizing, failed 등의 상태를 public relay/backend에 전달합니다.
S3 raw 업로드: ComfyUI output(images, gifs, videos)을 환경별 media bucket의 raw/ prefix에 업로드합니다.
후처리 queue enqueue: raw_s3_path, creationId, userId, env, resultIndex 등을 post-processing queue로 전달합니다.
실패/취소/타임아웃 처리: terminal event 누락, cancel command, output 누락 등을 감지해 backend 상태와 SQS 흐름이 꼬이지 않도록 처리합니다.

전체 흐름은 다음과 같습니다.

backend
 -> SQS computation queue
 -> ai-node-agent
 -> ComfyUI
 -> external generation API node
 -> S3 raw/
 -> SQS post-processing queue
 -> post-processing-worker

환경 변수 설정 (`.env`)

ai-server 디렉토리의 .env 파일에 다음 변수들을 올바르게 설정해야 합니다.

# 단일 환경은 prod, 다중 환경은 local,dev 처럼 쉼표로 구분합니다.
# prod는 local/dev와 같은 agent에서 함께 실행하지 않습니다.
AI_AGENT_ENV=local,dev

# AWS 리전
AWS_REGION=ap-northeast-2

# local/dev AWS credential
AWS_ACCESS_KEY_ID_LOCAL_DEV=
AWS_SECRET_ACCESS_KEY_LOCAL_DEV=
AWS_SESSION_TOKEN_LOCAL_DEV=

# prod AWS credential 또는 IRSA 환경에서는 비워둘 수 있습니다.
AWS_ACCESS_KEY_ID_PROD=
AWS_SECRET_ACCESS_KEY_PROD=
AWS_SESSION_TOKEN_PROD=

# SQS 연산 큐 URL (환경별)
SQS_COMPUTATION_QUEUE_LOCAL=https://sqs.ap-northeast-2.amazonaws.com/your_aws_account_id/vivid-ai-computation-queue-local
SQS_COMPUTATION_QUEUE_DEV=https://sqs.ap-northeast-2.amazonaws.com/your_aws_account_id/vivid-ai-computation-queue-dev
SQS_COMPUTATION_QUEUE_PROD=https://sqs.ap-northeast-2.amazonaws.com/your_aws_account_id/vivid-ai-computation-queue-prod

# SQS 후처리 큐 URL (환경별)
SQS_POST_PROCESSING_QUEUE_LOCAL=https://sqs.ap-northeast-2.amazonaws.com/your_aws_account_id/vivid-ai-post-processing-worker-queue-local
SQS_POST_PROCESSING_QUEUE_DEV=https://sqs.ap-northeast-2.amazonaws.com/your_aws_account_id/vivid-ai-post-processing-worker-queue-dev
SQS_POST_PROCESSING_QUEUE_PROD=https://sqs.ap-northeast-2.amazonaws.com/your_aws_account_id/vivid-ai-post-processing-worker-queue-prod

# S3 media bucket 이름 (환경별)
# ai-node-agent는 raw/ prefix에 생성 결과를 업로드합니다.
S3_TEMP_BUCKET_LOCAL_NAME=<local-media-bucket-name>
S3_TEMP_BUCKET_DEV_NAME=<dev-media-bucket-name>
S3_TEMP_BUCKET_PROD_NAME=<prod-media-bucket-name>

# workflow/system configuration bucket
S3_SYSTEM_CONFIGURATION_BUCKET_NAME=

# ComfyUI API 및 WebSocket URL
COMFY_API_URL=http://comfyui:8188/prompt
COMFY_WS_URL=ws://comfyui:8188/ws

# AI 노드 식별자
NODE_ID=local-ai-node-01

# ComfyUI shared directories
COMFY_INPUT_DIR=/app/input
COMFY_OUTPUT_DIR=/app/output
COMFY_TEMP_DIR=/app/temp

# Public relay
AI_AGENT_RELAY_HTTP_URL=
AI_AGENT_RELAY_WS_URL=
AI_AGENT_RELAY_TOKEN=

SQS 메시지 스키마 (`env` 필드)

ai-node-agent가 후처리 SQS 큐로 보내는 메시지 본문에는 env 필드가 추가되었습니다. 이 env 필드(예: "local" 또는 "dev")는 post-processing-worker가 어떤 환경의 S3 버킷과 SQS 큐를 사용할지 결정하는 데 사용됩니다.

메시지 예시:

{
  "creationId": "your-creation-id",
  "userId": "your-user-id",
  "raw_s3_path": "s3://<local-media-bucket-name>/raw/...",
  "originalFileName": "image.png",
  "env": "local",
  "expectedBatchSize": 1,
  "resultIndex": 0
}

실행 방법

ai-server는 Docker Compose를 사용하여 ComfyUI와 ai-node-agent를 함께 실행합니다.

# ai-server 디렉토리로 이동
cd ai-server

# .env 파일이 올바르게 설정되었는지 확인 후 컨테이너 빌드 및 실행
docker compose up -d --build

COMFY_INPUT_DIR, COMFY_OUTPUT_DIR, COMFY_TEMP_DIR과 Docker Compose/Kubernetes의 volume mount가 일치해야 합니다. ComfyUI가 생성한 파일을 ai-node-agent가 같은 경로에서 읽을 수 있어야 S3 raw/ 업로드와 post-processing queue enqueue가 정상 동작합니다. S3 bucket/prefix 기준은 S3 media bucket 설정을 따릅니다.

Production 배치 원칙

Prod에서는 ComfyUI와 ai-node-agent를 같은 Pod의 sidecar container로 묶는 구성을 우선 고려합니다.

Pod: ai-node
- container: comfyui
- container: ai-node-agent
- shared volume: input/output/temp

ComfyUI와 ai-node-agent를 별도 Deployment로 분리하려면 output 전달 방식, shared volume, network retry 전략을 별도로 설계해야 합니다.

개요​

ai-node-agent의 역할​

환경 변수 설정 (.env)​

SQS 메시지 스키마 (env 필드)​

실행 방법​

Production 배치 원칙​

개요

`ai-node-agent`의 역할

환경 변수 설정 (`.env`)

SQS 메시지 스키마 (`env` 필드)

실행 방법

Production 배치 원칙