251 lines
6.4 KiB
Markdown
251 lines
6.4 KiB
Markdown
# 可视化语音聊天系统（初版）说明文档
|
||
|
||
本文档覆盖：
|
||
- 资源位置（代码、模型、环境）
|
||
- 本机启动与部署
|
||
- 局域网/远程访问
|
||
- 常用运维命令
|
||
- 验收与排障
|
||
|
||
---
|
||
|
||
## 1. 项目概览
|
||
|
||
当前项目实现的是单机部署的可视化聊天系统（WebRTC）：
|
||
- 用户语音上行（VAD + ASR）
|
||
- 文本调用在线 LLM
|
||
- 本地 TTS 合成语音
|
||
- WebRTC 音频下行 + 3D 数字人控制流下行（WebSocket）
|
||
- 前端字幕与指标面板（SSE + WebSocket）
|
||
- 单工仲裁（支持 barge-in 打断）
|
||
|
||
代码根目录：
|
||
- `/home/xsl/product`
|
||
|
||
---
|
||
|
||
## 2. 代码结构（关键目录）
|
||
|
||
- `main.py`：后端入口（FastAPI + WebRTC + 全链路编排）
|
||
- `config.py`：配置加载（读取 `.env`）
|
||
- `core/`
|
||
- `state_machine.py`：会话状态机（单工仲裁）
|
||
- `pipeline.py`：VAD/ASR/LLM/TTS/字幕/时延逻辑
|
||
- `services/`
|
||
- `asr.py`：SenseVoice
|
||
- `llm.py`：在线模型 + fallback
|
||
- `tts.py`：Kokoro
|
||
- `vad.py`：Silero VAD
|
||
- `avatar.py`：音频转 3D 控制数据（blendshape / 头部姿态）
|
||
- `webrtc/`
|
||
- `tracks.py`：实际音频轨道实现
|
||
- `gateway.py`、`audio_track.py`：结构化封装
|
||
- `web/`
|
||
- `index.html`、`app.js`、`style.css`
|
||
- `scripts/`
|
||
- 启停：`service.sh`、`start-public.sh`
|
||
- 验收：`run_all_checks.sh`、`qa_check.py`、`smoke_test.py`、`model_probe.py`、`vad_check.py`、`tts_stress.py`、`llm_fallback_check.py`
|
||
- 监控：`gpu_monitor.sh`
|
||
|
||
---
|
||
|
||
## 3. 环境与模型资源位置
|
||
|
||
### 3.1 Conda 环境
|
||
|
||
当前实际运行环境：
|
||
- `/home/xsl/miniconda3/envs/MuseTalk`
|
||
|
||
系统启动脚本固定使用该 Python：
|
||
- `scripts/start-public.sh` 中 `PY=/home/xsl/miniconda3/envs/MuseTalk/bin/python`
|
||
|
||
### 3.2 主要模型路径
|
||
|
||
MuseTalk 模型目录：
|
||
- `/home/xsl/work/MuseTalk/models/`
|
||
|
||
关键文件：
|
||
- UNet：`/home/xsl/work/MuseTalk/models/musetalkV15/unet.pth`
|
||
- 配置：`/home/xsl/work/MuseTalk/models/musetalkV15/musetalk.json`
|
||
- Whisper：`/home/xsl/work/MuseTalk/models/whisper`
|
||
|
||
数字人源视频（写实底片 + MuseTalk 驱动源）：
|
||
- `/home/xsl/work/MuseTalk/data/video/yongen.mp4`
|
||
|
||
MuseTalk 推理脚本：
|
||
- `/home/xsl/work/MuseTalk/scripts/inference.py`
|
||
|
||
### 3.3 其他环境记录
|
||
|
||
完整环境与模型清单参考：
|
||
- `environments.md`
|
||
|
||
---
|
||
|
||
## 4. 配置文件
|
||
|
||
主配置文件：
|
||
- `/home/xsl/product/.env`
|
||
|
||
当前关键项（示例）：
|
||
- `LLM_API_KEY`
|
||
- `LLM_BASE_URL=https://api.deepseek.com`
|
||
- `WEBRTC_HOST=0.0.0.0`
|
||
- `WEBRTC_PORT=8080`
|
||
- `STUN_URL=stun:stun.l.google.com:19302`
|
||
- `SSL_CERTFILE=/home/xsl/product/certs/dev-cert.pem`
|
||
- `SSL_KEYFILE=/home/xsl/product/certs/dev-key.pem`
|
||
|
||
说明：
|
||
- `LLM_MODEL` 为空时会自动按 `base_url` 推断（DeepSeek 默认 `deepseek-chat`）。
|
||
|
||
---
|
||
|
||
## 5. 启动与部署
|
||
|
||
### 5.1 本机启动（推荐）
|
||
|
||
```bash
|
||
bash /home/xsl/product/scripts/service.sh start
|
||
bash /home/xsl/product/scripts/service.sh status
|
||
```
|
||
|
||
重启：
|
||
|
||
```bash
|
||
bash /home/xsl/product/scripts/service.sh restart
|
||
```
|
||
|
||
停止：
|
||
|
||
```bash
|
||
bash /home/xsl/product/scripts/service.sh stop
|
||
```
|
||
|
||
日志：
|
||
|
||
```bash
|
||
bash /home/xsl/product/scripts/service.sh logs
|
||
```
|
||
|
||
### 5.2 访问地址
|
||
|
||
- HTTPS（推荐）：`https://<服务器IP>:8080/`
|
||
- 本机：`https://127.0.0.1:8080/`
|
||
|
||
如果你使用自签证书，浏览器首次需要手动信任。
|
||
|
||
### 5.3 远程/跨机器访问
|
||
|
||
见：
|
||
- `REMOTE_ACCESS.md`
|
||
|
||
重点：
|
||
- 跨机器麦克风通常要求 HTTPS
|
||
- WSL2 场景可能需要 Windows 端口转发/防火墙放行
|
||
|
||
---
|
||
|
||
## 6. 一键验收与调试命令
|
||
|
||
### 6.1 一键全检查
|
||
|
||
```bash
|
||
bash /home/xsl/product/scripts/run_all_checks.sh
|
||
```
|
||
|
||
覆盖：
|
||
- 服务状态
|
||
- 文本链路压测
|
||
- LLM fallback
|
||
- VAD 检查
|
||
- TTS 20 句稳定性
|
||
- smoke 媒体输出（`wav + mp4`）
|
||
|
||
### 6.2 单项脚本
|
||
|
||
```bash
|
||
conda run -n MuseTalk python /home/xsl/product/scripts/model_probe.py
|
||
conda run -n MuseTalk python /home/xsl/product/scripts/qa_check.py --base-url "https://127.0.0.1:8080" --rounds 20
|
||
conda run -n MuseTalk python /home/xsl/product/scripts/llm_fallback_check.py
|
||
conda run -n MuseTalk python /home/xsl/product/scripts/vad_check.py
|
||
conda run -n MuseTalk python /home/xsl/product/scripts/tts_stress.py
|
||
conda run -n MuseTalk python /home/xsl/product/scripts/smoke_test.py --text "全链路验收"
|
||
```
|
||
|
||
### 6.3 长稳与GPU监控
|
||
|
||
1小时长稳：
|
||
|
||
```bash
|
||
conda run -n MuseTalk python /home/xsl/product/scripts/longrun_test.py --base-url "https://127.0.0.1:8080" --minutes 60 --interval-sec 30
|
||
```
|
||
|
||
GPU采样（CSV）：
|
||
|
||
```bash
|
||
bash /home/xsl/product/scripts/gpu_monitor.sh /home/xsl/product/outputs/gpu-1h.csv 3600 5
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 前端功能说明
|
||
|
||
网页包含：
|
||
- Three.js 3D 数字人舞台
|
||
- 文本输入框
|
||
- 字幕消息区（WebSocket）
|
||
- 指标面板（SSE）
|
||
|
||
当前前端能力：
|
||
- 浏览器通过 import map 直接加载 Three.js、GLTFLoader、three-vrm
|
||
- 可加载本地 `VRM`/`GLB` 文件
|
||
- 可加载 URL 形式的 `VRM`/`GLB`/`GLTF` 模型
|
||
- 页面默认会自动尝试加载官方 `three-vrm` 示例模型：`VRM1_Constraint_Twist_Sample.vrm`
|
||
- 未加载真实模型时会显示调试头像，仍可联调动画控制流
|
||
|
||
当前已支持：
|
||
- 页面刷新自动重连
|
||
- 单连接策略（新连接踢掉旧连接）
|
||
- 句级字幕流式下发
|
||
- 打断耗时等指标展示
|
||
|
||
---
|
||
|
||
## 8. 当前已知边界
|
||
|
||
- 当前后端输出的是可直接对接 3D 引擎的控制数据，不负责最终 3D 渲染。
|
||
- 当前控制数据基于音频能量和频谱特征做启发式推断，适合作为联调骨架，不等同于生产级口型模型。
|
||
- 若要达到更高口型精度，建议后续接入 phoneme/viseme 对齐模型或 Audio2Face 类推理服务。
|
||
|
||
---
|
||
|
||
## 9. 快速排障
|
||
|
||
1) 页面无声/无画面
|
||
- 先看 `service.sh status`
|
||
- 看 `/health` 是否正常
|
||
- 浏览器是否授权麦克风、是否信任 HTTPS 证书
|
||
|
||
2) 连接冲突
|
||
- 系统是单连接模式，新连接会断开旧连接（预期）
|
||
|
||
3) 口型不动
|
||
- 查看 `/health` 中 `avatar.last_frame_count` 和 `avatar.last_error`
|
||
- 查看前端 `/ws/animation` 是否已连接，控制流预览是否持续刷新
|
||
- 若模型已加载但不动，先检查该模型是否带有 VRM expression 或 morph target
|
||
|
||
4) 模型异常
|
||
- 跑 `scripts/model_probe.py` 快速定位 ASR/TTS/VAD
|
||
|
||
---
|
||
|
||
## 10. 版本建议
|
||
|
||
如果要做“生产化下一步”，建议优先：
|
||
- 增加 TURN（公网复杂 NAT）
|
||
- 增加多会话隔离（当前默认单会话）
|
||
- 增加 Prometheus/结构化日志
|
||
- 增加模型切换开关（Kokoro/Qwen3-TTS）
|
||
|