243 lines
5.8 KiB
Markdown
243 lines
5.8 KiB
Markdown
# 可视化语音聊天系统（初版）说明文档
|
||
|
||
本文档覆盖：
|
||
- 资源位置（代码、模型、环境）
|
||
- 本机启动与部署
|
||
- 局域网/远程访问
|
||
- 常用运维命令
|
||
- 验收与排障
|
||
|
||
---
|
||
|
||
## 1. 项目概览
|
||
|
||
当前项目实现的是单机部署的可视化聊天系统（WebRTC）：
|
||
- 用户语音上行（VAD + ASR）
|
||
- 文本调用在线 LLM
|
||
- 本地 TTS 合成语音
|
||
- 数字人视频下行（MuseTalk 优先，失败回退写实底片）
|
||
- 前端字幕与指标面板（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`：MuseTalk 推理调度 + 写实回退帧
|
||
- `webrtc/`
|
||
- `tracks.py`：实际音视频轨道实现
|
||
- `gateway.py`、`video_track.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. 前端功能说明
|
||
|
||
网页包含：
|
||
- 视频窗口（数字人）
|
||
- 文本输入框
|
||
- 字幕消息区（WebSocket）
|
||
- 指标面板（SSE）
|
||
|
||
当前已支持：
|
||
- 页面刷新自动重连
|
||
- 单连接策略（新连接踢掉旧连接）
|
||
- 句级字幕流式下发
|
||
- 打断耗时等指标展示
|
||
|
||
---
|
||
|
||
## 8. 当前已知边界
|
||
|
||
- MuseTalk 结果生成可能有一定延迟，期间使用写实底片回退。
|
||
- 部分“主观体验类”验收项（如口型同步主观评分）需要人工实测判定。
|
||
- Qwen3-TTS 对比方案尚未并入主链路（可后续做 A/B 开关）。
|
||
|
||
---
|
||
|
||
## 9. 快速排障
|
||
|
||
1) 页面无声/无画面
|
||
- 先看 `service.sh status`
|
||
- 看 `/health` 是否正常
|
||
- 浏览器是否授权麦克风、是否信任 HTTPS 证书
|
||
|
||
2) 连接冲突
|
||
- 系统是单连接模式，新连接会断开旧连接（预期）
|
||
|
||
3) 口型不动
|
||
- 查看 `/health` 中 `avatar.queued_frames` 和 `avatar.last_error`
|
||
- 若 MuseTalk 未产帧，会回退写实底片 + 口型叠加
|
||
|
||
4) 模型异常
|
||
- 跑 `scripts/model_probe.py` 快速定位 ASR/TTS/VAD
|
||
|
||
---
|
||
|
||
## 10. 版本建议
|
||
|
||
如果要做“生产化下一步”，建议优先：
|
||
- 增加 TURN（公网复杂 NAT）
|
||
- 增加多会话隔离（当前默认单会话）
|
||
- 增加 Prometheus/结构化日志
|
||
- 增加模型切换开关（Kokoro/Qwen3-TTS）
|
||
|