1451 lines
58 KiB
Markdown
1451 lines
58 KiB
Markdown
# 설계안 1: Celery Chain Primitive 파이프라인
|
|
|
|
> **Celery Canvas의 `chain()` 원시 타입을 활용한 선언적 파이프라인 설계**
|
|
|
|
---
|
|
|
|
## 목차
|
|
|
|
1. [개요 및 핵심 차이점](#1-개요-및-핵심-차이점)
|
|
2. [아키텍처 설계](#2-아키텍처-설계)
|
|
3. [데이터 흐름 상세](#3-데이터-흐름-상세)
|
|
4. [큐 및 태스크 동작 상세](#4-큐-및-태스크-동작-상세)
|
|
5. [코드 구현](#5-코드-구현)
|
|
6. [상태 관리 및 모니터링](#6-상태-관리-및-모니터링)
|
|
7. [실패 처리 전략](#7-실패-처리-전략)
|
|
8. [설계 및 동작 설명](#8-설계-및-동작-설명)
|
|
9. [기존안과의 비교](#9-기존안과의-비교)
|
|
10. [배포 및 운영](#10-배포-및-운영)
|
|
|
|
---
|
|
|
|
## 1. 개요 및 핵심 차이점
|
|
|
|
### 1.1 설계 철학
|
|
|
|
이 설계안은 Celery Canvas의 **`chain()` 원시 타입**을 사용하여 파이프라인을 **선언적으로 정의**합니다.
|
|
|
|
기존안(`celery-plan.md`)에서는 각 태스크가 완료 후 다음 큐에 **명시적으로 `apply_async()`를 호출**하는 반면,
|
|
이 방식에서는 파이프라인 시작 시점에 **전체 실행 순서를 한 번에 선언**합니다.
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ 기존안 vs 이 설계안 │
|
|
├────────────────────────────────┬────────────────────────────────────────────┤
|
|
│ 기존안 (명시적 전달) │ 설계안 1 (Chain Primitive) │
|
|
├────────────────────────────────┼────────────────────────────────────────────┤
|
|
│ lyric_task 내부에서 │ API에서 전체 체인을 한 번에 선언: │
|
|
│ song_task.apply_async() │ chain( │
|
|
│ 호출 │ lyric.s() | song.s() | video.s() │
|
|
│ │ ).apply_async() │
|
|
│ │ │
|
|
│ 각 태스크가 다음 단계를 "안다" │ 각 태스크는 다음 단계를 "모른다" │
|
|
│ (강한 흐름 결합) │ (Celery가 자동으로 체이닝) │
|
|
│ │ │
|
|
│ 태스크 A → 직접 발행 → 태스크 B│ 태스크 A → 결과 반환 → Celery → 태스크 B │
|
|
└────────────────────────────────┴────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 1.2 핵심 원칙
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 핵심 설계 원칙 │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 1. 선언적 파이프라인: 실행 순서를 코드 한 줄로 정의 │
|
|
│ 2. 결과 전파: 이전 태스크의 반환값이 다음 태스크의 입력 │
|
|
│ 3. 순수 함수: 각 태스크는 자신의 다음 단계를 모름 │
|
|
│ 4. 단일 진입점: API에서 chain을 생성, 전체 흐름을 제어 │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 2. 아키텍처 설계
|
|
|
|
### 2.1 전체 아키텍처
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ Chain Primitive 파이프라인 아키텍처 │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────┐
|
|
│ Client │
|
|
└──────┬──────┘
|
|
│ POST /pipeline/start
|
|
▼
|
|
┌────────────────────┐
|
|
│ FastAPI │
|
|
│ │
|
|
│ chain( │
|
|
│ lyric.s(data) │◄── 파이프라인을 한 번에 선언
|
|
│ | song.s() │
|
|
│ | video.s() │
|
|
│ ).apply_async() │
|
|
└─────────┬──────────┘
|
|
│
|
|
│ chain 메시지 발행
|
|
▼
|
|
┌────────────────────┐
|
|
│ Redis Broker │
|
|
│ │
|
|
│ chain 메타데이터: │
|
|
│ task1 → task2 → │
|
|
│ task3 순서 보관 │
|
|
└─────────┬──────────┘
|
|
│
|
|
┌─────────────────┼─────────────────┐
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
|
│ lyric_queue │ │ song_queue │ │ video_queue │
|
|
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
|
│ Lyric Worker │ │ Song Worker │ │ Video Worker │
|
|
│ │ │ │ │ │
|
|
│ 입력: data │ │ 입력: lyric의 │ │ 입력: song의 │
|
|
│ 출력: result │ │ 반환값 │ │ 반환값 │
|
|
│ (자동 전달) │ │ 출력: result │ │ 출력: result │
|
|
└───────────────┘ └───────────────┘ └───────────────┘
|
|
```
|
|
|
|
### 2.2 chain()의 내부 동작
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ chain()이 내부적으로 하는 일 │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
chain(lyric.s(data) | song.s() | video.s()).apply_async()
|
|
│ │ │
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
|
|
Celery가 내부적으로 다음과 같이 변환:
|
|
|
|
1. lyric.apply_async(
|
|
args=(data,),
|
|
link=song.s().set(link=video.s()) ◄── 콜백 체인 설정
|
|
)
|
|
|
|
2. lyric 완료 시:
|
|
song.apply_async(
|
|
args=(lyric_result,), ◄── 이전 결과가 첫 번째 인자로
|
|
link=video.s()
|
|
)
|
|
|
|
3. song 완료 시:
|
|
video.apply_async(
|
|
args=(song_result,), ◄── 이전 결과가 첫 번째 인자로
|
|
)
|
|
|
|
핵심: 각 태스크의 "반환값"이 다음 태스크의 "첫 번째 인자"로 자동 전달됨
|
|
```
|
|
|
|
### 2.3 큐 설계 (기존안과 동일)
|
|
|
|
```python
|
|
# 큐 구성은 기존안과 동일하게 3개 독립 큐 사용
|
|
# 차이점: 메시지 발행 방식만 다름 (chain이 자동으로 라우팅)
|
|
|
|
CELERY_QUEUES = {
|
|
'lyric_queue': {'routing_key': 'lyric.generate'},
|
|
'song_queue': {'routing_key': 'song.generate'},
|
|
'video_queue': {'routing_key': 'video.generate'},
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 데이터 흐름 상세
|
|
|
|
### 3.1 핵심 차이: 결과 전파 방식
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant C as Client
|
|
participant API as FastAPI
|
|
participant CE as Celery Engine
|
|
participant LW as Lyric Worker
|
|
participant SW as Song Worker
|
|
participant VW as Video Worker
|
|
participant DB as MySQL
|
|
|
|
C->>API: POST /pipeline/start
|
|
|
|
Note over API: chain 선언
|
|
API->>CE: chain(lyric.s(data) | song.s() | video.s())
|
|
|
|
Note over CE: 1단계: lyric_queue에 발행
|
|
CE->>LW: lyric_task(data)
|
|
LW->>DB: Lyric 생성 + ChatGPT 호출
|
|
LW-->>CE: return {"task_id": "xxx", "lyric_result": "..."}
|
|
|
|
Note over CE: 2단계: 자동으로 song_queue에 발행 (lyric 결과 포함)
|
|
CE->>SW: song_task({"task_id": "xxx", "lyric_result": "..."})
|
|
SW->>DB: Song 생성 + Suno API 호출
|
|
SW-->>CE: return {"task_id": "xxx", "song_url": "..."}
|
|
|
|
Note over CE: 3단계: 자동으로 video_queue에 발행 (song 결과 포함)
|
|
CE->>VW: video_task({"task_id": "xxx", "song_url": "..."})
|
|
VW->>DB: Video 생성 + Creatomate 호출
|
|
VW-->>CE: return {"task_id": "xxx", "video_url": "..."}
|
|
|
|
Note over CE: chain 완료
|
|
CE-->>C: (상태 조회 API로 확인)
|
|
```
|
|
|
|
### 3.2 단계별 데이터 형식
|
|
|
|
```python
|
|
# 각 태스크의 입출력 형식 정의
|
|
|
|
# ─────────────────────────────────────────
|
|
# Lyric Task (chain의 첫 번째)
|
|
# ─────────────────────────────────────────
|
|
# 입력: API에서 전달하는 초기 데이터
|
|
lyric_input = {
|
|
"task_id": "0192abc-...",
|
|
"customer_name": "스테이 머뭄",
|
|
"region": "군산",
|
|
"detail_region_info": "군산 신흥동",
|
|
"language": "Korean",
|
|
}
|
|
|
|
# 출력: 다음 태스크(song)의 입력이 됨
|
|
lyric_output = {
|
|
"task_id": "0192abc-...",
|
|
"lyric_id": 42,
|
|
"lyric_result": "아침 햇살 가득한 카페 머뭄에서...",
|
|
"language": "Korean",
|
|
"status": "completed",
|
|
}
|
|
|
|
# ─────────────────────────────────────────
|
|
# Song Task (chain의 두 번째)
|
|
# ─────────────────────────────────────────
|
|
# 입력: lyric_output이 자동으로 전달됨
|
|
# song_input = lyric_output (동일 구조)
|
|
|
|
# 출력: 다음 태스크(video)의 입력이 됨
|
|
song_output = {
|
|
"task_id": "0192abc-...",
|
|
"lyric_id": 42,
|
|
"song_id": 15,
|
|
"song_result_url": "https://blob.azure.../song.mp3",
|
|
"duration": 62.5,
|
|
"status": "completed",
|
|
}
|
|
|
|
# ─────────────────────────────────────────
|
|
# Video Task (chain의 마지막)
|
|
# ─────────────────────────────────────────
|
|
# 입력: song_output이 자동으로 전달됨
|
|
# video_input = song_output (동일 구조)
|
|
|
|
# 출력: 최종 파이프라인 결과
|
|
video_output = {
|
|
"task_id": "0192abc-...",
|
|
"video_id": 8,
|
|
"result_movie_url": "https://blob.azure.../video.mp4",
|
|
"status": "completed",
|
|
}
|
|
```
|
|
|
|
### 3.3 상태 전이 다이어그램
|
|
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> chain_created: chain().apply_async()
|
|
|
|
state "Chain Execution" as ChainExec {
|
|
chain_created --> lyric_running: Celery가 lyric_queue에 발행
|
|
lyric_running --> lyric_done: return lyric_output
|
|
|
|
lyric_done --> song_running: Celery가 song_output를 song_queue에 자동 발행
|
|
song_running --> song_done: return song_output
|
|
|
|
song_done --> video_running: Celery가 video_queue에 자동 발행
|
|
video_running --> video_done: return video_output
|
|
}
|
|
|
|
video_done --> [*]: chain 완료
|
|
|
|
lyric_running --> chain_failed: 예외 발생 (max_retries 초과)
|
|
song_running --> chain_failed: 예외 발생
|
|
video_running --> chain_failed: 예외 발생
|
|
|
|
chain_failed --> [*]: link_error 콜백 실행
|
|
```
|
|
|
|
---
|
|
|
|
## 4. 큐 및 태스크 동작 상세
|
|
|
|
### 4.1 chain이 큐를 활용하는 방식
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ chain이 큐를 활용하는 방식 │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
chain 생성 시점 (API 서버):
|
|
━━━━━━━━━━━━━━━━━━━━━━━━━
|
|
|
|
pipeline = chain(
|
|
generate_lyric.s(data).set(queue='lyric_queue'), # ① 큐 지정
|
|
generate_song.s().set(queue='song_queue'), # ② 큐 지정
|
|
generate_video.s().set(queue='video_queue'), # ③ 큐 지정
|
|
)
|
|
pipeline.apply_async()
|
|
|
|
Celery 내부 처리:
|
|
━━━━━━━━━━━━━━━━
|
|
|
|
[T+0ms] lyric_queue에 메시지 발행
|
|
메시지 내부에 "다음 태스크 정보" 포함:
|
|
{
|
|
"task": "generate_lyric",
|
|
"kwargs": {"task_id": "...", ...},
|
|
"callbacks": [ ◄── chain의 다음 단계 정보
|
|
{
|
|
"task": "generate_song",
|
|
"queue": "song_queue",
|
|
"callbacks": [
|
|
{
|
|
"task": "generate_video",
|
|
"queue": "video_queue"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
|
|
[T+5s] Lyric Worker가 lyric_queue에서 메시지 수신
|
|
generate_lyric 실행
|
|
결과 반환: {"task_id": "...", "lyric_result": "..."}
|
|
|
|
[T+5s] Celery Engine이 자동으로:
|
|
1. 결과를 callbacks[0]의 첫 번째 인자로 설정
|
|
2. song_queue에 메시지 발행
|
|
|
|
[T+10s] Song Worker가 song_queue에서 메시지 수신
|
|
generate_song(lyric_result) 실행
|
|
결과 반환
|
|
|
|
[T+10s] Celery Engine이 자동으로:
|
|
1. 결과를 다음 callback의 첫 번째 인자로
|
|
2. video_queue에 메시지 발행
|
|
|
|
[T+20s] Video Worker가 video_queue에서 메시지 수신
|
|
최종 처리
|
|
```
|
|
|
|
### 4.2 워커 격리 (기존안과 동일)
|
|
|
|
```bash
|
|
# 각 워커는 자신의 큐만 구독 (변경 없음)
|
|
celery -A app.celery_app worker -Q lyric_queue -n lyric@%h
|
|
celery -A app.celery_app worker -Q song_queue -n song@%h
|
|
celery -A app.celery_app worker -Q video_queue -n video@%h
|
|
|
|
# chain이 큐를 지정하므로, 워커 격리는 자동으로 보장됨
|
|
```
|
|
|
|
### 4.3 chain의 메시지 크기 주의점
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ chain 메시지 크기 주의점 │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
문제:
|
|
chain에서 이전 태스크의 반환값이 다음 태스크의 인자로 전달되므로,
|
|
반환값이 크면 Redis 메시지 크기가 커집니다.
|
|
|
|
예시:
|
|
lyric_result가 10KB → song_task 메시지에 10KB 포함
|
|
song_result에 audio_url만 포함 → 작은 크기
|
|
|
|
대응 전략:
|
|
✓ 반환값에는 ID와 URL만 포함 (경량 데이터)
|
|
✓ 대용량 데이터(가사 전문, 오디오)는 DB에 저장
|
|
✓ 다음 태스크가 DB에서 필요한 데이터를 직접 조회
|
|
|
|
권장 반환값 크기: < 1KB
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 코드 구현
|
|
|
|
### 5.1 Celery 앱 설정
|
|
|
|
```python
|
|
# app/celery_app.py
|
|
"""
|
|
Celery 앱 설정 (기존안과 동일한 큐 구조)
|
|
|
|
Chain에서는 task_routes 설정이 중요합니다.
|
|
chain에서 .set(queue=...) 를 생략하면 task_routes로 라우팅됩니다.
|
|
"""
|
|
|
|
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',
|
|
]
|
|
)
|
|
|
|
# 큐 정의 (기존안과 동일)
|
|
celery_app.conf.task_queues = (
|
|
Queue('lyric_queue', Exchange('lyric', type='direct'), routing_key='lyric.generate'),
|
|
Queue('song_queue', Exchange('song', type='direct'), routing_key='song.generate'),
|
|
Queue('video_queue', Exchange('video', type='direct'), routing_key='video.generate'),
|
|
)
|
|
|
|
# 태스크 라우팅 - chain에서 자동으로 사용됨
|
|
celery_app.conf.task_routes = {
|
|
'app.tasks.lyric_tasks.*': {'queue': 'lyric_queue'},
|
|
'app.tasks.song_tasks.*': {'queue': 'song_queue'},
|
|
'app.tasks.video_tasks.*': {'queue': 'video_queue'},
|
|
}
|
|
|
|
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 가사 생성 태스크
|
|
|
|
```python
|
|
# app/tasks/lyric_tasks.py
|
|
"""
|
|
가사 생성 태스크 (Chain 방식)
|
|
|
|
핵심 차이점:
|
|
- 이 태스크는 다음 단계(song)에 대해 전혀 모릅니다.
|
|
- 단순히 자신의 작업을 수행하고 결과를 반환할 뿐입니다.
|
|
- chain()이 자동으로 반환값을 다음 태스크에 전달합니다.
|
|
- "다음 큐에 apply_async()"하는 코드가 없습니다.
|
|
"""
|
|
|
|
from celery import Task
|
|
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,
|
|
)
|
|
def generate_lyric(self, data: dict) -> dict:
|
|
"""
|
|
가사 생성 태스크
|
|
|
|
chain()에서 첫 번째로 실행됩니다.
|
|
반환값이 자동으로 다음 태스크(generate_song)의 입력이 됩니다.
|
|
|
|
Args:
|
|
data: {
|
|
"task_id": str,
|
|
"customer_name": str,
|
|
"region": str,
|
|
"detail_region_info": str,
|
|
"language": str
|
|
}
|
|
|
|
Returns:
|
|
dict: {
|
|
"task_id": str,
|
|
"lyric_id": int,
|
|
"lyric_result": str, ← 경량화: 가사 전문 대신 DB에서 조회하도록 유도
|
|
"language": str,
|
|
"status": "completed"
|
|
}
|
|
→ 이 반환값이 generate_song의 첫 번째 인자로 자동 전달됨
|
|
|
|
독립성 보장:
|
|
- 이 태스크는 generate_song, generate_video의 존재를 모릅니다.
|
|
- 자신의 작업(ChatGPT 가사 생성)만 수행합니다.
|
|
- 반환값을 chain이 자동으로 전파합니다.
|
|
"""
|
|
task_id = data['task_id']
|
|
customer_name = data['customer_name']
|
|
region = data['region']
|
|
detail_region_info = data['detail_region_info']
|
|
language = data.get('language', 'Korean')
|
|
|
|
# 파이프라인 상태 업데이트
|
|
self.update_pipeline_status(
|
|
task_id=task_id,
|
|
stage='lyric',
|
|
status='processing',
|
|
message='가사 생성을 시작합니다.'
|
|
)
|
|
|
|
async def _generate():
|
|
# ────────────────────────────────────────────────
|
|
# 1단계: DB 레코드 생성
|
|
# ────────────────────────────────────────────────
|
|
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=customer_name,
|
|
region=region,
|
|
)
|
|
session.add(project)
|
|
await session.flush()
|
|
|
|
prompt = Prompt(
|
|
customer_name=customer_name,
|
|
region=region,
|
|
detail_region_info=detail_region_info,
|
|
language=language,
|
|
)
|
|
lyric_prompt = prompt.get_full_prompt()
|
|
|
|
lyric = Lyric(
|
|
project_id=project.id,
|
|
task_id=task_id,
|
|
status='processing',
|
|
lyric_prompt=lyric_prompt,
|
|
language=language,
|
|
)
|
|
session.add(lyric)
|
|
await session.commit()
|
|
lyric_id = lyric.id
|
|
|
|
# ────────────────────────────────────────────────
|
|
# 2단계: ChatGPT API 호출 (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 # chain이 자동으로 에러 처리
|
|
|
|
# ────────────────────────────────────────────────
|
|
# 3단계: 결과 저장
|
|
# ────────────────────────────────────────────────
|
|
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': language,
|
|
'status': 'completed',
|
|
}
|
|
|
|
result = self.run_async(_generate())
|
|
|
|
# 상태 업데이트
|
|
self.update_pipeline_status(
|
|
task_id=task_id,
|
|
stage='lyric',
|
|
status='completed',
|
|
message='가사 생성 완료'
|
|
)
|
|
|
|
# ────────────────────────────────────────────────────────────────
|
|
# 핵심: 여기서 다음 태스크를 직접 호출하지 않습니다!
|
|
# chain()이 이 반환값을 자동으로 generate_song에 전달합니다.
|
|
# ────────────────────────────────────────────────────────────────
|
|
logger.info(f"[Lyric] task_id={task_id} 완료. chain이 자동으로 다음 단계 실행.")
|
|
|
|
return result # ← 이 값이 generate_song(result)로 자동 전달됨
|
|
```
|
|
|
|
### 5.3 노래 생성 태스크
|
|
|
|
```python
|
|
# app/tasks/song_tasks.py
|
|
"""
|
|
노래 생성 태스크 (Chain 방식)
|
|
|
|
핵심 차이점:
|
|
- 첫 번째 인자 `prev_result`는 chain에서 자동으로 전달됩니다.
|
|
- generate_lyric의 반환값이 여기의 prev_result가 됩니다.
|
|
- 이 태스크도 generate_video의 존재를 모릅니다.
|
|
"""
|
|
|
|
from sqlalchemy import select, desc
|
|
import asyncio
|
|
import aiohttp
|
|
import os
|
|
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.song.models import Song, SongTimestamp
|
|
from app.utils.suno import SunoService
|
|
from app.utils.upload_blob_as_request import AzureBlobUploader
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
SUNO_POLL_INTERVAL = 10
|
|
SUNO_MAX_POLL_TIME = 300
|
|
|
|
|
|
@celery_app.task(
|
|
base=BaseTaskWithDB,
|
|
bind=True,
|
|
name='app.tasks.song_tasks.generate_song',
|
|
max_retries=3,
|
|
default_retry_delay=60,
|
|
acks_late=True,
|
|
soft_time_limit=540,
|
|
time_limit=600,
|
|
)
|
|
def generate_song(self, prev_result: dict, genre: str = "pop, ambient") -> dict:
|
|
"""
|
|
노래 생성 태스크
|
|
|
|
Args:
|
|
prev_result: chain에서 자동 전달된 이전 태스크의 반환값
|
|
{
|
|
"task_id": str,
|
|
"lyric_id": int,
|
|
"lyric_result": str,
|
|
"language": str,
|
|
}
|
|
genre: 음악 장르
|
|
|
|
Returns:
|
|
dict: 다음 태스크(generate_video)에 자동 전달될 결과
|
|
{
|
|
"task_id": str,
|
|
"lyric_id": int,
|
|
"song_id": int,
|
|
"song_result_url": str,
|
|
"duration": float,
|
|
}
|
|
|
|
chain 동작:
|
|
generate_lyric() → [결과] → generate_song([결과]) → [결과] → generate_video([결과])
|
|
^^^^^^^^^^^^^^^^
|
|
여기서 실행됨
|
|
"""
|
|
# ────────────────────────────────────────────────────────────────
|
|
# chain에서 전달받은 이전 결과에서 필요한 데이터 추출
|
|
# ────────────────────────────────────────────────────────────────
|
|
task_id = prev_result['task_id']
|
|
lyric_id = prev_result['lyric_id']
|
|
|
|
logger.info(f"[Song] chain에서 자동 전달 수신: task_id={task_id}")
|
|
|
|
self.update_pipeline_status(
|
|
task_id=task_id,
|
|
stage='song',
|
|
status='processing',
|
|
message='노래 생성을 시작합니다.'
|
|
)
|
|
|
|
async def _generate():
|
|
# ────────────────────────────────────────────────
|
|
# 1단계: DB에서 상세 데이터 조회
|
|
# ────────────────────────────────────────────────
|
|
# chain이 전달한 데이터는 경량이므로,
|
|
# 실제 작업에 필요한 상세 데이터는 DB에서 조회
|
|
async with self.get_db_session() as session:
|
|
lyric = await session.get(Lyric, lyric_id)
|
|
if not lyric or lyric.status != 'completed':
|
|
raise ValueError(f"Lyric not ready: id={lyric_id}")
|
|
|
|
project = await session.get(Project, lyric.project_id)
|
|
|
|
song = Song(
|
|
project_id=project.id,
|
|
lyric_id=lyric.id,
|
|
task_id=task_id,
|
|
status='processing',
|
|
song_prompt=f"{lyric.lyric_result}\n\nGenre: {genre}",
|
|
language=lyric.language,
|
|
)
|
|
session.add(song)
|
|
await session.commit()
|
|
song_id = song.id
|
|
lyrics_text = lyric.lyric_result
|
|
|
|
# ────────────────────────────────────────────────
|
|
# 2단계: Suno API 호출 + 폴링 (DB 세션 외부)
|
|
# ────────────────────────────────────────────────
|
|
suno = SunoService()
|
|
suno_response = await suno.generate_music(prompt=lyrics_text, style=genre)
|
|
suno_task_id = suno_response.get('task_id')
|
|
|
|
# suno_task_id 저장
|
|
async with self.get_db_session() as session:
|
|
song = await session.get(Song, song_id)
|
|
song.suno_task_id = suno_task_id
|
|
await session.commit()
|
|
|
|
# 폴링
|
|
elapsed = 0
|
|
audio_url = None
|
|
duration = None
|
|
suno_audio_id = None
|
|
|
|
while elapsed < SUNO_MAX_POLL_TIME:
|
|
await asyncio.sleep(SUNO_POLL_INTERVAL)
|
|
elapsed += SUNO_POLL_INTERVAL
|
|
|
|
self.update_pipeline_status(
|
|
task_id=task_id,
|
|
stage='song',
|
|
status='processing',
|
|
message=f'Suno 음악 생성 중... ({elapsed}초)'
|
|
)
|
|
|
|
status_resp = await suno.get_task_status(suno_task_id)
|
|
if status_resp.get('status') == 'SUCCESS':
|
|
clips = status_resp.get('clips', [])
|
|
if clips:
|
|
audio_url = clips[0].get('audio_url')
|
|
duration = clips[0].get('duration')
|
|
suno_audio_id = clips[0].get('id')
|
|
break
|
|
elif status_resp.get('status') == 'failed':
|
|
raise ValueError("Suno generation failed")
|
|
|
|
if not audio_url:
|
|
raise ValueError("Suno generation timed out")
|
|
|
|
# ────────────────────────────────────────────────
|
|
# 3단계: 업로드 + 타임스탬프 저장
|
|
# ────────────────────────────────────────────────
|
|
temp_dir = f"media/temp/{task_id}"
|
|
os.makedirs(temp_dir, exist_ok=True)
|
|
temp_file = f"{temp_dir}/song.mp3"
|
|
|
|
try:
|
|
async with aiohttp.ClientSession() as http:
|
|
async with http.get(audio_url) as resp:
|
|
with open(temp_file, 'wb') as f:
|
|
f.write(await resp.read())
|
|
|
|
uploader = AzureBlobUploader()
|
|
blob_url = await uploader.upload_file(
|
|
file_path=temp_file,
|
|
blob_name=f"songs/{task_id}/song.mp3",
|
|
content_type='audio/mpeg',
|
|
)
|
|
finally:
|
|
if os.path.exists(temp_file):
|
|
os.remove(temp_file)
|
|
|
|
# 타임스탬프 저장 (실패해도 계속)
|
|
try:
|
|
timestamps = await suno.get_lyric_timestamp(suno_audio_id)
|
|
async with self.get_db_session() as session:
|
|
for idx, ts in enumerate(timestamps):
|
|
session.add(SongTimestamp(
|
|
suno_audio_id=suno_audio_id,
|
|
order_idx=idx,
|
|
lyric_line=ts.get('text', ''),
|
|
start_time=ts.get('start_time', 0),
|
|
end_time=ts.get('end_time', 0),
|
|
))
|
|
await session.commit()
|
|
except Exception as e:
|
|
logger.warning(f"Timestamp save failed: {e}")
|
|
|
|
# 최종 업데이트
|
|
async with self.get_db_session() as session:
|
|
song = await session.get(Song, song_id)
|
|
song.status = 'completed'
|
|
song.song_result_url = blob_url
|
|
song.suno_audio_id = suno_audio_id
|
|
song.duration = duration
|
|
await session.commit()
|
|
|
|
return {
|
|
'task_id': task_id,
|
|
'lyric_id': lyric_id,
|
|
'song_id': song_id,
|
|
'song_result_url': blob_url,
|
|
'duration': duration,
|
|
'status': 'completed',
|
|
}
|
|
|
|
result = self.run_async(_generate())
|
|
|
|
self.update_pipeline_status(
|
|
task_id=task_id,
|
|
stage='song',
|
|
status='completed',
|
|
message='노래 생성 완료'
|
|
)
|
|
|
|
# ────────────────────────────────────────────────────────────────
|
|
# chain이 자동으로 이 결과를 generate_video에 전달합니다.
|
|
# 여기서 video_task를 직접 호출하지 않습니다!
|
|
# ────────────────────────────────────────────────────────────────
|
|
return result
|
|
```
|
|
|
|
### 5.4 비디오 생성 태스크
|
|
|
|
```python
|
|
# app/tasks/video_tasks.py
|
|
"""
|
|
비디오 생성 태스크 (Chain 방식 - 마지막 단계)
|
|
|
|
chain의 마지막 태스크이므로, 반환값은 chain의 최종 결과가 됩니다.
|
|
AsyncResult.get()으로 이 결과를 조회할 수 있습니다.
|
|
"""
|
|
|
|
from sqlalchemy import select, desc
|
|
import asyncio
|
|
import aiohttp
|
|
import os
|
|
import logging
|
|
|
|
from app.celery_app import celery_app
|
|
from app.tasks.base import BaseTaskWithDB
|
|
from app.home.models import Project, Image
|
|
from app.lyric.models import Lyric
|
|
from app.song.models import Song, SongTimestamp
|
|
from app.video.models import Video
|
|
from app.utils.creatomate import CreatomateService
|
|
from app.utils.upload_blob_as_request import AzureBlobUploader
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
CREATOMATE_POLL_INTERVAL = 15
|
|
CREATOMATE_MAX_POLL_TIME = 600
|
|
TEMPLATE_ID_VERTICAL = "e8c7b43f-de4b-4ba3-b8eb-5df688569193"
|
|
TEMPLATE_ID_HORIZONTAL = "0f092a6a-f526-4ef0-9181-d4ad4426b9e7"
|
|
|
|
|
|
@celery_app.task(
|
|
base=BaseTaskWithDB,
|
|
bind=True,
|
|
name='app.tasks.video_tasks.generate_video',
|
|
max_retries=2,
|
|
default_retry_delay=120,
|
|
acks_late=True,
|
|
soft_time_limit=840,
|
|
time_limit=900,
|
|
)
|
|
def generate_video(self, prev_result: dict, orientation: str = "vertical") -> dict:
|
|
"""
|
|
비디오 생성 태스크 (chain 마지막)
|
|
|
|
Args:
|
|
prev_result: chain에서 자동 전달 (generate_song의 반환값)
|
|
{
|
|
"task_id": str,
|
|
"song_id": int,
|
|
"song_result_url": str,
|
|
"duration": float,
|
|
}
|
|
orientation: 비디오 방향
|
|
|
|
Returns:
|
|
dict: chain의 최종 결과
|
|
{
|
|
"task_id": str,
|
|
"result_movie_url": str,
|
|
"status": "completed",
|
|
}
|
|
"""
|
|
task_id = prev_result['task_id']
|
|
song_id = prev_result['song_id']
|
|
|
|
logger.info(f"[Video] chain 마지막 단계: task_id={task_id}")
|
|
|
|
self.update_pipeline_status(
|
|
task_id=task_id,
|
|
stage='video',
|
|
status='processing',
|
|
message='비디오 생성을 시작합니다.'
|
|
)
|
|
|
|
async def _generate():
|
|
# DB 조회
|
|
async with self.get_db_session() as session:
|
|
song = await session.get(Song, song_id)
|
|
if not song or song.status != 'completed':
|
|
raise ValueError(f"Song not ready: id={song_id}")
|
|
|
|
lyric = await session.get(Lyric, song.lyric_id)
|
|
project = await session.get(Project, song.project_id)
|
|
|
|
images = await session.scalars(
|
|
select(Image)
|
|
.where(Image.project_id == project.id)
|
|
.where(Image.is_deleted == False)
|
|
.order_by(Image.img_order)
|
|
)
|
|
image_list = list(images)
|
|
|
|
timestamps = await session.scalars(
|
|
select(SongTimestamp)
|
|
.where(SongTimestamp.suno_audio_id == song.suno_audio_id)
|
|
.order_by(SongTimestamp.order_idx)
|
|
)
|
|
timestamp_list = list(timestamps)
|
|
|
|
video = Video(
|
|
project_id=project.id,
|
|
lyric_id=lyric.id,
|
|
song_id=song.id,
|
|
task_id=task_id,
|
|
status='processing',
|
|
)
|
|
session.add(video)
|
|
await session.commit()
|
|
video_id = video.id
|
|
|
|
song_url = song.song_result_url
|
|
song_duration = song.duration
|
|
image_urls = [img.image_url for img in image_list]
|
|
lyric_timestamps = [
|
|
{'text': ts.lyric_line, 'start': ts.start_time, 'end': ts.end_time}
|
|
for ts in timestamp_list
|
|
]
|
|
|
|
# Creatomate 처리
|
|
template_id = TEMPLATE_ID_VERTICAL if orientation == 'vertical' else TEMPLATE_ID_HORIZONTAL
|
|
creatomate = CreatomateService()
|
|
|
|
template = await creatomate.get_template(template_id)
|
|
modifications = {
|
|
'music_url': song_url,
|
|
'duration': song_duration,
|
|
**{f'image_{i+1}': url for i, url in enumerate(image_urls[:10])},
|
|
'captions': lyric_timestamps,
|
|
}
|
|
|
|
render_response = await creatomate.render(
|
|
template_id=template_id,
|
|
modifications=modifications,
|
|
)
|
|
render_id = render_response.get('id')
|
|
|
|
async with self.get_db_session() as session:
|
|
video = await session.get(Video, video_id)
|
|
video.creatomate_render_id = render_id
|
|
await session.commit()
|
|
|
|
# 폴링
|
|
elapsed = 0
|
|
video_url = None
|
|
while elapsed < CREATOMATE_MAX_POLL_TIME:
|
|
await asyncio.sleep(CREATOMATE_POLL_INTERVAL)
|
|
elapsed += CREATOMATE_POLL_INTERVAL
|
|
|
|
self.update_pipeline_status(
|
|
task_id=task_id, stage='video', status='rendering',
|
|
message=f'렌더링 중... ({elapsed}초)'
|
|
)
|
|
|
|
status_resp = await creatomate.get_render_status(render_id)
|
|
if status_resp.get('status') == 'succeeded':
|
|
video_url = status_resp.get('url')
|
|
break
|
|
elif status_resp.get('status') == 'failed':
|
|
raise ValueError(f"Rendering failed: {status_resp.get('error_message')}")
|
|
|
|
if not video_url:
|
|
raise ValueError("Rendering timed out")
|
|
|
|
# 업로드
|
|
temp_dir = f"media/temp/{task_id}"
|
|
os.makedirs(temp_dir, exist_ok=True)
|
|
temp_file = f"{temp_dir}/video.mp4"
|
|
|
|
try:
|
|
async with aiohttp.ClientSession() as http:
|
|
async with http.get(video_url) as resp:
|
|
with open(temp_file, 'wb') as f:
|
|
f.write(await resp.read())
|
|
|
|
uploader = AzureBlobUploader()
|
|
blob_url = await uploader.upload_file(
|
|
file_path=temp_file,
|
|
blob_name=f"videos/{task_id}/video.mp4",
|
|
content_type='video/mp4',
|
|
)
|
|
finally:
|
|
if os.path.exists(temp_file):
|
|
os.remove(temp_file)
|
|
|
|
async with self.get_db_session() as session:
|
|
video = await session.get(Video, video_id)
|
|
video.status = 'completed'
|
|
video.result_movie_url = blob_url
|
|
await session.commit()
|
|
|
|
return {
|
|
'task_id': task_id,
|
|
'video_id': video_id,
|
|
'result_movie_url': blob_url,
|
|
'status': 'completed',
|
|
}
|
|
|
|
result = self.run_async(_generate())
|
|
|
|
self.update_pipeline_status(
|
|
task_id=task_id,
|
|
stage='video',
|
|
status='completed',
|
|
message='파이프라인 완료',
|
|
extra_data={'result_movie_url': result['result_movie_url']}
|
|
)
|
|
|
|
# chain의 마지막 태스크 - 최종 결과 반환
|
|
return result
|
|
```
|
|
|
|
### 5.5 파이프라인 API (핵심 차이점)
|
|
|
|
```python
|
|
# app/api/routers/v1/pipeline.py
|
|
"""
|
|
Chain 기반 파이프라인 API
|
|
|
|
핵심 차이점:
|
|
- API에서 chain()을 선언하여 전체 파이프라인을 한 번에 정의합니다.
|
|
- 각 태스크는 다음 단계를 모릅니다.
|
|
- 파이프라인 제어(순서, 에러 핸들링)가 API 레벨에 집중됩니다.
|
|
"""
|
|
|
|
from celery import chain
|
|
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.celery_app import celery_app
|
|
|
|
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)
|
|
):
|
|
"""
|
|
파이프라인 시작
|
|
|
|
chain()으로 전체 파이프라인을 선언적으로 정의합니다.
|
|
"""
|
|
# ────────────────────────────────────────────────────────────────
|
|
# 핵심: 전체 파이프라인을 한 줄로 선언
|
|
# ────────────────────────────────────────────────────────────────
|
|
# .s() = signature: 태스크의 지연 호출 선언
|
|
# | = chain 연산자: 왼쪽 태스크의 결과를 오른쪽 태스크의 입력으로 연결
|
|
# .set(queue=...) = 실행될 큐 지정
|
|
|
|
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,
|
|
}
|
|
|
|
pipeline = chain(
|
|
# 1단계: 가사 생성 → lyric_queue에서 실행
|
|
generate_lyric.s(initial_data).set(queue='lyric_queue'),
|
|
|
|
# 2단계: 노래 생성 → song_queue에서 실행
|
|
# generate_lyric의 반환값이 자동으로 첫 번째 인자로 전달
|
|
generate_song.s(genre=request.genre).set(queue='song_queue'),
|
|
|
|
# 3단계: 비디오 생성 → video_queue에서 실행
|
|
# generate_song의 반환값이 자동으로 첫 번째 인자로 전달
|
|
generate_video.s(orientation=request.orientation).set(queue='video_queue'),
|
|
)
|
|
|
|
# chain 실행 - 전체 파이프라인 시작
|
|
async_result = pipeline.apply_async()
|
|
|
|
return {
|
|
'success': True,
|
|
'task_id': request.task_id,
|
|
'chain_id': async_result.id, # chain 전체 ID
|
|
'message': '파이프라인이 시작되었습니다.',
|
|
}
|
|
|
|
|
|
@router.get("/result/{chain_id}")
|
|
async def get_chain_result(
|
|
chain_id: str,
|
|
current_user=Depends(get_current_user)
|
|
):
|
|
"""
|
|
chain 결과 조회
|
|
|
|
chain의 마지막 태스크(video)의 결과를 조회합니다.
|
|
"""
|
|
result = celery_app.AsyncResult(chain_id)
|
|
|
|
return {
|
|
'chain_id': chain_id,
|
|
'state': result.state, # PENDING, STARTED, SUCCESS, FAILURE
|
|
'result': result.result if result.ready() else None,
|
|
'ready': result.ready(),
|
|
}
|
|
|
|
|
|
# ────────────────────────────────────────────────────────────────
|
|
# chain 에러 핸들링 (link_error)
|
|
# ────────────────────────────────────────────────────────────────
|
|
# chain에서 에러 발생 시 호출될 콜백 태스크
|
|
@celery_app.task(name='app.tasks.error_handler')
|
|
def pipeline_error_handler(request, exc, traceback):
|
|
"""
|
|
chain 실패 시 호출되는 에러 핸들러
|
|
|
|
어떤 단계에서 실패했든, 이 핸들러가 호출됩니다.
|
|
"""
|
|
task_id = request.kwargs.get('task_id') or 'unknown'
|
|
logger.error(f"Pipeline failed: task_id={task_id}, error={exc}")
|
|
# 알림 발송 등
|
|
|
|
|
|
# 에러 핸들러 포함 chain 사용 예시:
|
|
# pipeline = chain(
|
|
# generate_lyric.s(data),
|
|
# generate_song.s(),
|
|
# generate_video.s(),
|
|
# )
|
|
# pipeline.apply_async(link_error=pipeline_error_handler.s())
|
|
```
|
|
|
|
---
|
|
|
|
## 6. 상태 관리 및 모니터링
|
|
|
|
### 6.1 chain 상태 추적
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ chain 상태 추적 방법 │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
방법 1: chain_id로 결과 조회
|
|
───────────────────────────
|
|
async_result = celery_app.AsyncResult(chain_id)
|
|
print(async_result.state) # PENDING, STARTED, SUCCESS, FAILURE
|
|
print(async_result.result) # chain의 마지막 태스크 결과
|
|
|
|
※ 주의: chain_id로는 마지막 태스크 상태만 볼 수 있음
|
|
|
|
방법 2: 각 태스크의 ID를 저장하여 개별 추적
|
|
───────────────────────────────────────────
|
|
pipeline = chain(lyric.s(data), song.s(), video.s())
|
|
result = pipeline.apply_async()
|
|
|
|
# chain의 부모(parent) 추적
|
|
print(result.id) # video 태스크 ID
|
|
print(result.parent.id) # song 태스크 ID
|
|
print(result.parent.parent.id) # lyric 태스크 ID
|
|
|
|
방법 3: 커스텀 Redis 상태 (기존안과 동일)
|
|
──────────────────────────────────────────
|
|
각 태스크 내에서 pipeline:{task_id}:status 업데이트
|
|
→ 이 방법이 가장 실용적
|
|
```
|
|
|
|
### 6.2 모니터링 (기존안과 동일)
|
|
|
|
Flower, 커스텀 CLI 도구 등은 기존안과 동일합니다.
|
|
|
|
---
|
|
|
|
## 7. 실패 처리 전략
|
|
|
|
### 7.1 chain에서의 실패 처리
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ chain 실패 시 동작 │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
chain(lyric.s() | song.s() | video.s())
|
|
|
|
[시나리오 1] lyric 실패 (재시도 후 성공)
|
|
──────────────────────────────────────
|
|
lyric 실행 → 실패 → 재시도 (max_retries=3)
|
|
├─ 재시도 성공 → song 자동 실행 → video 자동 실행
|
|
└─ 3회 모두 실패 → chain 전체 FAILURE
|
|
└─ link_error 콜백 실행
|
|
|
|
[시나리오 2] song 실패 (lyric 이미 완료)
|
|
──────────────────────────────────────
|
|
lyric 완료 ✓ → song 실행 → 실패 → 재시도
|
|
├─ 재시도 성공 → video 자동 실행
|
|
└─ 모두 실패 → chain 전체 FAILURE
|
|
※ lyric 결과는 DB에 보존됨 (재사용 가능)
|
|
|
|
[시나리오 3] 부분 재시작 (chain의 약점)
|
|
──────────────────────────────────────
|
|
chain은 기본적으로 "전체 또는 없음"입니다.
|
|
song에서 실패하면, chain 자체가 실패합니다.
|
|
song부터 재시작하려면 새로운 chain을 만들어야 합니다:
|
|
|
|
# song부터 재시작
|
|
resume_chain = chain(
|
|
generate_song.s(prev_lyric_result),
|
|
generate_video.s(),
|
|
)
|
|
resume_chain.apply_async()
|
|
```
|
|
|
|
### 7.2 link_error 콜백
|
|
|
|
```python
|
|
# 전체 chain에 에러 핸들러 연결
|
|
pipeline = chain(
|
|
generate_lyric.s(data),
|
|
generate_song.s(),
|
|
generate_video.s(),
|
|
)
|
|
|
|
# link_error: chain의 어떤 단계에서든 실패하면 호출
|
|
pipeline.apply_async(
|
|
link_error=pipeline_error_handler.s()
|
|
)
|
|
|
|
@celery_app.task
|
|
def pipeline_error_handler(request, exc, traceback):
|
|
"""
|
|
실패 알림 및 DLQ 저장
|
|
"""
|
|
# Slack 알림
|
|
# DLQ에 실패 정보 저장
|
|
# DB 상태 업데이트 (failed)
|
|
pass
|
|
```
|
|
|
|
### 7.3 부분 재시작 API
|
|
|
|
```python
|
|
@router.post("/resume/{task_id}/{from_stage}")
|
|
async def resume_pipeline(
|
|
task_id: str,
|
|
from_stage: str, # "song" 또는 "video"
|
|
current_user=Depends(get_current_user)
|
|
):
|
|
"""
|
|
실패한 단계부터 chain 재시작
|
|
|
|
chain은 전체 재시작만 지원하므로,
|
|
실패한 단계부터 새로운 chain을 생성합니다.
|
|
"""
|
|
if from_stage == 'song':
|
|
# DB에서 lyric 결과 조회
|
|
lyric_result = await get_lyric_result_from_db(task_id)
|
|
|
|
resume = chain(
|
|
generate_song.s(lyric_result),
|
|
generate_video.s(),
|
|
)
|
|
result = resume.apply_async()
|
|
|
|
elif from_stage == 'video':
|
|
song_result = await get_song_result_from_db(task_id)
|
|
|
|
# 단일 태스크 (chain 불필요)
|
|
result = generate_video.apply_async(
|
|
args=(song_result,),
|
|
queue='video_queue',
|
|
)
|
|
|
|
return {'resumed_from': from_stage, 'chain_id': result.id}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. 설계 및 동작 설명
|
|
|
|
### 8.1 chain이 "독립성"을 보장하는 방법
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ chain의 독립성 보장 메커니즘 │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
[기존안]
|
|
lyric_tasks.py 내부에 이런 코드가 있음:
|
|
from app.tasks.song_tasks import generate_song ◄── 직접 의존
|
|
generate_song.apply_async(...) ◄── 직접 호출
|
|
|
|
→ lyric_tasks.py가 song_tasks.py를 "알고 있음"
|
|
→ 수정 시 양쪽 파일을 함께 변경해야 할 수 있음
|
|
|
|
[이 설계안]
|
|
lyric_tasks.py는 단순히 결과를 return합니다.
|
|
pipeline.py에서 chain을 선언합니다.
|
|
|
|
→ lyric_tasks.py는 song_tasks.py의 존재를 모름
|
|
→ 각 태스크가 완전히 독립적인 "순수 함수"
|
|
→ 파이프라인 순서 변경은 pipeline.py만 수정
|
|
|
|
비유:
|
|
기존안: 선수가 다음 주자를 직접 불러 릴레이 바통 전달
|
|
이 방식: 감독(Celery)이 주자 순서를 관리, 선수는 자기 주로만 달림
|
|
```
|
|
|
|
### 8.2 chain vs 명시적 전달 의사결정 매트릭스
|
|
|
|
```
|
|
┌──────────────────────┬─────────────────┬─────────────────┐
|
|
│ 기준 │ 기존안 (명시적)│ 이 방식 (chain) │
|
|
├──────────────────────┼─────────────────┼─────────────────┤
|
|
│ 태스크 간 결합도 │ 중간 │ 낮음 │
|
|
│ 파이프라인 가시성 │ 분산 │ 집중 │
|
|
│ 부분 재시작 용이성 │ 높음 │ 중간 │
|
|
│ 코드 복잡도 │ 중간 │ 낮음 │
|
|
│ 유연성 (동적 분기) │ 높음 │ 낮음 │
|
|
│ 디버깅 난이도 │ 중간 │ 중간 │
|
|
│ Celery 네이티브 지원 │ 일부 │ 완전 │
|
|
│ 추가 코드 필요량 │ 많음 │ 적음 │
|
|
└──────────────────────┴─────────────────┴─────────────────┘
|
|
```
|
|
|
|
### 8.3 언제 이 방식을 선택해야 하는가
|
|
|
|
```
|
|
이 방식이 적합한 경우:
|
|
✓ 파이프라인이 항상 고정된 순서 (lyric → song → video)
|
|
✓ 각 태스크가 순수 함수처럼 동작
|
|
✓ 파이프라인 전체를 한눈에 보고 싶을 때
|
|
✓ 코드량을 최소화하고 싶을 때
|
|
|
|
이 방식이 부적합한 경우:
|
|
✗ 동적 분기가 필요한 경우 (조건에 따라 다른 태스크 실행)
|
|
✗ 병렬 실행이 필요한 경우 (chord/group 조합 필요)
|
|
✗ 부분 재시작을 자주 하는 경우
|
|
✗ 태스크 결과가 매우 큰 경우 (메시지 크기 문제)
|
|
```
|
|
|
|
---
|
|
|
|
## 9. 기존안과의 비교
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
│ 기존안 vs 설계안 1 종합 비교 │
|
|
└─────────────────────────────────────────────────────────────────────────────┘
|
|
|
|
기존안 설계안 1
|
|
┌─────────────────┐ ┌─────────────────────┐
|
|
│ 명시적 큐 전달 │ │ Celery Chain │
|
|
└────────┬────────┘ └──────────┬──────────┘
|
|
│ │
|
|
파이프라인 각 태스크가 API에서 chain()으로
|
|
정의 위치 직접 다음 단계 호출 한 번에 선언
|
|
│ │
|
|
태스크 다음 태스크를 다음 태스크를
|
|
의존성 직접 import 전혀 모름
|
|
│ │
|
|
결과 전달 task_id만 전달 반환값 전체 전달
|
|
방식 DB에서 재조회 (경량 데이터 권장)
|
|
│ │
|
|
부분 해당 단계부터 새 chain 생성 필요
|
|
재시작 바로 재시작 가능 (약간 번거로움)
|
|
│ │
|
|
코드량 태스크당 ~10줄 추가 API에 chain 3줄
|
|
(apply_async 호출) (태스크는 return만)
|
|
│ │
|
|
적합한 동적 파이프라인 고정 순서
|
|
상황 조건부 분기 단순한 체인
|
|
```
|
|
|
|
---
|
|
|
|
## 10. 배포 및 운영
|
|
|
|
### 10.1 실행 명령어 (기존안과 동일)
|
|
|
|
```bash
|
|
# 워커 실행은 기존안과 동일
|
|
celery -A app.celery_app worker -Q lyric_queue -c 2 -n lyric@%h
|
|
celery -A app.celery_app worker -Q song_queue -c 2 -n song@%h
|
|
celery -A app.celery_app worker -Q video_queue -c 1 -n video@%h
|
|
```
|
|
|
|
### 10.2 Docker Compose (기존안과 동일)
|
|
|
|
워커 구성, 스케일링 전략은 기존안과 동일합니다.
|
|
차이점은 API 서버 코드에서 chain을 사용한다는 것뿐입니다.
|
|
|
|
---
|
|
|
|
## 문서 버전
|
|
|
|
| 버전 | 날짜 | 변경 내용 |
|
|
|------|------|-----------|
|
|
| 1.0 | 2024-XX-XX | 초안 작성 |
|