xsl/product

Fork 0

Files

T

xsl 22a5f31847 init

2026-03-27 10:49:34 +08:00

5.8 KiB

Raw Blame History

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

本文档覆盖：

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

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 /home/xsl/product/scripts/service.sh start
bash /home/xsl/product/scripts/service.sh status

重启：

bash /home/xsl/product/scripts/service.sh restart

停止：

bash /home/xsl/product/scripts/service.sh stop

日志：

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 /home/xsl/product/scripts/run_all_checks.sh

覆盖：

服务状态
文本链路压测
LLM fallback
VAD 检查
TTS 20 句稳定性
smoke 媒体输出（wav + mp4）

6.2 单项脚本

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小时长稳：

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 /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. 快速排障

页面无声/无画面

先看 service.sh status
看 /health 是否正常
浏览器是否授权麦克风、是否信任 HTTPS 证书

连接冲突

系统是单连接模式，新连接会断开旧连接（预期）

口型不动

查看 /health 中 avatar.queued_frames 和 avatar.last_error
若 MuseTalk 未产帧，会回退写实底片 + 口型叠加

模型异常

跑 scripts/model_probe.py 快速定位 ASR/TTS/VAD

10. 版本建议

如果要做“生产化下一步”，建议优先：

增加 TURN（公网复杂 NAT）
增加多会话隔离（当前默认单会话）
增加 Prometheus/结构化日志
增加模型切换开关（Kokoro/Qwen3-TTS）

5.8 KiB Raw Blame History Unescape Escape