myAiVideos – 자동화된 중국어 단편 영상 제작 파이프라인

하나의 명령어로 입력, 출판 가능한 영상으로 출력. 이 리포지토리는 주제 탐색, 스크립트 작성, 비주얼 및 오디오 생성, 편집, 최종적으로 배포 채널로 전달하는 완전한 엔드투엔드 워크플로우를 구현합니다. 모든 단계는 인증, 라우팅, 회로 차단, 관측성을 제공하는 FastAPI 서비스와 Java Spring-Boot 게이트웨이에 의해 오케스트레이션됩니다.

---

프로젝트의 기능

• 주제 탐색 (L1) – 핫 뉴스 또는 트렌드 아이템을 가져와 순위를 매깁니다.
• 창의적 생성 (L2) – 스크립트/프롬프트를 작성하여 화면 내 캐릭터의 시각적 정체성을 고정합니다.
• 비주얼 생성 (L3) – 텍스트에서 이미지 또는 이미지에서 동영상 모델 (DeepSeek, Kling, MuAPI 등)을 사용하고, CLIP 기반 일관성 검사를 수행합니다.
• 오디오 생성 (L4) – Volcengine 또는 MiniMax TTS로 음성 합성, 배경 음악과 믹스, 지속 시간 동기화를 수행합니다.
• 편집 (L5) – 자동 AV 동기화 복구, 자막 생성, 커버 이미지 생성.
• 배포 (L6) – 최종 MP4를 패키지화하여 호출자에게 반환하거나 봇에 푸시합니다.
• 최적화 (L7) – 결과를 평가하고 향후 실행을 위해 피드백을 저장합니다.

파이프라인은 계층적이고 분리된 구조이며, 각 단계는 다른 모델이나 서비스로 교체 가능하며, 다른 단계에 영향을 주지 않습니다.

---

핵심 아키텍처

• FastAPI (Python) – 오케스트레이션 엔진. 들어오는 웹훅 요청을 처리하고, PostgreSQL에 작업 상태를 저장하며, Redis에 작업을 큐잉하고, ARQ를 통해 백그라운드 워커를 실행합니다.
• Java Spring-Boot 게이트웨이 – Python API 앞에 위치. JWT 검증, trace_id 전파(다중 언어 관측성), Resilience4j 회로 차단, Caffeine 캐시, AOP 어셉트를 통한 토큰 사용량 기록을 수행합니다.
• 관측성 – Langfuse는 전체 호출 트리 캡처; Prometheus는 Java 게이트웨이에서 메트릭을 스크래핑합니다.
• 데이터 저장소 – PostgreSQL(지속적 메타데이터), Redis(큐), MinIO(생성된 미디어 자산).
• 컨테이너 – 모든 구성 요소가 Docker Compose로 패키지화됨 (오케스트레이터, 워커, 게이트웨이, DB, Redis, MinIO).

---

주요 기능 (README에 설명됨)

• 7단계 파이프라인 – 각 단계는 독립적으로 교체 가능.
• 다중 모델 장애 대체 – 프로바이더(DeepSeek, Qwen, GLM 등)가 사용 불가 시 자동 전환.
• AI 일관성 거버넌스:
  • 캐릭터의 시각적 일관성을 유지하기 위한 프롬프트 앵커링.
  • 오프-프롬프트 프레임을 조기에 제거하는 CLIP 기반 텍스트-이미지 게이팅.
  • 4단계 오디오-비디오 동기화 복구 (템포 조정, 비디오 패딩, 내레이션 재작성).
• 풀스택 관측성 – trace_id가 Java에서 Python으로 흐르며, Langfuse가 호출 트리를 표시합니다.
• 메터링 및 레이트 제한 – 코드 변경 없이 토큰 사용량을 캡처하고, 테넌트별로 집계됩니다.
• 프로덕션 대응 UX – Server-Sent Events로 진행 상황 스트리밍, 단일 세그먼트 재생성, 롤링 로그 아카이브.

---

기술 스택 스냅샷

레이어	기술
오케스트레이션 (Python)	FastAPI, asyncio, Pydantic, SQLAlchemy (asyncpg), Alembic, ARQ
게이트웨이 (Java)	Spring Boot 3.5, WebClient, Resilience4j, Caffeine, Prometheus
프론트엔드	Vue 3, Vite, Vue Flow, Pinia, Tailwind
데이터	PostgreSQL, Redis, MinIO
관측성	Langfuse, Prometheus
AI 모델	DeepSeek, Zhipu GLM-4V, Kling v2.5, Volcengine / MiniMax TTS, faster-whisper
컨테이너화	Docker Compose

---

시작하기 (빠른 시작)

# 리포지토리 클론 및 환경 템플릿 복사
git clone <your-fork>.git && cd myAiVideos
cp .env.example .env   # DeepSeek, GLM, Kling, TTS 등 API 키 입력

# 핵심 서비스 시작 (Postgres, Redis, FastAPI 오케스트레이터, ARQ 워커)
docker compose up -d postgres redis orchestrator worker

# DB 마이그레이션 적용
docker compose exec -T orchestrator alembic upgrade head

# (옵션) Java 게이트웨이 시작
docker compose up -d gateway

# Vue 프론트엔드 실행
cd sl-vue && npm install && npm run dev

헬스 엔드포인트:

• FastAPI: http://localhost:8000/health
• Java 게이트웨이: http://localhost:8080/actuator/health
• 프론트엔드: http://localhost:5173

---

누가 이 프로젝트를 사용할 수 있을까

• 콘텐츠 크리에이터 – 대규모로 중국어 단편 영상(뉴스 해설, 설명 동영상, 스토리텔링, 사실 요약)을 제작해야 하는 사람.
• 프로덕트 팀 – Douyin, Kuaishou 또는 기업 내부 피드용 AI 기반 영상 봇을 개발하는 사람.
• 연구자/개발자 – 다중 모달 생성 파이프라인, 장애 대체 전략, AI 거버넌스(프롬프트 앵커링, CLIP 게이팅)를 실험하는 사람.

---

문서 및 추가 읽기

• architecture.md – 상세한 데이터 흐름 다이어그램 및 컴포넌트 책임.
• docs/operations-manual.md – Feishu와의 통합 방법, 일일 유지보수, 시스템 모니터링 방법.
• gateway/README.md – Java 게이트웨이 설정, 인증, 메터링 세부 정보.
• 테스트 스위트(tests/)는 Docker Compose를 통해 실행 가능.

---

라이선스

MIT – LICENSE 참조.

---

결론: myAiVideos는 여러 LLM, 텍스트에서 이미지/비디오 모델, TTS 서비스를 통합한 프로덕션 수준의 오픈소스 프레임워크입니다. 자동으로 중국어 단편 영상을 생성하는 강력하고 관측 가능한 파이프라인을 제공합니다. 이는 단순한 튜토리얼이나 링크 모음이 아니라, 진정한 AI 중심 소프트웨어 프로젝트입니다.