236 lines
4.8 KiB
Markdown
236 lines
4.8 KiB
Markdown
# CosyVoice 引擎集成 - 快速参考
|
||
|
||
## 文件清单
|
||
|
||
已创建/修改的文件：
|
||
|
||
### 新增文件
|
||
- `tts/cosyvoice_engine.py` - CosyVoice 引擎实现
|
||
- `tts/COSYVOICE.md` - 详细使用指南
|
||
- `tts/test_cosyvoice.py` - 集成测试文件
|
||
|
||
### 修改文件
|
||
- `tts/factory.py` - 注册 CosyVoice 引擎
|
||
- `tts/__init__.py` - 导出 CosyVoiceEngine 类
|
||
- `tts/examples.py` - 添加 CosyVoice 使用示例
|
||
- `requirements.txt` - 添加 httpx 依赖
|
||
|
||
## 核心实现
|
||
|
||
### 1. CosyVoice 引擎类 (`cosyvoice_engine.py`)
|
||
|
||
```python
|
||
from tts.cosyvoice_engine import CosyVoiceEngine
|
||
|
||
# 创建引擎实例
|
||
engine = CosyVoiceEngine(
|
||
api_url="http://192.168.1.200:8000/tts/zero_shot",
|
||
timeout=30.0
|
||
)
|
||
|
||
# 合成语音
|
||
audio = await engine.synthesize(
|
||
text="你好世界",
|
||
voice="speaker_id" # zero_shot_spk_id
|
||
)
|
||
```
|
||
|
||
### 2. 工厂模式注册
|
||
|
||
```python
|
||
from tts.factory import TTSEngineFactory, TTSEngineType
|
||
|
||
# 通过工厂创建 CosyVoice 引擎
|
||
engine = TTSEngineFactory.create("cosyvoice")
|
||
|
||
# 或者
|
||
engine = TTSEngineFactory.create(TTSEngineType.COSYVOICE)
|
||
```
|
||
|
||
## API 调用示例
|
||
|
||
### POST 请求格式
|
||
|
||
```
|
||
POST http://192.168.1.200:8000/tts/zero_shot
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"text": "合成的文本内容",
|
||
"zero_shot_spk_id": "发音人ID"
|
||
}
|
||
```
|
||
|
||
### Python 集成示例
|
||
|
||
```python
|
||
import asyncio
|
||
from tts.factory import TTSEngineFactory
|
||
|
||
async def main():
|
||
# 创建引擎
|
||
engine = TTSEngineFactory.create("cosyvoice")
|
||
|
||
# 合成语音
|
||
text = "你好，我是 CosyVoice 合成的语音。"
|
||
audio = await engine.synthesize(
|
||
text=text,
|
||
voice="female_speaker_001"
|
||
)
|
||
|
||
# 保存音频文件
|
||
with open("output.wav", "wb") as f:
|
||
f.write(audio.getvalue())
|
||
|
||
asyncio.run(main())
|
||
```
|
||
|
||
### FastAPI 路由示例
|
||
|
||
```python
|
||
from fastapi import APIRouter, HTTPException
|
||
from tts.factory import TTSEngineFactory
|
||
|
||
router = APIRouter(prefix="/api/tts", tags=["tts"])
|
||
|
||
@router.post("/cosyvoice")
|
||
async def synthesize(text: str, speaker_id: str):
|
||
"""使用 CosyVoice 合成语音"""
|
||
try:
|
||
engine = TTSEngineFactory.create("cosyvoice")
|
||
audio = await engine.synthesize(text=text, voice=speaker_id)
|
||
return {
|
||
"status": "success",
|
||
"size": len(audio.getvalue())
|
||
}
|
||
except ValueError as e:
|
||
raise HTTPException(status_code=400, detail=str(e))
|
||
except Exception as e:
|
||
raise HTTPException(status_code=500, detail="TTS failed")
|
||
```
|
||
|
||
## 支持的引擎列表
|
||
|
||
获取所有支持的 TTS 引擎：
|
||
|
||
```python
|
||
from tts.factory import TTSEngineFactory
|
||
|
||
engines = TTSEngineFactory.get_supported_engines()
|
||
# 返回: ['edge-tts', 'cosyvoice']
|
||
```
|
||
|
||
## 关键特性
|
||
|
||
✓ **异步支持** - 使用 asyncio 异步操作
|
||
✓ **HTTP 客户端** - 使用 httpx 库进行异步 HTTP 请求
|
||
✓ **错误处理** - 完善的异常处理和日志记录
|
||
✓ **连接管理** - 提供 close() 方法管理 HTTP 连接
|
||
✓ **工厂模式** - 统一的引擎创建和管理接口
|
||
✓ **参数验证** - 强制要求 voice 参数
|
||
|
||
## 依赖项
|
||
|
||
- `httpx>=0.24.0` - 异步 HTTP 客户端
|
||
- `loguru` - 日志记录（已存在）
|
||
|
||
## 配置建议
|
||
|
||
### 环境变量方式
|
||
|
||
在 `.env` 文件中添加：
|
||
|
||
```
|
||
COSYVOICE_API_URL=http://192.168.1.200:8000/tts/zero_shot
|
||
COSYVOICE_TIMEOUT=30
|
||
```
|
||
|
||
在代码中使用：
|
||
|
||
```python
|
||
import os
|
||
from tts.cosyvoice_engine import CosyVoiceEngine
|
||
|
||
api_url = os.getenv("COSYVOICE_API_URL", "http://192.168.1.200:8000/tts/zero_shot")
|
||
timeout = float(os.getenv("COSYVOICE_TIMEOUT", "30"))
|
||
|
||
engine = CosyVoiceEngine(api_url=api_url, timeout=timeout)
|
||
```
|
||
|
||
### 配置类方式
|
||
|
||
创建 `config/cosyvoice.py`：
|
||
|
||
```python
|
||
from pydantic_settings import BaseSettings
|
||
|
||
class CosyVoiceSettings(BaseSettings):
|
||
api_url: str = "http://192.168.1.200:8000/tts/zero_shot"
|
||
timeout: float = 30.0
|
||
|
||
class Config:
|
||
env_prefix = "COSYVOICE_"
|
||
|
||
settings = CosyVoiceSettings()
|
||
```
|
||
|
||
## 故障排查
|
||
|
||
### 问题：连接失败
|
||
|
||
```
|
||
ValueError: Failed to connect to CosyVoice API
|
||
```
|
||
|
||
**检查清单：**
|
||
1. CosyVoice 服务是否运行
|
||
2. 网络连接是否正常
|
||
3. API URL 是否正确
|
||
4. 防火墙是否阻止连接
|
||
|
||
### 问题：缺少 voice 参数
|
||
|
||
```
|
||
ValueError: voice (zero_shot_spk_id) is required for CosyVoice
|
||
```
|
||
|
||
**解决方案：** 确保在调用 `synthesize()` 时提供 `voice` 参数
|
||
|
||
### 问题：httpx 未安装
|
||
|
||
```
|
||
ModuleNotFoundError: No module named 'httpx'
|
||
```
|
||
|
||
**解决方案：** 安装依赖
|
||
```bash
|
||
pip install httpx
|
||
```
|
||
|
||
## 测试
|
||
|
||
运行集成测试：
|
||
|
||
```bash
|
||
python tts/test_cosyvoice.py
|
||
```
|
||
|
||
运行示例代码：
|
||
|
||
```bash
|
||
python tts/examples.py
|
||
```
|
||
|
||
## 更多信息
|
||
|
||
- [完整使用指南](./COSYVOICE.md)
|
||
- [TTS 架构](../docs/TTS_ARCHITECTURE.md)
|
||
- [示例代码](./examples.py)
|
||
|
||
---
|
||
|
||
**版本信息**
|
||
- CosyVoice 引擎版本: 1.0.0
|
||
- 最后更新: 2025年11月
|
||
- 兼容 Python 3.7+
|