# 可视化语音聊天系统（初版）说明文档

本文档覆盖：
- 资源位置（代码、模型、环境）
- 本机启动与部署
- 局域网/远程访问
- 常用运维命令
- 验收与排障

---

## 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）