更新

deploy/cosyvoice.md

@@ -0,0 +1,86 @@
+# CosyVoice 客服语音部署
+
+当前聊天应用已经内置 CosyVoice FastAPI 适配器。语音对话使用 SSE 持续转发 PCM16，浏览器收到第一段音频后立即播放；兼容接口仍可把 PCM16 封装为 WAV。CosyVoice 异常时会熔断 20 秒，并自动回落到 OpenAI/浏览器语音。
+
+## 当前部署（2026-07-23）
+
+- 服务地址：`http://192.168.110.111:50000`（仅绑定局域网地址）
+- 容器：`cosyvoice3`，重启策略 `unless-stopped`
+- 镜像：`local/cosyvoice3:cu128-stream4-cancel`
+- 模型：`FunAudioLLM/Fun-CosyVoice3-0.5B-2512`
+- GPU：第 4 张 NVIDIA RTX 6000D（Docker 设备编号 `3`）
+- 服务目录：`/home/ps/services/cosyvoice3`
+- 输出格式：24 kHz、单声道、PCM16；语音对话由 PHP 以 SSE 原样转发并通过 Web Audio 边收边播
+- 打断：每次合成带唯一 `request_id`；浏览器插话后会停止已排期音频、终止文本请求，并调用 GPU 服务的 `/cancel/{request_id}` 停止后续生成
+- 回滚容器：`cosyvoice3-stream2-rollback-20260723`（上一版流式服务）和 `cosyvoice3-rollback-20260723`（最初稳定版），均保持停止状态
+
+本机端到端实测：SSE 响应头约 0.09 秒返回，短句第一段可播放音频约 2.1–2.6 秒到达。长文本收到第一段音频后执行取消，GPU 在约 0.8 秒内关闭生成流，未继续生成后续段落。数据库已启用会员端语音开关，并配置为 `zero_shot` 模式。当前使用官方仓库参考音频作为临时演示音色，正式上线前应在管理后台替换为已获得授权的真人客服 WAV 及其完全一致的逐字稿。
+
+## 1. GPU 主机部署官方服务
+
+建议使用 NVIDIA GPU 和 Linux/Docker。按照官方仓库构建：
+
+```bash
+git clone --recursive https://github.com/FunAudioLLM/CosyVoice.git
+cd CosyVoice/runtime/python
+docker build -t cosyvoice:v1.0 .
+```
+
+快速使用内置中文女声（SFT）：
+
+```bash
+docker run -d --gpus all --restart unless-stopped \
+  -p 50000:50000 cosyvoice:v1.0 \
+  /bin/bash -lc "cd /opt/CosyVoice/CosyVoice/runtime/python/fastapi && python3 server.py --port 50000 --model_dir iic/CosyVoice-300M-SFT"
+```
+
+生产环境请只允许聊天后端访问 50000 端口，或在反向代理中设置 Bearer Token；不要把官方无鉴权 FastAPI 直接暴露到公网。
+
+## 2. 在管理后台配置 AI 客服人物
+
+登录管理后台，进入「系统设置 → AI 客服人物」，填写 CosyVoice 服务地址，并选择人物模板、合成模式、说话人和采样率。点击「保存并试听音色」可以立即验证服务。
+
+后台保存的设置优先级高于环境变量；环境变量用于首次启动时提供默认值：
+
+在 `backend/.env` 中加入：
+
+```dotenv
+COSYVOICE_ENABLED=true
+COSYVOICE_BASE_URL=http://GPU服务器内网地址:50000
+COSYVOICE_MODE=sft
+COSYVOICE_SPEAKER=中文女
+COSYVOICE_SAMPLE_RATE=22050
+COSYVOICE_CONNECT_TIMEOUT_MS=800
+COSYVOICE_TIMEOUT_SECONDS=8
+```
+
+只使用管理后台修改时无需重启 PHP 服务。
+
+## 3. 最佳质量：CosyVoice 3 零样本客服音色
+
+使用一段已获得说话人明确授权、干净无背景音乐的客服录音，并准备完全一致的逐字稿。不要克隆未授权的真人声音。
+
+GPU 服务改用 `FunAudioLLM/Fun-CosyVoice3-0.5B-2512`。在管理后台将模式切换为 `Zero-shot 克隆音色`，上传 WAV 并填写与录音完全一致的逐字稿；音色文件会安全保存到 `backend/storage/cosyvoice/`。
+
+也可以在首次启动前通过环境变量提供默认值：
+
+```dotenv
+COSYVOICE_MODE=zero_shot
+COSYVOICE_PROMPT_WAV=D:/web/chat/backend/storage/cosyvoice/customer-service.wav
+COSYVOICE_PROMPT_TEXT=You are a helpful assistant.<|endofprompt|>这里填写参考音频的完整逐字稿。
+COSYVOICE_SAMPLE_RATE=24000
+```
+
+音色样本由聊天后端通过 multipart 请求发送给 CosyVoice，因此 GPU 服务和 PHP 后端可以位于不同主机。
+
+## 4. 情绪与语速控制
+
+使用 Instruct 模型时：
+
+```dotenv
+COSYVOICE_MODE=instruct
+COSYVOICE_SPEAKER=中文女
+COSYVOICE_INSTRUCT=请用温暖、自然、耐心的中文客服语气表达，语速适中，停顿真实，避免播音腔和夸张情绪。
+```
+
+如果服务返回错误或超时，页面会显示设备语音兜底状态，不会中断文字客服对话。