xsl/product
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f24de38e94abd3fbfc3ee66f7dc0fe3f10b710be
product/DEPLOYMENT_GUIDE.md
T
xsl f24de38e94 大功告成
2026-03-27 17:10:41 +08:00

6.4 KiB
Raw Blame History

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

本文档覆盖：

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

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 /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. 前端功能说明

网页包含：

  • 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 证书
  1. 连接冲突
  • 系统是单连接模式，新连接会断开旧连接（预期）
  1. 口型不动
  • 查看 /health 中 avatar.last_frame_count 和 avatar.last_error
  • 查看前端 /ws/animation 是否已连接，控制流预览是否持续刷新
  • 若模型已加载但不动，先检查该模型是否带有 VRM expression 或 morph target
  1. 模型异常
  • 跑 scripts/model_probe.py 快速定位 ASR/TTS/VAD

10. 版本建议

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

  • 增加 TURN（公网复杂 NAT）
  • 增加多会话隔离（当前默认单会话）
  • 增加 Prometheus/结构化日志
  • 增加模型切换开关（Kokoro/Qwen3-TTS）
Reference in New Issue View Git Blame Copy Permalink