AI Avatar (Qwen Realtime + 3D Avatar)

基于 React + Vite + Three.js 的实时 3D 虚拟人前端，配套 FastAPI 后端，通过 WebSocket 与 DashScope Qwen Realtime 进行语音双向交互。

• 手势识别（挥手触发会话）
• 语音实时对话（PCM 直传）
• 3D 角色动画与表情驱动
• 会话自动结束（用户离开 / 静默）

---

技术栈

• 前端：React、Vite、@react-three/fiber、Three.js、MediaPipe Tasks
• 后端：FastAPI、websockets、python-dotenv
• 语音模型：DashScope Qwen Realtime（WebSocket）

---

目录结构（关键）

avatar1/
├─ backend/
│  ├─ .env                  # 后端环境变量（DashScope 等）
│  └─ main.py               # FastAPI WS 中转服务
├─ public/
│  ├─ models/               # 3D 模型 + MediaPipe 任务模型
│  │  ├─ avatar.fbx
│  │  ├─ face_landmarker.task
│  │  └─ gesture_recognizer.task
│  └─ audios/
│     └─ mic-worklet.js     # 录音 AudioWorklet
├─ src/
│  ├─ App.jsx               # 主逻辑：会话、VAD、打断
│  ├─ Screen/AvatarView.jsx # 画布与全屏
│  ├─ components/
│  │  ├─ GestureDetector.jsx# 挥手 + 人脸/手 presence
│  │  └─ Avatar.jsx         # 3D Avatar 组件
│  └─ audio/voiceWsClient.js# 采集/播放/WS 传输
└─ README.md

---

快速开始

1) 前端

npm install
npm run dev

默认开发端口：http://localhost:5173/

2) 后端

进入 backend/ 并安装依赖：

pip install fastapi uvicorn websockets python-dotenv

启动服务（默认端口 8787）：

uvicorn main:app --host 0.0.0.0 --port 8787

---

环境变量（backend/.env）

仅后端需要环境变量。

DASHSCOPE_API_KEY=YOUR_DASHSCOPE_API_KEY
QWEN_RT_URL=wss://dashscope.aliyuncs.com/api-ws/v1/realtime
QWEN_MODEL=qwen3-omni-flash-realtime
QWEN_VOICE=Cherry
SYSTEM_PROMPT=你的系统提示词
QWEN_DEBUG=0

说明：

• DASHSCOPE_API_KEY：必填
• QWEN_RT_URL：可选，默认 DashScope 实时 WS 地址
• QWEN_MODEL / QWEN_VOICE：模型与音色
• SYSTEM_PROMPT：角色设定/口吻
• QWEN_DEBUG=1：打印调试日志

---

运行流程

1. 前端打开页面后，摄像头与麦克风权限允许
2. 挥手识别成功后自动建立语音会话
3. 前端将麦克风 PCM16（16k）通过 WS 发送到后端
4. 后端转发到 DashScope Qwen Realtime，接收音频流并回传
5. 用户离开（10s 未检测到人脸/手）或静默超时自动结束会话

---

常见修改点

• 后端 WS 地址：src/App.jsx 中的 WS_URL
• 3D 模型替换：public/models/avatar.fbx
• 手势模型：public/models/gesture_recognizer.task
• 人脸模型：public/models/face_landmarker.task
• 音频采集工作线程：public/audios/mic-worklet.js

---

注意事项

• 浏览器必须允许麦克风/摄像头访问
• 本地开发可用 http://localhost 正常调用 getUserMedia
• 部署到线上时建议使用 HTTPS

---

License

Private / Internal