Forget-C/Jellyfish 딥다이브
— AI가 만든 결과물을 "재사용 가능한 자산"으로 승격시키는 숏드라마 제작 파이프라인

1프로젝트 한 줄 요약

2왜 주목받는가 — 일관성이라는 진짜 병목

AI 영상의 진짜 어려움은 "생성"이 아니다

Runway, Pika, Kling, Sora 같은 도구는 이미 한 컷은 훌륭하게 만든다. 그런데 60편짜리 드라마를 만들려고 하면 문제가 완전히 달라진다.

벤더 락인을 피한 설계

Jellyfish는 특정 AI 회사에 묶여 있지 않다. 텍스트 LLM은 전부 OpenAI 호환 프로토콜로 통일했고(langchain_openai.ChatOpenAI 하나만 씀), 이미지·영상은 core/contracts/에 벤더 중립 계약을 정의한 뒤 OpenAI와 Volcengine(중국 바이트댄스 계열) 어댑터를 각각 구현했다.

더 중요한 건 Provider와 Model이 코드가 아니라 DB 테이블이라는 점이다. 관리자 화면에서 API 키와 base_url을 넣으면 새 공급자가 등록된다. 자체 호스팅 LLM을 꽂아도 되고, 로컬 vLLM을 붙여도 된다.

3기술 스택 전체 지도

백엔드 — Python 3.11+, uv로 관리

backend/pyproject.toml을 그대로 읽어 각 의존성이 코드 어디서 실제로 쓰이는지까지 정리했다. 의존성 목록만 보면 알 수 없는 부분이 많다.

프론트엔드 — Vite + React + Ant Design

인프라 — docker-compose 8개 컨테이너

CI/CD — GitHub Actions 6개 워크플로

AI 모델 연동 — 텍스트 / 이미지 / 영상 3계층

이미지·영상 어댑터는 둘 다 "생성 요청 → task_id 반환 → GET으로 폴링"이라는 동일한 패턴을 쓰고, core/contracts/image_generation.py의 ImageGenerationInput/ImageGenerationResult라는 공통 계약으로 추상화된다. 새 공급자를 추가할 때 계약만 지키면 나머지 시스템은 손댈 필요가 없다.

4아키텍처 심화 분석

4-1. 요청 하나가 흘러가는 전체 경로

가장 대표적인 흐름 — "대본을 샷으로 쪼개줘"를 따라가 보자.

4-2. 13개 LLM 에이전트 전수 조사

backend/app/chains/agents/ 안의 에이전트를 전부 정리했다. 각각 입력과 출력(Pydantic 모델)이 명확하게 정의돼 있다.

# chains/agents/shot_frame_prompt_agents.py
_FRAME_FOCUS = {
    "首帧": "...只表现触发瞬间或最初反应，
             不要直接写成后续完成动作、最终姿态或情绪爆发完成态。",
    #  첫 프레임: 촉발 순간이나 최초 반응만 표현. 
    #  완료된 동작·최종 자세·감정 폭발 완료태로 쓰지 말 것.

    "尾帧": "...强调动作收束、人物结束姿态、视线落点或情绪余韵。",
    #  끝 프레임: 동작의 수렴, 인물의 종료 자세, 시선의 착지점, 감정의 여운.

    "关键帧": "...不必平均描述整个过程。",
    #  키 프레임: 전 과정을 균등하게 서술할 필요 없음.
}

이건 프롬프트 엔지니어링이 아니라 영상 문법에 대한 도메인 지식이 코드에 녹아든 사례다. 이런 게 오픈소스를 읽을 때 진짜 얻는 것이다.

4-3. LLM은 완벽한 JSON을 주지 않는다 — 5단계 방어

chains/agents/base.py는 이 프로젝트에서 가장 배울 게 많은 파일이다. LLM에게 구조화된 출력을 요구했는데 이상한 게 왔을 때 포기하지 않는 5단계 폴백 체인을 구현했다.

# chains/agents/base.py — 마지막 방어선
call_kwargs = _parse_python_call_kwargs(python_like)
if call_kwargs is not None:
    return call_kwargs

4-4. "일관성 관리"의 실체 — 벡터DB가 아니다

그럼 어떻게 일관성이 유지되는가? 세 가지 장치의 조합이다.

① 엔티티 스키마에 별칭을 1급으로 넣는다

# schemas/skills/script_processing.py — EntityEntry
id                : str            # 전역 고유 ID
name              : str            # 정식 이름 (이후 모든 참조가 이걸 씀)
type              : str            # character / scene / prop / costume
aliases           : list[str]      # "그녀", "여주인공", "민서" 전부 여기로
normalized_name   : str
confidence        : float          # LLM의 확신도
first_appearance  : EvidenceSpan   # 대본 어디서 처음 나왔는지 (증거)
appearances       : list[...]
variants          : list[...]      # 의상·외형 변이

first_appearance가 증거(evidence)를 담는다는 점이 좋다. AI가 "이 인물이 있다"고 주장할 때 대본 몇 번째 줄이 근거인지를 함께 내놓게 만든 것이다. 사람이 검수할 때 이게 결정적이다.

② AI 후보와 확정 자산을 다른 테이블로 분리한다

③ 병합은 재시도를 전제로 설계됐다

EntityMergerAgent의 입력을 보면 특이한 필드가 있다.

all_extractions_json      # 모든 샷의 추출 결과
historical_library_json   # 기존에 확정된 자산 라이브러리
script_division_json      # 샷 분할 정보
previous_merge_json       # ← 직전 병합 결과
conflict_resolutions_json # ← 사람이 내린 충돌 판정

마지막 두 개가 핵심이다. 병합이 충돌을 냈을 때 사람이 "A와 B는 같은 인물이다"라고 판정을 내려주면, 그 판정을 프롬프트에 넣어 다시 돌린다. Celery의 자동 재시도가 아니라 사람이 개입한 뒤의 수동 재시도다 — 그리고 이 도메인에서는 그게 맞다.

4-5. DB 스키마 핵심 구조

4-6. 상태(status)를 셋으로 쪼갠 이유

4-7. Celery + asyncio의 함정을 정면 대응

# core/celery_app.py
@worker_process_init.connect
def _reset_async_db_runtime(**_: object) -> None:
    reset_db_runtime()

해결책은 worker_process_init 시그널로 자식 프로세스가 시작될 때마다 DB 런타임을 새로 만드는 것이다. 세 줄짜리 코드지만, 이걸 몰라서 며칠을 태우는 사람이 많다.

추가로 task_ignore_result=True 설정이 눈에 띈다. Celery의 result backend를 아예 안 쓴다는 뜻이다 — 상태의 진실원(single source of truth)은 오직 GenerationTask 테이블 하나다. 상태가 두 군데 저장돼 어긋나는 문제를 원천 제거한 선택이다.

5디렉토리 구조 해부

6학습 포인트 — 기술별 배울 것

① LLM 출력 방어 파싱 난이도 ★★☆

어디: chains/agents/base.py

구조화 출력 → 마크다운 펜스 제거 → 따옴표 정규화 → ast.literal_eval → 파이썬 함수호출 파싱. 5단계 폴백. LLM을 프로덕션에 쓰는 사람이라면 이 파일 하나만 읽어도 본전이다.

가져갈 것: "실패를 예외가 아니라 정상 경로의 일부로 설계한다"는 사고방식.

② Registry + Strategy로 확장점 만들기 난이도 ★★☆

어디: tasks/execute_task.py, services/worker/task_registry.py, core/tasks/registry.py

같은 패턴이 두 곳에서 재사용된다 — 태스크 실행기 레지스트리(task_kind → executor)와 벤더 어댑터 레지스트리(task_kind + provider_key → adapter). 새 기능을 추가할 때 기존 코드를 수정하지 않고 등록만 하면 되는 구조를 어떻게 만드는지 보여준다.

③ 벤더 중립 계약(contract) 설계 난이도 ★★☆

어디: core/contracts/image_generation.py vs core/integrations/{openai,volcengine}/images.py

두 벤더의 API는 엔드포인트도, 파라미터명도, 응답 형태도 다르다. 그런데 시스템의 나머지 부분은 ImageGenerationInput/Result만 안다. 인터페이스를 어느 수준에서 잘라야 하는지에 대한 좋은 실례다.

④ 상태 의미론의 분리 난이도 ★★★

어디: AGENTS.md + models/studio_shots.py + services/studio/shot_video_readiness.py

영속 상태 / 휘발성 상태 / 파생 상태를 나눈 것. 특히 파생 상태를 DB에 저장하지 않고 매번 계산하는 판단이 좋다. 캐시하면 빨라지지만 반드시 어긋난다.

가져갈 것: 상태 필드를 추가하기 전에 "이건 사실인가, 진행 중인 일인가, 다른 것으로부터 계산되는가"를 먼저 묻는 습관.

⑤ Human-in-the-loop 데이터 승격 난이도 ★★★

어디: ShotExtractedCandidate 모델 + services/studio/shot_extracted_candidates.py

AI 결과를 담는 후보 테이블과 확정 자산 테이블을 물리적으로 분리한 것. 이 하나가 "AI 툴"과 "AI를 쓰는 프로덕션 시스템"의 차이다.

⑥ 스키마 우선 개발과 코드 생성 난이도 ★★☆

어디: front/package.json의 openapi:update + AGENTS.md 규칙

FastAPI가 자동 생성한 OpenAPI 스펙 → TypeScript 클라이언트 자동 생성. 백엔드 타입을 바꾸면 프론트가 컴파일 에러로 알려준다. 규약을 문서에만 쓰지 않고 도구로 강제한 점이 핵심이다.

⑦ Celery × asyncio 실전 대응 난이도 ★★★

어디: core/celery_app.py의 worker_process_init 핸들러, task_ignore_result=True

fork 후 이벤트루프 재구축, result backend 미사용으로 상태 진실원 단일화. 둘 다 겪어본 사람만 아는 함정이다.

⑧ 규약 파일을 1급 산출물로 난이도 ★☆☆

어디: AGENTS.md

단순 코딩 컨벤션이 아니라 문서 카테고리 분류, 릴리스 노트 필수 섹션, 상태의 의미론까지 정의했다. AI 코딩 에이전트와 협업하는 저장소에서 규약 자체가 산출물이 되는 최근 흐름을 잘 보여준다.

실습 아이디어 (섹션 8에서 자세히)

• base.py의 파서만 떼어내 나만의 라이브러리로 만들고 테스트 작성
• 새 이미지 공급자 어댑터 추가 (계약만 지켜서)
• Candidate → Confirm 패턴을 다른 도메인(이력서 파싱 등)에 이식

7시스템 · 실행 요구사항

docker-compose로 뜨는 컨테이너

로컬 개발 실행

# 백엔드
cd backend
uv sync
uvicorn app.main:app --reload

# Celery 워커 (별도 터미널)
celery -A app.core.celery_app worker -l info

# 프론트 (별도 터미널)
cd front
pnpm install
pnpm dev

# API 바꿨으면 반드시 — AGENTS.md 규칙
pnpm run openapi:update

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

공식

• GitHub — Forget-C/Jellyfish (Apache-2.0 · 별 5,510 · 포크 952)
• AGENTS.md — 가장 먼저 읽을 파일
• 일본어 README (중국어 README는 없고, 코드 주석이 중국어)
• deploy/compose — docker-compose 구성

저장소 안에서 꼭 볼 파일

• backend/app/chains/agents/base.py — JSON 복구 파서 (최고의 학습 자료)
• backend/app/tasks/execute_task.py — Celery 유일 진입점
• backend/app/core/celery_app.py — fork 대응 + result backend 미사용
• backend/app/schemas/skills/script_processing.py — EntityEntry 정의
• backend/app/services/studio/shot_video_readiness.py — 파생 상태 재계산
• backend/app/core/contracts/image_generation.py — 벤더 중립 계약
• backend/app/chains/agents/shot_frame_prompt_agents.py — 영상 문법이 녹아든 프롬프트

배경 지식

• Celery Signals 문서 — worker_process_init의 정확한 시점
• SQLAlchemy 2.0 asyncio — 비동기 세션 수명 관리
• LangChain 구조화 출력 — ToolStrategy의 원리
• FastAPI — 클라이언트 자동 생성
• uv 공식 문서
• RustFS — MinIO 대안 스토리지