45 KiB
45 KiB
설계안 2: Celery Callback Link + 에러 격리 파이프라인
link/link_error콜백과 단일 큐 + 우선순위 라우팅 기반 설계
목차
1. 개요 및 핵심 차이점
1.1 설계 철학
이 설계안은 **link(성공 콜백)과 link_error(실패 콜백)**을 활용하여 태스크 간 연결을 구현합니다.
기존안(celery-plan.md)은 태스크 내부에서 다음 단계를 apply_async()로 직접 호출하고,
설계안 1(chain)은 API에서 전체 순서를 선언합니다.
이 방식은 태스크 발행 시점에 콜백을 등록하여, 성공/실패에 따른 분기를 태스크 외부에서 제어합니다. 또한 단일 큐 + 우선순위 라우팅 전략으로 인프라를 단순화합니다.
┌─────────────────────────────────────────────────────────────────────────────┐
│ 3가지 방식 비교 │
├─────────────────────────┬───────────────────┬───────────────────────────────┤
│ 기존안 (명시적 전달) │ 설계안 1 (chain) │ 설계안 2 (callback link) │
├─────────────────────────┼───────────────────┼───────────────────────────────┤
│ 태스크 내부에서 │ API에서 전체 순서를│ 태스크 발행 시 성공/실패 │
│ 다음 태스크를 직접 호출 │ chain으로 선언 │ 콜백을 등록 │
│ │ │ │
│ A() 내부에서 B.delay() │ chain(A|B|C) │ A.apply_async( │
│ │ │ link=B.s(), │
│ │ │ link_error=err.s() │
│ │ │ ) │
├─────────────────────────┼───────────────────┼───────────────────────────────┤
│ 단순하지만 강한 결합 │ 선언적이지만 │ 유연한 성공/실패 분기 │
│ │ 부분 재시작 어려움 │ + 단일 큐로 인프라 단순화 │
└─────────────────────────┴───────────────────┴───────────────────────────────┘
1.2 핵심 원칙
┌─────────────────────────────────────────────────────────────────┐
│ 핵심 설계 원칙 │
├─────────────────────────────────────────────────────────────────┤
│ 1. 콜백 기반 연결: link/link_error로 성공/실패 분기 │
│ 2. 단일 큐 + 우선순위: 3개 큐 대신 1개 큐 + priority 사용 │
│ 3. 에러 격리: 각 단계별 독립 에러 핸들러 │
│ 4. 제어 역전: 태스크가 아닌 발행자가 다음 단계를 결정 │
└─────────────────────────────────────────────────────────────────┘
1.3 단일 큐 + 우선순위 전략
┌─────────────────────────────────────────────────────────────────────────────┐
│ 큐 전략 비교: 3개 큐 vs 1개 큐 + 우선순위 │
└─────────────────────────────────────────────────────────────────────────────┘
[기존안: 3개 독립 큐]
┌──────────┐ ┌──────────┐ ┌──────────┐
│lyric_q │ │ song_q │ │video_q │
│(Worker1) │ │(Worker2) │ │(Worker3) │
└──────────┘ └──────────┘ └──────────┘
• 장점: 완벽한 격리
• 단점: 워커 3개 항상 가동, 유휴 리소스 낭비
[이 설계안: 단일 큐 + 우선순위]
┌─────────────────────────────────────────┐
│ pipeline_queue │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │Priority │ │Priority │ │Priority │ │
│ │ 10 │ │ 5 │ │ 1 │ │
│ │(lyric) │ │ (song) │ │(video) │ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
│ 모든 워커가 모든 태스크 처리 가능 │
│ 우선순위로 실행 순서 자연스럽게 제어 │
└─────────────────────────────────────────┘
• 장점: 워커 풀 공유, 리소스 효율적
• 단점: 특정 유형의 태스크만 처리하는 워커 불가
2. 아키텍처 설계
2.1 전체 아키텍처
┌─────────────────────────────────────────────────────────────────────────────┐
│ Callback Link + 단일 큐 아키텍처 │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────┐
│ Client │
└──────┬──────┘
│
▼
┌────────────────────┐
│ FastAPI │
│ │
│ lyric.apply_async( │
│ link=song.s(), │◄── 성공 시 song 실행
│ link_error= │
│ err.s() │◄── 실패 시 에러 핸들러
│ ) │
└─────────┬──────────┘
│
▼
┌────────────────────────────────────┐
│ pipeline_queue │
│ (단일 큐, 우선순위 지원) │
│ │
│ Priority 10: Lyric 태스크 │
│ Priority 5: Song 태스크 │
│ Priority 1: Video 태스크 │
└───────────────┬────────────────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Worker 1 │ │ Worker 2 │ │ Worker 3 │
│ (모든 태스크) │ │ (모든 태스크) │ │ (모든 태스크) │
└───────────────┘ └───────────────┘ └───────────────┘
│ │ │
│ 각 워커는 lyric, song, video 모두 처리 가능│
│ 우선순위가 높은 태스크(lyric)를 먼저 실행 │
└─────────────────────┴─────────────────────┘
2.2 link/link_error 콜백 구조
┌─────────────────────────────────────────────────────────────────────────────┐
│ link/link_error 콜백 구조 │
└─────────────────────────────────────────────────────────────────────────────┘
lyric.apply_async(
kwargs={...},
link=song.s(), ◄── 성공 콜백: lyric 성공 → song 실행
link_error=lyric_error.s(), ◄── 실패 콜백: lyric 실패 → 에러 처리
)
내부 동작:
━━━━━━━━━
lyric_task 실행
│
┌──────────┼──────────┐
│ │
[성공 시] [실패 시]
│ │
▼ ▼
link 콜백 실행 link_error 콜백 실행
= song.s() 실행 = lyric_error.s() 실행
│ │
▼ ▼
song_task 실행 에러 로깅/알림
│ DLQ 저장
┌────┼────┐
│ │
[성공] [실패]
│ │
▼ ▼
video song_error
2.3 콜백 중첩 (Nested Callbacks)
# 전체 파이프라인을 콜백 중첩으로 표현
lyric_task.apply_async(
kwargs=initial_data,
priority=10, # 높은 우선순위
link=song_task.s().set(
priority=5, # 중간 우선순위
link=video_task.s().set(
priority=1, # 낮은 우선순위
link_error=video_error_handler.s()
),
link_error=song_error_handler.s()
),
link_error=lyric_error_handler.s()
)
# 풀어서 설명:
# lyric 성공 → song 실행
# song 성공 → video 실행
# video 성공 → 파이프라인 완료
# video 실패 → video_error_handler
# song 실패 → song_error_handler
# lyric 실패 → lyric_error_handler
3. 데이터 흐름 상세
3.1 시퀀스 다이어그램
sequenceDiagram
participant C as Client
participant API as FastAPI
participant Q as pipeline_queue
participant W1 as Worker (lyric)
participant W2 as Worker (song)
participant W3 as Worker (video)
participant EH as Error Handler
participant DB as MySQL
C->>API: POST /pipeline/start
API->>Q: lyric_task + link(song) + link_error(err)
API-->>C: {"task_id": "xxx"}
Q->>W1: lyric_task (priority=10)
W1->>DB: Lyric 생성 + ChatGPT
alt 성공
W1-->>Q: SUCCESS → link 콜백 발동
Note over Q: Celery가 자동으로 song_task를 큐에 발행
Q->>W2: song_task (priority=5)
W2->>DB: Song 생성 + Suno
alt 성공
W2-->>Q: SUCCESS → link 콜백 발동
Q->>W3: video_task (priority=1)
W3->>DB: Video 생성 + Creatomate
W3-->>Q: SUCCESS
Note over Q: 파이프라인 완료
else 실패
W2-->>EH: link_error → song_error_handler
EH->>DB: 실패 상태 기록
end
else 실패
W1-->>EH: link_error → lyric_error_handler
EH->>DB: 실패 상태 기록
end
3.2 우선순위 기반 태스크 처리
┌─────────────────────────────────────────────────────────────────────────────┐
│ 우선순위 기반 태스크 처리 │
└─────────────────────────────────────────────────────────────────────────────┘
시간축 →
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
T+0 pipeline_queue:
┌────────────────────────────────────────────────────────────┐
│ [P=10] lyric_A │ [P=10] lyric_B │ [P=5] song_X │ │
└────────────────────────────────────────────────────────────┘
Worker1 → lyric_A 처리 (P=10, 가장 높은 우선순위)
Worker2 → lyric_B 처리
T+5 lyric_A 완료 → link 콜백으로 song_A가 큐에 추가 (P=5)
┌────────────────────────────────────────────────────────────┐
│ [P=5] song_X │ [P=5] song_A │ │
└────────────────────────────────────────────────────────────┘
Worker1 → song_X 처리 (같은 우선순위면 FIFO)
T+60 song_X 완료 → video_X 추가 (P=1)
┌────────────────────────────────────────────────────────────┐
│ [P=5] song_A │ [P=1] video_X │ │
└────────────────────────────────────────────────────────────┘
Worker1 → song_A 처리 (P=5 > P=1)
※ video_X는 모든 song 태스크보다 낮은 우선순위
효과:
• 새로운 파이프라인 요청(lyric)이 가장 먼저 처리됨
• 이미 진행 중인 파이프라인의 후반 단계(video)는 자연스럽게 후순위
• 전체 처리량(throughput)보다 응답성(latency)을 우선시
3.3 데이터 전달 방식
┌─────────────────────────────────────────────────────────────────────────────┐
│ Callback에서의 데이터 전달 │
└─────────────────────────────────────────────────────────────────────────────┘
link 콜백에서 이전 태스크의 결과는 다음 태스크의 첫 번째 인자로 전달됩니다.
이는 chain과 동일한 동작입니다.
lyric_task 반환값:
{
"task_id": "xxx",
"lyric_id": 42,
"status": "completed"
}
│
│ link 콜백 발동
▼
song_task(prev_result={...}) ◄── 자동으로 첫 번째 인자
song_task 반환값:
{
"task_id": "xxx",
"song_id": 15,
"song_result_url": "...",
"status": "completed"
}
│
│ link 콜백 발동
▼
video_task(prev_result={...}) ◄── 자동으로 첫 번째 인자
4. 큐 및 태스크 동작 상세
4.1 단일 큐 설정
# Redis 큐 우선순위 설정
# Redis는 기본적으로 우선순위 큐를 지원하지 않지만,
# Celery가 priority_steps로 가상 우선순위를 구현합니다.
celery_app.conf.update(
# 브로커 전송 옵션
broker_transport_options={
'priority_steps': list(range(11)), # 0~10 우선순위 레벨
'sep': ':',
'queue_order_strategy': 'priority', # 우선순위 기반 처리
},
)
4.2 Redis에서의 우선순위 구현
┌─────────────────────────────────────────────────────────────────────────────┐
│ Redis 우선순위 큐 내부 구조 │
└─────────────────────────────────────────────────────────────────────────────┘
Celery가 Redis에서 우선순위를 구현하는 방법:
priority_steps=[0,1,2,3,4,5,6,7,8,9,10] 설정 시
Redis에 다음과 같은 키가 생성됩니다:
pipeline_queue (priority 0 - 가장 높음)
pipeline_queue\x06\x16\x01 (priority 1)
pipeline_queue\x06\x16\x02 (priority 2)
...
pipeline_queue\x06\x16\x0a (priority 10 - 가장 낮음)
워커가 BRPOP으로 여러 키를 동시에 감시하되,
낮은 번호(높은 우선순위) 키를 먼저 확인합니다.
이 프로젝트에서의 우선순위 할당:
lyric_task → priority=1 (가장 먼저 처리)
song_task → priority=5 (중간)
video_task → priority=9 (가장 나중에)
4.3 워커 동작
┌─────────────────────────────────────────────────────────────────────────────┐
│ 단일 큐 워커 동작 │
└─────────────────────────────────────────────────────────────────────────────┘
# 모든 워커가 하나의 큐를 구독
celery -A app.celery_app worker -Q pipeline_queue -c 4
동작 방식:
1. Worker가 pipeline_queue를 BRPOP으로 감시
2. 우선순위 높은 메시지부터 가져옴
3. 메시지의 task 타입에 따라 해당 함수 실행
4. 완료 시 link 콜백이 자동으로 다음 태스크 발행
모든 워커가 모든 태스크를 처리할 수 있으므로:
• 유휴 워커가 없음 (한 유형의 태스크가 없어도 다른 유형 처리)
• 특정 유형에 병목이 생기면 자연스럽게 모든 워커가 분담
• 스케일링이 단순: 워커 수만 조절하면 됨
5. 코드 구현
5.1 Celery 앱 설정
# app/celery_app.py
"""
Callback Link + 단일 큐 Celery 설정
핵심 차이점:
- 큐가 1개뿐 (pipeline_queue)
- 우선순위로 태스크 유형별 처리 순서 제어
- 모든 워커가 모든 태스크 처리 가능
"""
from celery import Celery
from kombu import Queue, Exchange
import os
celery_app = Celery(
'o2o_castad',
broker=os.getenv('CELERY_BROKER_URL', 'redis://localhost:6379/0'),
backend=os.getenv('CELERY_RESULT_BACKEND', 'redis://localhost:6379/1'),
include=[
'app.tasks.lyric_tasks',
'app.tasks.song_tasks',
'app.tasks.video_tasks',
'app.tasks.error_handlers', # 에러 핸들러 모듈
]
)
# ============================================================================
# 단일 큐 정의 (우선순위 지원)
# ============================================================================
pipeline_exchange = Exchange('pipeline', type='direct')
celery_app.conf.task_queues = (
Queue(
'pipeline_queue',
pipeline_exchange,
routing_key='pipeline',
queue_arguments={
'x-max-priority': 10, # 우선순위 범위: 0~10
}
),
)
# 기본 큐 설정 - 모든 태스크가 pipeline_queue로 라우팅
celery_app.conf.task_default_queue = 'pipeline_queue'
celery_app.conf.task_default_routing_key = 'pipeline'
# 우선순위 설정
celery_app.conf.broker_transport_options = {
'priority_steps': list(range(11)),
'sep': ':',
'queue_order_strategy': 'priority',
}
celery_app.conf.update(
task_serializer='json',
accept_content=['json'],
result_serializer='json',
timezone='Asia/Seoul',
enable_utc=True,
task_acks_late=True,
task_reject_on_worker_lost=True,
worker_prefetch_multiplier=1,
result_expires=86400,
result_extended=True,
)
5.2 에러 핸들러 모듈
# app/tasks/error_handlers.py
"""
단계별 에러 핸들러
link_error 콜백으로 사용되는 에러 처리 태스크입니다.
각 단계별로 독립된 에러 핸들러가 있어,
실패 원인에 맞는 대응이 가능합니다.
"""
import logging
import redis
import json
from datetime import datetime
from app.celery_app import celery_app
logger = logging.getLogger(__name__)
redis_client = redis.Redis.from_url(
celery_app.conf.result_backend,
decode_responses=True
)
# ============================================================================
# 공통 에러 핸들러 로직
# ============================================================================
def _handle_error(stage: str, request, exc, traceback):
"""
공통 에러 처리 로직
1. 로깅
2. Redis 상태 업데이트
3. DLQ 저장
4. 알림 발송 (선택)
"""
task_id = 'unknown'
# link_error 콜백에서는 request 객체로 원본 태스크 정보 접근
if hasattr(request, 'kwargs') and request.kwargs:
# 원본 태스크의 kwargs에서 task_id 추출
if isinstance(request.kwargs, dict):
task_id = request.kwargs.get('task_id', 'unknown')
# prev_result에서 추출 (chain/link에서 전달된 경우)
elif hasattr(request, 'args') and request.args:
first_arg = request.args[0]
if isinstance(first_arg, dict):
task_id = first_arg.get('task_id', 'unknown')
logger.error(
f"[{stage.upper()} ERROR] task_id={task_id}, error={exc}",
exc_info=True
)
# Redis 상태 업데이트
pipeline_key = f"pipeline:{task_id}:status"
stage_key = f"pipeline:{task_id}:{stage}"
redis_client.hset(pipeline_key, mapping={
'current_stage': stage,
'status': 'failed',
})
redis_client.hset(stage_key, mapping={
'status': 'failed',
'error': str(exc),
'failed_at': datetime.utcnow().isoformat(),
})
redis_client.expire(pipeline_key, 86400)
redis_client.expire(stage_key, 86400)
# DLQ에 실패 정보 저장
redis_client.lpush('failed_tasks', json.dumps({
'stage': stage,
'task_id': task_id,
'error': str(exc),
'traceback': str(traceback),
'failed_at': datetime.utcnow().isoformat(),
}))
# ============================================================================
# 단계별 에러 핸들러
# ============================================================================
@celery_app.task(name='app.tasks.error_handlers.lyric_error_handler')
def lyric_error_handler(request, exc, traceback):
"""
가사 생성 실패 핸들러
ChatGPT API 실패 원인:
- API 키 만료
- Rate limit 초과
- 네트워크 타임아웃
- 잘못된 프롬프트
"""
_handle_error('lyric', request, exc, traceback)
# 가사 실패 시 추가 처리:
# - API 키 상태 확인 알림 발송
# - Rate limit인 경우 자동 재시도 예약 (선택)
@celery_app.task(name='app.tasks.error_handlers.song_error_handler')
def song_error_handler(request, exc, traceback):
"""
노래 생성 실패 핸들러
Suno API 실패 원인:
- 생성 타임아웃
- Rate limit
- 오디오 다운로드 실패
- Azure 업로드 실패
"""
_handle_error('song', request, exc, traceback)
# 노래 실패 시 추가 처리:
# - 가사는 이미 완료됨 → 재시도 시 가사부터 안해도 됨
# - Suno 크레딧 확인 알림
@celery_app.task(name='app.tasks.error_handlers.video_error_handler')
def video_error_handler(request, exc, traceback):
"""
비디오 생성 실패 핸들러
Creatomate 실패 원인:
- 렌더링 타임아웃
- 템플릿 오류
- 이미지 로드 실패
- Azure 업로드 실패
"""
_handle_error('video', request, exc, traceback)
# 비디오 실패 시 추가 처리:
# - 가사 + 노래 모두 완료 상태 → 비디오만 재시도 가능
# - Creatomate 크레딧 확인 알림
5.3 가사 생성 태스크
# app/tasks/lyric_tasks.py
"""
가사 생성 태스크 (Callback Link 방식)
chain 방식과 유사하게, 이 태스크는 다음 단계를 모릅니다.
결과를 반환하면 link 콜백이 자동으로 다음 태스크를 실행합니다.
핵심 차이점: 우선순위 설정 (priority=1, 가장 높음)
"""
from sqlalchemy import select
import asyncio
import logging
from app.celery_app import celery_app
from app.tasks.base import BaseTaskWithDB
from app.home.models import Project
from app.lyric.models import Lyric
from app.utils.chatgpt_prompt import ChatgptService
from app.utils.prompts.prompts import Prompt
logger = logging.getLogger(__name__)
@celery_app.task(
base=BaseTaskWithDB,
bind=True,
name='app.tasks.lyric_tasks.generate_lyric',
max_retries=3,
default_retry_delay=30,
acks_late=True,
# ────────────────────────────────────────────
# 단일 큐에서는 큐 이름 대신 우선순위로 구분
# priority=1 → 가장 먼저 처리
# ────────────────────────────────────────────
)
def generate_lyric(self, data: dict) -> dict:
"""
가사 생성 태스크
반환값이 link 콜백(song_task)의 첫 번째 인자가 됩니다.
Args:
data: 초기 파이프라인 데이터
Returns:
dict: 다음 태스크에 전달될 결과
"""
task_id = data['task_id']
self.update_pipeline_status(
task_id=task_id, stage='lyric', status='processing',
message='가사 생성 시작'
)
async def _generate():
async with self.get_db_session() as session:
project = await session.scalar(
select(Project).where(Project.task_id == task_id)
)
if not project:
project = Project(
task_id=task_id,
customer_name=data['customer_name'],
region=data['region'],
)
session.add(project)
await session.flush()
prompt = Prompt(
customer_name=data['customer_name'],
region=data['region'],
detail_region_info=data['detail_region_info'],
language=data.get('language', 'Korean'),
)
lyric_prompt = prompt.get_full_prompt()
lyric = Lyric(
project_id=project.id,
task_id=task_id,
status='processing',
lyric_prompt=lyric_prompt,
language=data.get('language', 'Korean'),
)
session.add(lyric)
await session.commit()
lyric_id = lyric.id
# ChatGPT 호출 (DB 세션 외부)
try:
chatgpt = ChatgptService()
lyric_result = await chatgpt.generate_lyric(lyric_prompt)
if not lyric_result or len(lyric_result.strip()) < 50:
raise ValueError("가사가 너무 짧음")
except Exception as e:
async with self.get_db_session() as session:
lyric = await session.get(Lyric, lyric_id)
lyric.status = 'failed'
lyric.lyric_result = f"Error: {str(e)}"
await session.commit()
raise
# 결과 저장
async with self.get_db_session() as session:
lyric = await session.get(Lyric, lyric_id)
lyric.status = 'completed'
lyric.lyric_result = lyric_result
await session.commit()
return {
'task_id': task_id,
'lyric_id': lyric_id,
'lyric_result': lyric_result,
'language': data.get('language', 'Korean'),
'status': 'completed',
}
result = self.run_async(_generate())
self.update_pipeline_status(
task_id=task_id, stage='lyric', status='completed',
message='가사 생성 완료'
)
# ────────────────────────────────────────────────────────────
# 다음 태스크를 직접 호출하지 않음!
# link 콜백이 자동으로 이 결과를 song_task에 전달합니다.
# ────────────────────────────────────────────────────────────
return result
5.4 노래/비디오 태스크
노래 및 비디오 태스크는 설계안 1(chain)과 구조적으로 동일합니다.
prev_result를 첫 번째 인자로 받아 처리하고, 결과를 반환합니다.
설계안 1의
song_tasks.py,video_tasks.py를 그대로 사용합니다. 유일한 차이:queue지정이 없음 (단일 큐이므로)
5.5 파이프라인 API (핵심 차이점)
# app/api/routers/v1/pipeline.py
"""
Callback Link 기반 파이프라인 API
핵심 차이점:
1. chain() 대신 link/link_error 콜백 사용
2. 단일 큐에 우선순위로 발행
3. 각 단계별 독립 에러 핸들러 등록
"""
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel
from app.dependencies.auth import get_current_user
from app.tasks.lyric_tasks import generate_lyric
from app.tasks.song_tasks import generate_song
from app.tasks.video_tasks import generate_video
from app.tasks.error_handlers import (
lyric_error_handler,
song_error_handler,
video_error_handler,
)
router = APIRouter(prefix="/pipeline", tags=["Pipeline"])
class StartPipelineRequest(BaseModel):
task_id: str
customer_name: str
region: str
detail_region_info: str
language: str = "Korean"
orientation: str = "vertical"
genre: str = "pop, ambient"
@router.post("/start")
async def start_pipeline(
request: StartPipelineRequest,
current_user=Depends(get_current_user)
):
"""
파이프라인 시작 (Callback Link 방식)
link/link_error를 중첩하여 전체 파이프라인을 구성합니다.
각 단계별로 독립된 에러 핸들러가 등록됩니다.
"""
initial_data = {
"task_id": request.task_id,
"customer_name": request.customer_name,
"region": request.region,
"detail_region_info": request.detail_region_info,
"language": request.language,
}
# ────────────────────────────────────────────────────────────────
# 핵심: 콜백 중첩으로 파이프라인 구성
# ────────────────────────────────────────────────────────────────
#
# 읽는 순서: 안쪽부터 바깥으로
# video_task ← song 성공 시 실행 (priority=9)
# song_task ← lyric 성공 시 실행 (priority=5)
# lyric_task ← 즉시 실행 (priority=1)
#
# 에러 핸들러: 각 단계별 독립
# lyric 실패 → lyric_error_handler
# song 실패 → song_error_handler
# video 실패 → video_error_handler
result = generate_lyric.apply_async(
kwargs={'data': initial_data},
priority=1, # 가장 높은 우선순위
# lyric 성공 시 → song 실행
link=generate_song.s(
genre=request.genre,
).set(
priority=5, # 중간 우선순위
# song 성공 시 → video 실행
link=generate_video.s(
orientation=request.orientation,
).set(
priority=9, # 가장 낮은 우선순위
link_error=video_error_handler.s(), # video 실패 시
),
link_error=song_error_handler.s(), # song 실패 시
),
link_error=lyric_error_handler.s(), # lyric 실패 시
)
return {
'success': True,
'task_id': request.task_id,
'celery_task_id': result.id,
'message': '파이프라인이 시작되었습니다.',
}
@router.post("/retry/{task_id}/{stage}")
async def retry_stage(
task_id: str,
stage: str,
current_user=Depends(get_current_user)
):
"""
특정 단계 재시도
실패한 단계부터 콜백을 다시 구성하여 재시작합니다.
"""
if stage == 'song':
# DB에서 lyric 결과 조회 후 song부터 재시작
lyric_result = await _get_lyric_result(task_id)
result = generate_song.apply_async(
args=(lyric_result,),
priority=5,
link=generate_video.s().set(
priority=9,
link_error=video_error_handler.s(),
),
link_error=song_error_handler.s(),
)
elif stage == 'video':
song_result = await _get_song_result(task_id)
result = generate_video.apply_async(
args=(song_result,),
priority=9,
link_error=video_error_handler.s(),
)
return {'resumed_from': stage, 'task_id': result.id}
6. 상태 관리 및 모니터링
6.1 상태 추적
기존안의 Redis 커스텀 상태(pipeline:{task_id}:*)를 그대로 사용합니다.
추가로 에러 핸들러에서도 상태를 업데이트합니다.
6.2 Flower 모니터링
# 단일 큐이므로 더 단순한 모니터링
celery -A app.celery_app flower --port=5555
# Flower에서 볼 수 있는 정보:
# - pipeline_queue의 대기 태스크 수 (전체)
# - 태스크 유형별 필터링 (lyric/song/video)
# - 우선순위별 분포
7. 실패 처리 전략
7.1 단계별 독립 에러 핸들링
┌─────────────────────────────────────────────────────────────────────────────┐
│ 에러 격리 전략 │
└─────────────────────────────────────────────────────────────────────────────┘
이 방식의 가장 큰 장점: 각 단계별로 독립된 에러 핸들러
[기존안/chain]
─────────────
모든 실패 → 동일한 에러 처리 또는 chain 자체 실패
[이 방식]
─────────
lyric 실패 → lyric_error_handler
├─ ChatGPT API 키 확인
├─ Rate limit 대기 후 재시도 예약
└─ 관리자에게 API 상태 알림
song 실패 → song_error_handler
├─ Suno 크레딧 확인
├─ 이미 완료된 lyric 보존
└─ song만 재시도 가능
video 실패 → video_error_handler
├─ Creatomate 렌더링 오류 분석
├─ 이미 완료된 lyric + song 보존
└─ video만 재시도 가능
각 에러 핸들러는 해당 단계의 실패 원인에 맞는 구체적인 대응이 가능합니다.
이것이 "에러 격리"의 핵심입니다.
8. 설계 및 동작 설명
8.1 link vs chain vs 명시적 전달 상세 비교
┌─────────────────────────────────────────────────────────────────────────────┐
│ 태스크가 다음 단계를 "아는가"에 따른 분류 │
└─────────────────────────────────────────────────────────────────────────────┘
태스크가 다음 단계를 안다?
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
[안다 (Yes)] [모른다 (No)] [모른다 (No)]
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌───────────┐ ┌──────────────┐
│ 기존안 │ │ 설계안 1 │ │ 설계안 2 │
│ (명시적 전달)│ │ (chain) │ │ (link 콜백) │
└─────────────┘ └───────────┘ └──────────────┘
│ │ │
▼ ▼ ▼
다음 단계 지식이 API에서 chain API에서 link
태스크 코드에 선언 콜백으로 연결
하드코딩 (파이프라인만) (에러 핸들러도
단계별 등록)
8.2 단일 큐의 장단점
┌─────────────────────────────────────────────────────────────────────────────┐
│ 단일 큐 장단점 분석 │
└─────────────────────────────────────────────────────────────────────────────┘
장점:
─────
✓ 인프라 단순화: Redis 큐 1개, 워커 타입 1개
✓ 리소스 효율: 유휴 워커 없음, 모든 워커가 모든 작업 처리
✓ 스케일링 단순: 워커 수만 조절
✓ 운영 부담 감소: 워커 3종류 → 1종류 관리
단점:
─────
✗ 격리 불가: video 작업이 lyric 워커 리소스 사용 가능
✗ 리소스 불균형: ChatGPT(가벼움)와 Creatomate(무거움) 같은 워커
✗ 우선순위 한계: Redis 우선순위가 RabbitMQ만큼 정확하지 않음
✗ 특정 워커 튜닝 불가: 메모리, CPU 한도를 태스크 유형별로 설정 불가
이 프로젝트에서의 판단:
──────────────────────
• 트래픽이 적은 초기 단계에서는 단일 큐가 효율적
• 트래픽 증가 시 3개 큐로 전환 가능 (호환됨)
• 우선순위로 "새 요청 우선 처리"가 가능하여 UX 향상
9. 기존안과의 비교
┌──────────────────────┬──────────────┬──────────────┬──────────────┐
│ 기준 │ 기존안 │ 설계안 1 │ 설계안 2 │
│ │ (명시적 전달)│ (chain) │ (link+단일큐)│
├──────────────────────┼──────────────┼──────────────┼──────────────┤
│ 큐 구성 │ 3개 독립 큐 │ 3개 독립 큐 │ 1개 우선순위 │
│ 워커 구성 │ 3종류 │ 3종류 │ 1종류 │
│ 태스크 독립성 │ 중간 │ 높음 │ 높음 │
│ 에러 핸들링 │ 태스크 내 │ link_error │ 단계별 독립 │
│ 부분 재시작 │ 쉬움 │ 약간 번거로움│ 쉬움 │
│ 인프라 복잡도 │ 중간 │ 중간 │ 낮음 │
│ 리소스 효율 │ 중간 │ 중간 │ 높음 │
│ 적합한 규모 │ 중~대 │ 중 │ 소~중 │
│ Celery 숙련도 │ 초급 │ 중급 │ 중급 │
└──────────────────────┴──────────────┴──────────────┴──────────────┘
10. 배포 및 운영
10.1 실행 명령어
# 워커 실행 - 모든 워커가 동일한 큐 구독
# 워커 수만 조절하면 됨
celery -A app.celery_app worker -Q pipeline_queue -c 4 -n worker1@%h
celery -A app.celery_app worker -Q pipeline_queue -c 4 -n worker2@%h
celery -A app.celery_app worker -Q pipeline_queue -c 4 -n worker3@%h
# 또는 단일 워커로 시작 (개발환경)
celery -A app.celery_app worker -Q pipeline_queue -c 4 -n dev@%h
10.2 Docker Compose
# docker-compose.yml (단순화됨)
version: '3.8'
services:
redis:
image: redis:7-alpine
ports: ["6379:6379"]
api:
build: .
ports: ["8000:8000"]
command: uvicorn main:app --host 0.0.0.0 --port 8000
# 워커가 1종류뿐이므로 스케일링이 단순
worker:
build: .
command: celery -A app.celery_app worker -Q pipeline_queue -c 4
deploy:
replicas: 3 # 워커 3개 (모든 태스크 처리)
문서 버전
| 버전 | 날짜 | 변경 내용 |
|---|---|---|
| 1.0 | 2024-XX-XX | 초안 작성 |