10 KiB

Raw Blame History

ADO2 Hookit — 백엔드 개발자 핸드오프

무엇인가: 사진 4장 + 5개 인터뷰 답변 → 8초 세로형(9:16) 후킹 숏폼을 자동 생성하는 파이프라인. "Intentional Unreal" 전략 — 실제 사진 기반에 AI 카메라 무브를 입혀 스크롤을 멈추게 하고, 디스클로저로 신뢰를 지킨다. ADO2 플랫폼의 어텐션 트랙 엔진 (engine/higgsfield_shorts).

이 문서는 PoC를 운영 가능한 서비스로 넘기기 위한 핸드오프입니다. 현 상태, 실행법, 데이터 계약, 그리고 운영화에 반드시 필요한 작업(❗)을 정리했습니다.

1. 아키텍처 — 3 엔진 오케스트레이션

인터뷰 답변(5개) + 사진(4장+)
        │
        ▼
 ① spec_builder.py   Claude(claude-opus-4-7) → VideoSpec(JSON) / ScriptResult(JSON)
        │            · 구조화 출력(json_schema) + 프롬프트 캐싱 + 가드레일
        ▼
 ② higgsfield_client.py   Higgsfield CLI shell-out → 완성형 8초 base.mp4 (오디오 포함)
        │                 · model=marketing_studio_video, mode=tv_spot, 9:16, 40cr
        ▼
 ③ remotion_render.py   VideoSpec + base.mp4 → props.json → `npx remotion render` → final.mp4
        │               · 자막/타이틀/셀링배지/엔드카드 오버레이 합성
        ▼
   /outputs/<job>.mp4  +  caption(업로드용 해시태그)

핵심 설계 원칙:

각 단계는 순수 함수(입력 → path/객체 반환). 비동기 잡 큐로 바꾸기 쉬움.
데이터 주도 Remotion: 컷/자막/타이밍을 props JSON으로 주입 → 콘텐츠가 바뀌어도 컴포넌트 불변.
dry_run 모드: 크레딧 0으로 데모 클립 반환 (Higgsfield 호출 스킵). 개발·테스트용.

2. 디렉터리 구조

engine/higgsfield_shorts/
├── server/                      # FastAPI 백엔드 (운영 대상 ★)
│   ├── app/
│   │   ├── main.py              # 라우트: /api/health, /api/captions, /api/generate
│   │   ├── schemas.py           # Pydantic 데이터 계약 (LLM·Remotion 공유)
│   │   └── pipeline/
│   │       ├── spec_builder.py      # ① Claude → VideoSpec / ScriptResult
│   │       ├── higgsfield_client.py # ② Higgsfield CLI 래퍼
│   │       └── remotion_render.py   # ③ Remotion 렌더 래퍼
│   ├── pyproject.toml           # Python deps (fastapi, anthropic, pydantic…)
│   └── .env.example             # ANTHROPIC_API_KEY
├── remotion/                    # Remotion 영상 합성 프로젝트 (Node)
│   ├── src/
│   │   ├── Root.tsx             # Composition 등록 (MumumShort)
│   │   ├── MumumShort.tsx       # 메인 컴포지션 (props 기반)
│   │   ├── data/types.ts        # ShortProps 타입 (= schemas.py VideoSpec와 1:1)
│   │   ├── data/mumum.ts        # defaultProps (Studio 미리보기용 샘플)
│   │   └── components/          # HookTitle/Subtitle/SellingBadge/BrandLines/EndCard
│   ├── public/                  # base 영상이 여기로 복사됨 (staticFile 해석)
│   └── package.json             # remotion 4.0.468, react 19
├── webapp/                      # 프론트엔드 (단일 HTML, Vercel 정적 배포)
│   ├── index.html               # React(CDN) 단일 파일 — 4스텝 UI
│   ├── vercel.json
│   └── demo/mumum.mp4           # dry_run·데모용 완성 영상
├── _brief/03_energy-matching.md # 에너지 자동 매칭 결정표 (3 프로파일)
├── prompts/camera-vocabulary.md # 카메라 어휘 + 키프레임 기법
├── concepts/                    # 5개 영상 컨셉 정의
└── docs/pipeline-integration.md # ADO2 본체 통합 노트

3. 사전 요구사항 (개발 환경)

항목	버전/조건	비고
Python	≥ 3.12	`uv` 권장
Node.js	≥ 22	Remotion 4.x 요구
ffmpeg / ffprobe	설치 필요	`remotion_render._probe_frames`가 ffprobe 사용
Higgsfield CLI	`@higgsfield/cli@^0.1.40`	`higgsfield auth login` 으로 디바이스 로그인 인증 선행
ANTHROPIC_API_KEY	필수	`server/.env` 에 설정 (Claude 호출)

⚠️ Higgsfield는 API 키가 아니라 CLI 디바이스 로그인으로 인증합니다(~/.higgsfield/). 서버는 subprocess로 CLI를 호출하므로, 서버 실행 계정이 로그인되어 있어야 실제 생성이 동작합니다. 컨테이너/서버리스 환경에서는 이 인증 상태 주입이 별도 과제입니다(§7 참고).

4. 로컬 실행

# 0) 인증 (1회)
higgsfield auth login

# 1) Remotion 의존성 (1회)
cd remotion && npm install && cd ..

# 2) 서버 의존성 + 환경변수
cd server
cp .env.example .env        # ANTHROPIC_API_KEY 채우기
uv sync                     # 또는: pip install -e .

# 3) 서버 기동
uv run uvicorn app.main:app --reload --port 8000
#   → http://localhost:8000/         (웹앱)
#   → http://localhost:8000/api/health

# (선택) Remotion 미리보기 스튜디오
cd ../remotion && npm run studio

프론트엔드만 따로 확인하려면 webapp/을 정적 서빙 (python3 -m http.server). index.html의 API_BASE를 백엔드 주소로 설정하면 실 호출, 비우면 데모 모드.

5. API 계약

`GET /api/health`

{ "ok": true }

`POST /api/captions` — 자막 스크립트 4블록 생성 (JSON)

요청 (GenerateRequest):

{
  "kind": "place",            // "place" | "product" | "message"
  "biz_name": "Stay, 머뭄",
  "addr": "전북 군산 …",       // optional
  "price": "1박 18만원",       // optional
  "selling": "프라이빗 독채, 넓은 정원, 깊은 욕조"
}

응답 (ScriptResult):

{ "intro": "...", "selling": "...", "story": "...", "cta": "..." }

`POST /api/generate` — 최종 영상 생성 (multipart/form-data)

필드: photos[](파일, 4장 이상), kind, biz_name, selling, addr?, price?, dry_run?(bool) 응답 (GenerateResult):

{
  "video_url": "/outputs/<job>.mp4",
  "caption": "업로드용 캡션 + 해시태그",
  "profile": "Still Cinema",
  "cost_credits": 40.0,
  "job_id": "ab12cd34"
}

데이터 계약 정의: server/app/schemas.py (VideoSpec / ScriptResult / GenerateRequest / GenerateResult). Remotion 측 동일 계약: remotion/src/data/types.ts — 두 파일은 1:1로 동기화 유지 필수.

6. 가드레일 (반드시 유지 — 비즈니스 규칙)

spec_builder.py의 시스템 프롬프트에 인코딩됨. 프롬프트 수정 시 절대 훼손 금지:

식민지 유산·역사정치 용어 금지 — "적산가옥/일제/식민지/근대사" 등 → 미학·경험 어휘로 대체. ("적산가옥"은 어원상 부정적 함의 → 숙박 카피에서 영구 차단)
거짓·과장 금지 — 사용자가 주지 않은 거리/효능/수치를 지어내지 않음.
자막은 흰색 모노크롬 — 카피에 색 지시어 금지. 강조는 굵기·크기·그림자로.
AI 디스클로저 고정 — 엔드카드에 "실제 사진 기반, AI 카메라 효과를 적용한 영상입니다."

7. 운영화(Production) 작업 — ❗ 백엔드 핵심 과제

현재는 동작하는 PoC입니다. 실 트래픽 전 다음을 처리해야 합니다:

❗ 동기 → 비동기 잡 전환 /api/generate가 Higgsfield 대기(최대 15분) + Remotion 렌더(수십 초)를 한 요청 안에서 블로킹함. → POST /api/generate는 job_id 즉시 반환, GET /api/jobs/{id} 폴링 or 웹소켓. → Celery/RQ/ARQ + Redis(이미 ADO2 스택에 있음) 권장.
❗ Higgsfield 인증의 서버 이식 CLI 디바이스 로그인(~/.higgsfield/)이 로컬 사용자에 묶여 있음. 컨테이너에서 동작하려면 인증 토큰/세션을 시크릿으로 주입하거나, Higgsfield REST API 직접 호출로 전환 검토 (현재는 CLI를 subprocess로 감싼 것 — .env.example의 HIGGSFIELD_API_KEY는 미사용 placeholder).
❗ 스토리지 — server/outputs/, remotion/public/(잡별 base 복사)는 로컬 디스크. → S3(S3_BUCKET_OUTPUTS, ap-northeast-2) 업로드 + presigned URL 반환. 잡 종료 후 로컬 정리.
멀티테넌트 / RLS — ADO2 본체 규칙(모든 쿼리 tenant_id 기반). 잡·결과물에 tenant context 주입.
비용 가드레일 — 생성 전 higgsfield_client.cost()로 크레딧 선확인, 월 예산(HF_MONTHLY_BUDGET_USD) 차단 로직.
에러 처리 — 현재 각 단계 실패를 502로 surface. 재시도/부분 실패(예: Higgsfield 성공·Remotion 실패 시 base 보존) 정책 필요.
동시성 — Remotion 렌더는 CPU/메모리 집약적. 렌더 워커 풀 분리 권장.
CORS — 현재 allow_origins=["*"]. 운영 도메인으로 제한.
에너지 자동 매칭 자동화 — 현 PoC는 프로파일을 LLM이 텍스트로 선택. _brief/03_energy-matching.md의 결정표를 코드(energy_matcher)로 옮겨 결정론적 프로파일링 → Remotion 트랜지션/리듬 기본값 주입(Phase 2).

8. 비용 모델 (참고)

1 크레딧 ≈ $0.051(세포함) ≈ ₩76 (환율 1500 기준)
영상 1편 = 40cr = 약 ₩3,060 (marketing_studio_video tv_spot)
풀로디드(LLM 호출 포함) ≈ ₩3,160 / 편

9. 배포 현황

프론트엔드(webapp): Vercel 정적 배포 — https://ado2short.o2osolution.ai (커스텀 도메인 DNS 연결 진행 중). Vercel은 정적 호스팅이므로 백엔드 미포함 → 데모 모드만 동작. 실 생성은 별도 백엔드 호스트 필요.
백엔드(server): 아직 배포처 없음. → §7 운영화 후 컨테이너 배포 대상.

10. 다음 액션 (백엔드 개발자 시작점)

로컬 실행(§4) → dry_run=true로 /api/generate 한 번 통과시켜 파이프라인 감 잡기.
§7-1(비동기 잡) + §7-2(Higgsfield 인증 이식)이 블로커. 이 둘부터 설계.
schemas.py ↔ remotion/src/data/types.ts 동기화 규칙 확인 (계약 변경 시 양쪽).
가드레일(§6)은 제품 신뢰의 핵심 — 프롬프트 리팩터 시 회귀 테스트 추가 권장.

문의: 크리에이티브/프롬프트 로직은 _brief/·prompts/·concepts/ 참조.

10 KiB Raw Blame History