# 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=请用温暖、自然、耐心的中文客服语气表达，语速适中，停顿真实，避免播音腔和夸张情绪。
```

如果服务返回错误或超时，页面会显示设备语音兜底状态，不会中断文字客服对话。