PunithVT/ai-avatar-system

🎭 AI Avatar / digital human platform — upload a photo, clone a voice, talk to any face in real time with lip-sync video. Open-source, self-hosted. Claude · Whisper · Chatterbox · MuseTalk.

🎭 AvatarAI – 실시간 AI 아바타 플랫폼

무엇인가요 – 어떤 포트레이트 사진과 짧은 음성 샘플을 사용해 실시간으로 입모양이 동기화된 대화 가능한 디지털 인간을 만들 수 있는 오픈소스이며 프로덕션 준비 완료된 스택입니다. 얼굴을 업로드하고 짧은 음성 샘플을 제공하면 실시간으로 입모양이 동기화된 대화를 할 수 있습니다. 시스템은 LLM이 생성한 텍스트를 스트리밍하고, TTS 엔진을 거쳐 음성을 처리한 후, 음성을 입모양 동기화 모델에 전달하고 WebSocket을 통해 브라우저로 비디오 조각을 전송하며, 몇 초 안에 완료됩니다.

핵심 기능 (README에 설명됨)

기능	작동 방식	주요 세부 사항
제로샷 음성 클론	Chatterbox Multilingual 사용; 10~60초의 음성으로 23개 언어의 합성 음성 생성 가능.	외부 API 필요 없음; 선택적 백업 체인 (Chatterbox → edge-tts → gTTS) 제공.
사진처럼 생긴 입모양 동기화	MuseTalk V1.5는 지속적인 GPU 워커로 작동하며, A10G GPU에서 약 30 FPS로 256×256 크기의 입 모양 프레임 생성.	CPU 기반 FFmpeg로 백업 가능; 더 선명한 출력을 위해 GFPGAN을 선택적으로 사용 가능.
스트리밍 LLM 파이프라인	Whisper (STT) → Claude / GPT-4o / 로컬 LLM (Ollama, vLLM, LM Studio) → 문장 단위 TTS → MuseTalk → WebSocket 비디오 조각.	LLM에서 토큰을 스트리밍하므로 AWS GPU 환경에서는 2~4초 내에 첫 번째 비디오 조각이 표시됨.
바지인 (인터럽션)	프론트엔드가 음성 활동을 감지; 중지 신호를 보내면 수 밀리초 내에 진행 중인 턴을 취소.
다중 LLM 지원	클라우드 API (Claude, GPT-4o) 또는 Ollama/vLLM/LM Studio를 통한 무료 로컬 모델.
인증 및 지속성	JWT + http-only 쿠키, PostgreSQL (Alembic 마이그레이션)로 사용자, 아바타, 대화 기록 관리. Redis로 레이트 제한 및 Celery 작업 큐.
관측성	Prometheus 메트릭, Celery Flower UI, 선택적 Sentry 통합, 구조화된 로깅.
배포 가능성	Docker-Compose로 로컬 개발 (CPU만) 및 GPU 지원 프로덕션. 원클릭 EC2 배포 스크립트. Terraform으로 관리되는 ECS + RDS + ElastiCache + CloudFront.
확장 가능한 아바타 엔진	`AVATAR_ENGINE` 환경 변수 – `simple` (입모양 없음), `musetalk` (기본값), 선택적 `liveavatar` (고해상도지만 48~80GB VRAM 필요).

아키텍처 개요

브라우저 (Next.js)                     FastAPI 백엔드 (Python)
 ├─ 아바타 스튜디오 (업로드)                ├─ WebSocket 매니저 (문장 스트리밍)
 ├─ 음성 스튜디오 (클론)                  ├─ Whisper STT (faster-whisper, CUDA)
 └─ 채팅 UI (WebSocket 비디오)             ├─ LLM 어댑터 (Claude, GPT-4o, Ollama, vLLM)
                                          ├─ TTS (XTTS v2, Chatterbox, edge-tts)
                                          └─ MuseTalk 워커 (GPU, 지속)

데이터 저장소: PostgreSQL (사용자, 아바타, 대화), Redis (레이트 제한, Celery 브로커), 로컬 파일 시스템 또는 S3 (업로드, 생성된 비디오), Prometheus/Sentry (메트릭).

빠른 시작 (Docker만, CPU 개발용)

git clone https://github.com/PunithVT/ai-avatar-system.git
cd ai-avatar-system
cp .env.example .env               # Anthropic 또는 OpenAI 키 추가
docker compose up -d               # 백엔드, 프론트엔드, redis, postgres 빌드

프론트엔드: http://localhost:3000
백엔드 API: http://localhost:8000 (Swagger는 /docs)
Celery Flower (선택 사항): http://localhost:5555

준비된 아바타를 시도하려면:

backend/venv/bin/python scripts/seed_demo.py --with-voices

GPU / AWS 배포

추천 인스턴스: g5.xlarge (A10G, 24GB VRAM) – 약 30 FPS 입모양 동기화.
원클릭 EC2 스크립트 (scripts/deploy-aws.sh)는 Docker 설치, 이미지 다운로드, MuseTalk 가중치 (~9GB) 다운로드, GPU 전달을 통해 스택 시작.
완전히 관리되는 설정을 원하면 infrastructure/의 Terraform 파일을 실행 (ECS 서비스, RDS, ElastiCache, S3 + CloudFront 생성) 후 bash deploy.sh production 실행.

로드맵 주요 사항 (README에서)

RAG 통합 – 벡터 스토어 검색을 추가해 LLM 응답을 보강.
고해상도 비디오 엔진 – MuseTalk보다 더 나은 오프라인 렌더링용.
개선된 얼굴 복원 파이프라인 – GFPGAN의 더 매끄러운 통합.
다중 아바타 오케스트레이션 – 서로 다른 아바타와 동시에 대화 지원.

누구에게 적합한가?

개발자 – 상용 AI 어시스턴트 또는 가상 호스트 서비스를 구축하고, 바로 사용 가능한 자체 호스팅 스택이 필요한 사람.
연구자 – 별도의 여러 리포지토리를 연결하지 않고도 실시간 다중 모달 파이프라인 (STT → LLM → TTS → 입모양 동기화)을 실험하고 싶은 사람.
콘텐츠 크리에이터 – 자신의 얼굴과 음성으로 맞춤화 가능한 로컬 실행 아바타를 찾는 사람.

결론 – AvatarAI는 음성 캡처부터 애니메이션 비디오 출력까지 전체 파이프라인을 커버하는 풀스택 오픈소스 플랫폼이며, 클라우드 API와 완전히 로컬 실행 경로를 모두 제공합니다. 실시간 AI 아바타 분야에서 가장 기능이 풍부한 프로젝트로, 프로덕션 배포 또는 추가 연구에 적합합니다.