add edge tts
This commit is contained in:
459
docs/TTS_ARCHITECTURE.md
Normal file
459
docs/TTS_ARCHITECTURE.md
Normal file
@ -0,0 +1,459 @@
|
||||
# TTS 模块架构设计文档
|
||||
|
||||
## 📐 整体架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 应用层 (API) │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────┐ │
|
||||
│ │ FastAPI 路由 │ │ 定时任务 │ │ 服务层 │ │
|
||||
│ │ (tts_routes.py) │ │ (scheduler) │ │ (services)│ │
|
||||
│ └──────────────────┘ └──────────────────┘ └───────────┘ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 高级服务层 (Service) │
|
||||
│ ┌─────────────────────────────────────┐ │
|
||||
│ │ TTSService │ │
|
||||
│ │ - synthesize() │ │
|
||||
│ │ - get_supported_voices() │ │
|
||||
│ │ - get_engine_info() │ │
|
||||
│ │ - 自动使用配置文件设置 │ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 工厂层 (Factory) │
|
||||
│ ┌─────────────────────────────────────┐ │
|
||||
│ │ TTSEngineFactory │ │
|
||||
│ │ - create() (创建引擎) │ │
|
||||
│ │ - register_engine() (注册引擎) │ │
|
||||
│ │ - 单例模式缓存引擎实例 │ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 抽象层 (Abstract Base) │
|
||||
│ ┌─────────────────────────────────────┐ │
|
||||
│ │ TTSEngine │ │
|
||||
│ │ - synthesize() │ │
|
||||
│ │ - get_supported_voices() │ │
|
||||
│ │ - get_engine_name() │ │
|
||||
│ │ - get_engine_version() │ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 具体实现层 (Implementations) │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────┐ │
|
||||
│ │ EdgeTTSEngine │ │ GoogleTTSEngine │ │ ... │ │
|
||||
│ │ (现有) │ │ (待实现) │ │ (扩展) │ │
|
||||
│ └──────────────────┘ └──────────────────┘ └───────────┘ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ 第三方 TTS 服务 │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ ┌───────────┐ │
|
||||
│ │ Edge TTS │ │ Google TTS │ │ ... │ │
|
||||
│ │ (Microsoft) │ │ (Google Cloud) │ │ (其他) │ │
|
||||
│ └──────────────────┘ └──────────────────┘ └───────────┘ │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 🏗️ 类关系图
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ TTSEngine │
|
||||
│ (ABC) │
|
||||
└──────────────────┘
|
||||
▲
|
||||
│ inherits
|
||||
│
|
||||
┌───────────────────┼───────────────────┐
|
||||
│ │ │
|
||||
┌─────────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ EdgeTTSEngine │ │GoogleTTSEngine│ │... │
|
||||
│ (已实现) │ │(待实现) │ │(扩展) │
|
||||
└─────────────────┘ └──────────────┘ └──────────────┘
|
||||
|
||||
┌─────────────────────────────────┐
|
||||
│ TTSEngineFactory │
|
||||
│ manages instances of ▲ │
|
||||
│ │ │
|
||||
│ - create() │ │
|
||||
│ - register_engine() │ │
|
||||
│ - _instances cache │ │
|
||||
└─────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────┐
|
||||
│ TTSService │
|
||||
│ uses ▼ │
|
||||
│ │
|
||||
│ - TTSEngineFactory │
|
||||
│ - Settings (config) │
|
||||
│ - Logger │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 🔄 执行流程
|
||||
|
||||
### 1. 初始化流程
|
||||
|
||||
```
|
||||
应用启动
|
||||
│
|
||||
├─→ 加载配置 (settings.py)
|
||||
│ │
|
||||
│ └─→ TTS_ENGINE="edge-tts"
|
||||
│ TTS_LANGUAGE="zh-CN"
|
||||
│ ...
|
||||
│
|
||||
└─→ 应用就绪
|
||||
│
|
||||
└─→ 第一次 TTS 请求到达时初始化引擎
|
||||
```
|
||||
|
||||
### 2. 合成语音流程
|
||||
|
||||
```
|
||||
用户请求 (HTTP POST)
|
||||
│
|
||||
├─→ TTSService.synthesize()
|
||||
│ │
|
||||
│ ├─→ 检查引擎是否已初始化
|
||||
│ │ │
|
||||
│ │ └─→ 否: TTSEngineFactory.create()
|
||||
│ │ │
|
||||
│ │ └─→ 创建 EdgeTTSEngine 实例
|
||||
│ │ └─→ 缓存实例
|
||||
│ │
|
||||
│ ├─→ 从配置获取参数
|
||||
│ │ (language, voice, rate, pitch)
|
||||
│ │
|
||||
│ ├─→ engine.synthesize()
|
||||
│ │ │
|
||||
│ │ └─→ Edge TTS API 调用
|
||||
│ │ │
|
||||
│ │ └─→ 返回 BytesIO 对象
|
||||
│ │
|
||||
│ └─→ 返回音频数据
|
||||
│
|
||||
└─→ API 响应成功
|
||||
```
|
||||
|
||||
### 3. 获取声音列表流程
|
||||
|
||||
```
|
||||
用户请求 (HTTP GET)
|
||||
│
|
||||
├─→ TTSService.get_supported_voices()
|
||||
│ │
|
||||
│ ├─→ 获取或创建引擎实例
|
||||
│ │
|
||||
│ ├─→ engine.get_supported_voices()
|
||||
│ │ │
|
||||
│ │ └─→ Edge TTS API 调用
|
||||
│ │ │
|
||||
│ │ └─→ 获取完整声音列表
|
||||
│ │ │
|
||||
│ │ └─→ 按语言筛选
|
||||
│ │
|
||||
│ └─→ 返回声音列表
|
||||
│
|
||||
└─→ API 响应成功
|
||||
```
|
||||
|
||||
## 🎯 设计模式
|
||||
|
||||
### 1. 工厂模式 (Factory Pattern)
|
||||
|
||||
**目的**：统一创建和管理引擎实例
|
||||
|
||||
**实现**：`TTSEngineFactory`
|
||||
|
||||
```python
|
||||
# 使用工厂创建引擎
|
||||
engine = TTSEngineFactory.create("edge-tts")
|
||||
|
||||
# 自动缓存，再次创建返回同一实例
|
||||
engine2 = TTSEngineFactory.create("edge-tts")
|
||||
assert engine is engine2 # True (单例)
|
||||
```
|
||||
|
||||
**优点**：
|
||||
- 统一的创建入口
|
||||
- 易于添加新引擎
|
||||
- 自动实例缓存和生命周期管理
|
||||
|
||||
### 2. 抽象基类模式 (ABC Pattern)
|
||||
|
||||
**目的**：定义引擎的统一接口
|
||||
|
||||
**实现**：`TTSEngine` 基类
|
||||
|
||||
```python
|
||||
from abc import ABC, abstractmethod
|
||||
|
||||
class TTSEngine(ABC):
|
||||
@abstractmethod
|
||||
async def synthesize(self, ...):
|
||||
pass
|
||||
```
|
||||
|
||||
**优点**：
|
||||
- 强制所有引擎实现相同接口
|
||||
- IDE 自动补全和类型检查
|
||||
- 清晰的契约定义
|
||||
|
||||
### 3. 服务外观模式 (Facade Pattern)
|
||||
|
||||
**目的**：为客户端提供简化的高级接口
|
||||
|
||||
**实现**：`TTSService`
|
||||
|
||||
```python
|
||||
# 简化的调用
|
||||
audio = await TTSService.synthesize("文本")
|
||||
|
||||
# vs 复杂的调用
|
||||
engine = TTSEngineFactory.create(settings.TTS_ENGINE)
|
||||
audio = await engine.synthesize(
|
||||
text="文本",
|
||||
language=settings.TTS_LANGUAGE,
|
||||
voice=settings.TTS_VOICE or None,
|
||||
rate=settings.TTS_RATE,
|
||||
pitch=settings.TTS_PITCH,
|
||||
)
|
||||
```
|
||||
|
||||
**优点**：
|
||||
- 隐藏复杂性
|
||||
- 统一配置管理
|
||||
- 易于使用
|
||||
|
||||
### 4. 单例模式 (Singleton Pattern)
|
||||
|
||||
**目的**：确保同一引擎类型只有一个实例
|
||||
|
||||
**实现**：`TTSEngineFactory._instances`
|
||||
|
||||
```python
|
||||
_instances: dict[TTSEngineType, TTSEngine] = {}
|
||||
|
||||
# 第一次创建
|
||||
engine1 = TTSEngineFactory.create("edge-tts") # 创建新实例
|
||||
|
||||
# 第二次创建
|
||||
engine2 = TTSEngineFactory.create("edge-tts") # 返回缓存实例
|
||||
|
||||
assert engine1 is engine2 # True
|
||||
```
|
||||
|
||||
**优点**：
|
||||
- 节省资源
|
||||
- 避免重复初始化
|
||||
- 状态管理简化
|
||||
|
||||
## 📦 模块职责
|
||||
|
||||
| 模块 | 职责 | 关键类/函数 |
|
||||
|------|------|-----------|
|
||||
| `base.py` | 定义引擎接口 | `TTSEngine` |
|
||||
| `edge_tts_engine.py` | 实现 Edge-TTS | `EdgeTTSEngine` |
|
||||
| `factory.py` | 管理引擎创建 | `TTSEngineFactory`, `TTSEngineType` |
|
||||
| `service.py` | 提供高级接口 | `TTSService` |
|
||||
| `tts_routes.py` | REST API 端点 | 4 个 API 端点 |
|
||||
|
||||
## 🔌 扩展点
|
||||
|
||||
### 新增引擎支持
|
||||
|
||||
1. **创建新引擎类** (步骤 1)
|
||||
```python
|
||||
# tts/google_tts_engine.py
|
||||
class GoogleTTSEngine(TTSEngine):
|
||||
async def synthesize(self, ...):
|
||||
# 实现 Google TTS 调用
|
||||
pass
|
||||
```
|
||||
|
||||
2. **注册到工厂** (步骤 2)
|
||||
```python
|
||||
# factory.py
|
||||
class TTSEngineType(Enum):
|
||||
EDGE_TTS = "edge-tts"
|
||||
GOOGLE_TTS = "google-tts" # 新增
|
||||
|
||||
class TTSEngineFactory:
|
||||
_engines = {
|
||||
TTSEngineType.EDGE_TTS: EdgeTTSEngine,
|
||||
TTSEngineType.GOOGLE_TTS: GoogleTTSEngine, # 新增
|
||||
}
|
||||
```
|
||||
|
||||
3. **更新配置** (步骤 3)
|
||||
```python
|
||||
# settings.py
|
||||
TTS_ENGINE: str = Field("edge-tts") # 支持 google-tts
|
||||
GOOGLE_TTS_API_KEY: str # 新增 Google TTS 配置
|
||||
```
|
||||
|
||||
4. **在 .env 中配置** (步骤 4)
|
||||
```env
|
||||
TTS_ENGINE=google-tts
|
||||
GOOGLE_TTS_API_KEY=your_api_key
|
||||
```
|
||||
|
||||
完成！系统会自动使用新引擎。
|
||||
|
||||
## 🧵 异步设计
|
||||
|
||||
所有 TTS 操作都是异步的：
|
||||
|
||||
```python
|
||||
# 高效的并发处理
|
||||
async def synthesize_multiple(texts: list[str]):
|
||||
"""并发合成多个文本"""
|
||||
tasks = [TTSService.synthesize(text) for text in texts]
|
||||
audios = await asyncio.gather(*tasks)
|
||||
return audios
|
||||
```
|
||||
|
||||
**好处**：
|
||||
- 支持高并发请求
|
||||
- 不阻塞其他操作
|
||||
- 与 FastAPI/APScheduler 无缝集成
|
||||
|
||||
## 💾 状态管理
|
||||
|
||||
### 应用级状态
|
||||
|
||||
```python
|
||||
class TTSService:
|
||||
_engine: Optional[TTSEngine] = None # 共享引擎实例
|
||||
_instances: dict = {} # 引擎实例缓存
|
||||
```
|
||||
|
||||
**特点**：
|
||||
- 懒加载：第一次使用时初始化
|
||||
- 线程安全：使用装饰器 `@classmethod`
|
||||
- 可重置：`TTSService.reset_engine()`
|
||||
|
||||
## ⚙️ 配置管理
|
||||
|
||||
```
|
||||
┌─────────────────────────────────┐
|
||||
│ .env 文件 │
|
||||
│ TTS_ENGINE=edge-tts │
|
||||
│ TTS_LANGUAGE=zh-CN │
|
||||
│ TTS_RATE=1.0 │
|
||||
└──────────────┬──────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ Settings 对象 │
|
||||
│ (config/settings.py) │
|
||||
│ - 验证配置值 │
|
||||
│ - 提供类型提示 │
|
||||
│ - 支持环境变量覆盖 │
|
||||
└──────────────┬──────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────┐
|
||||
│ TTSService │
|
||||
│ - 自动使用配置 │
|
||||
│ - 可被参数覆盖 │
|
||||
└─────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 🚦 错误处理
|
||||
|
||||
### 错误处理流程
|
||||
|
||||
```
|
||||
try:
|
||||
audio = await engine.synthesize(text)
|
||||
except Exception as e:
|
||||
logger.error(f"TTS Error: {e}")
|
||||
│
|
||||
├─→ 网络错误
|
||||
│ └─→ 重试或返回错误信息
|
||||
│
|
||||
├─→ 不支持的语言
|
||||
│ └─→ 返回支持的语言列表
|
||||
│
|
||||
├─→ API 限制
|
||||
│ └─→ 实现本地缓存或队列
|
||||
│
|
||||
└─→ 其他错误
|
||||
└─→ 记录详细日志并返回 500
|
||||
```
|
||||
|
||||
### 日志级别
|
||||
|
||||
- **DEBUG**: 详细的执行过程
|
||||
- **INFO**: 成功的操作
|
||||
- **ERROR**: 错误和异常
|
||||
|
||||
## 📊 性能考虑
|
||||
|
||||
### 优化策略
|
||||
|
||||
1. **实例缓存**
|
||||
```python
|
||||
# 引擎实例只创建一次
|
||||
engine = TTSEngineFactory.create("edge-tts")
|
||||
engine = TTSEngineFactory.create("edge-tts") # 返回缓存
|
||||
```
|
||||
|
||||
2. **异步操作**
|
||||
```python
|
||||
# 不阻塞其他请求
|
||||
audio = await engine.synthesize(text)
|
||||
```
|
||||
|
||||
3. **结果缓存（可选）**
|
||||
```python
|
||||
# 缓存常见文本的合成结果
|
||||
@functools.lru_cache
|
||||
async def synthesize(text: str):
|
||||
...
|
||||
```
|
||||
|
||||
4. **批量处理（可选）**
|
||||
```python
|
||||
# 合成多个文本时并发处理
|
||||
audios = await asyncio.gather(*tasks)
|
||||
```
|
||||
|
||||
## 🔐 安全考虑
|
||||
|
||||
1. **输入验证**
|
||||
- 验证文本长度
|
||||
- 检查不支持的字符
|
||||
|
||||
2. **速率限制**
|
||||
- 限制每秒请求数
|
||||
- 实现请求队列
|
||||
|
||||
3. **日志安全**
|
||||
- 不记录敏感信息
|
||||
- 限制日志输出大小
|
||||
|
||||
4. **API 密钥管理**
|
||||
- 存储在环境变量中
|
||||
- 不在代码中硬编码
|
||||
|
||||
## 📚 相关文件
|
||||
|
||||
- `tts/README.md` - 完整的 API 文档
|
||||
- `TTS_QUICK_START.md` - 快速开始指南
|
||||
- `TTS_IMPLEMENTATION_SUMMARY.md` - 实现总结
|
||||
- `TTS_INTEGRATION_CHECKLIST.md` - 集成检查清单
|
||||
|
||||
---
|
||||
|
||||
**版本**: 1.0.0
|
||||
**最后更新**: 2025-11-27
|
||||
**作者**: AI Assistant
|
||||
Reference in New Issue
Block a user