上传照片+克隆人声，实现实时对口型数字人对话。

方案简介

AvatarAI 是一个面向生产的开源 AI 数字人/Avatar 平台，目标是把"上传一张照片 + 克隆一段声音 → 与一张脸实时对话"做成完整可上线的 Web 服务，而非仅停留在 demo。

它面向希望快速交付拟真对话 Avatar 产品的开发者/团队，解决以下问题：

• 在浏览器里完成上传人脸、录制克隆音色、并发起 WebSocket 实时对话；
• 让大模型的回答流式生成，并以逐句对口型视频的形式回传给前端，做到首段视频远早于回答结束即可播放；
• 同时支持商业 LLM（Claude、GPT-4o）与本地开源 LLM（Ollama / vLLM / LM Studio），可纯本地运行，数据不出机；
• 提供生产化配套：JWT 鉴权、Postgres + Alembic 迁移、S3/CloudFront、Prometheus、pytest 测试、CI、AWS 一键部署 IaC。

README 原话定位其为 "the only project in this niche you can ship as a product, not just a demo"。

亮点与能力

AvatarAI 在 README 中声明并由依赖/架构图支撑的关键能力如下：

• 🎤 零样本声音克隆：10 秒音频即可克隆（Chatterbox Multilingual）；
• 🎭 任意人脸 + 23 种语言：上传 JPEG，选择语言即可对话；
• ⚡ Token 流式管线：LLM 流式输出 token，TTS + 对口型按句执行，首个视频块先于回答结束到达；
• ✋ Barge-in 打断：对话中再次说话或点击 stop，正在执行的回合会被毫秒级取消；
• 🔒 100% 本地模式：USE_LOCAL_STORAGE=true 时本地存储 + 本地 Whisper + Ollama；
• 🔌 多 LLM：Claude（带 prompt caching）、GPT-4o，或本地 Ollama / vLLM / LM Studio；
• 🚀 AWS GPU 部署：一行命令部署到 g5.xlarge，实现约 30 FPS 真实时；
• 🏗️ 生产级配套：JWT + httpOnly cookie、Postgres + Alembic、S3/CloudFront、Prometheus、CI 与 pytest 测试套件。

组成与分工

组合中每个成员的角色（基于架构图与依赖清单）：

• Whisper（faster-whisper, CUDA）：浏览器 WebM 音频解码，识别用户语音为文本；
• Claude / GPT-4o / Ollama / vLLM / LM Studio：多 LLM 后端，负责流式生成对话文本；
• Chatterbox TTS（Multilingual, 零样本克隆）：把每句文本合成克隆人声，支持 23 种语言；
• MuseTalk V1.5（持久化 worker）：以克隆语音 + 人脸照片驱动对口型视频，GPU 30 FPS；
• FastAPI + WebSocket Manager：核心后端，按句串起 TTS→MuseTalk→视频块回传；
• PostgreSQL + Alembic：持久化用户、avatar、会话与消息；
• Redis + Celery + Flower：任务队列与监控；
• Prometheus + Sentry + 结构化日志：可观测性；
• JWT（httpOnly cookie）+ 限流：鉴权与防滥用；
• S3 / CloudFront 或本地文件系统：人脸与音频资产存储。

前置要求

基础前置要求：

• Python（用于 FastAPI 后端、Whisper、MuseTalk worker）；
• Node.js（用于 Next.js 前端，按 README "Web app with auth & history | ✅ Next.js + JWT + Postgres"）；
• PostgreSQL 数据库 + Alembic 做迁移；
• Redis（Celery 队列）；
• 若启用 TTS 可选高级模块 Chatterbox：需独立 venv（"chatterbox (optional, separate venv)"）；
• 真实时对口型需 NVIDIA GPU（AWS 推荐 g5.xlarge，CUDA 11.8 + float16）；
• LLM 后端可选：Claude / OpenAI API Key，或本地 Ollama / vLLM / LM Studio。

README 明确给出环境变量 USE_LOCAL_STORAGE=true 即可走本地存储/本地 LLM 路径，零云依赖开发。

实施步骤

1. 克隆并启动后端

按仓库 backend/ 目录（FastAPI 应用）进行本地启动，安装 Python 依赖与模型权重（Whisper、Chatterbox Multilingual、MuseTalk V1.5），导出所需 API Key 与本地存储开关。

2. 启动依赖服务

• 启动 PostgreSQL、Redis；
• 若走 AWS 路径，配置 S3 / CloudFront；
• 若走本地路径，设置 USE_LOCAL_STORAGE=true。

3. 启动 FastAPI 与 MuseTalk worker

FastAPI 暴露 REST + WebSocket：上传人脸、克隆音色、走对话通道；MuseTalk 以独立持久化 worker 进程提供 GPU 对口型推理，CPU 回退走 FFmpeg。

4. 启动前端

Next.js 应用包含 Avatar Studio（人脸上传）、Voice Studio（音色克隆）、Chat Interface（实时对话）。

5. 发起一次实时对话

在浏览器中：

• 上传一张人脸 JPEG；
• 录制 10–60 秒音频触发零样本克隆；
• 打开 Chat Interface，麦克风说话或键入；
• 后端：Whisper STT → LLM 流式 → 句级 TTS + 对口型 → WebSocket 推回逐句视频块；
• 命中 barge-in：再次说话或点 stop，立即取消在飞回合。

6. 一键 AWS GPU 部署

按 README 描述，使用项目自带的 IaC 一行命令部署到 g5.xlarge（CUDA 11.8 + float16），目标 ~30 FPS 真实时。

注：README 在本段被截断，具体的 pip install、.env 模板与 aws deploy 命令需以仓库 backend/、infra/ 与 docs/ 目录原文为准，逐字复制执行。

使用与配置要点

关键配置开关

• USE_LOCAL_STORAGE=true：本地文件存储，跳过 AWS（开发模式）；
• LLM 选择：Claude（启用 prompt caching）、GPT-4o，或本地 Ollama / vLLM / LM Studio；
• TTS 回退链：chatterbox（独立 venv，可选）→ edge-tts（免费神经语音）→ gTTS，确保不会沉默。

实时管线使用要点

• 浏览器端 WebM 音频由 Whisper 原生解码；
• LLM 流式产出 token，句子切分后每句独立送 TTS + MuseTalk；
• 视频块按 WebSocket 推回前端，"首块 < 2–4 秒到达 AWS GPU" 是 README 公开指标；
• barge-in：再次说话或点 stop，毫秒级取消 in-flight turn。

验证成功

• 上传人脸 + 录音 → 进入 Chat Interface；
• 说话后 ~几秒内浏览器开始播放对口型视频；
• 打断生效，新回答从第一句开始重新流式渲染。

可观测与运维

• Prometheus 指标、Celery Flower、Sentry、结构化日志；
• pytest 覆盖 users / avatars / sessions / health checks。

优缺点

• ✓ 首块视频 2-4 秒即可播放
• ✓ 支持本地/云端多种部署
• ✕ GPU 部署依赖 g5.xlarge
• ✕ TTS 可选模块需独立 venv

出处

本方案挖掘自开源项目 PunithVT/ai-avatar-system，方案内容与实施命令均来自其 README 原文。