Update multi-speaker TTS README

- Reflect current smart detection implementation - Remove outdated ENABLE_TTS environment variable references - Add TTS systems comparison table - Update usage examples with correct URLs - Add intelligent routing flowchart - Clarify zero-configuration approach - Update feature list to match current implementation
2026-07-20 20:11:43 +08:00 · 2025-07-15 15:55:47 +09:00
parent af5b2fa2c9
commit 1a6feae23b
2 changed files with 126 additions and 59 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -258,5 +258,4 @@ $RECYCLE.BIN/
 # Custom rules (everything added below won't be overriden by 'Generate .gitignore File' if you use 'Update' option)

 tests/
-default_db
-.augment-guidelines
+default_db
--- a/app/service/tts/multi_speaker/README.md
+++ b/app/service/tts/multi_speaker/README.md
@@ -1,12 +1,14 @@
 # 多人对话TTS功能

-这个模块为Gemini Balance项目添加了多人语音TTS（Text-to-Speech）功能，采用继承模式设计，保持与原始代码的完全兼容性。
+这个模块为Gemini Balance项目添加了多人语音TTS（Text-to-Speech）功能，采用智能检测和继承模式设计，保持与原始代码的完全兼容性。

 ## 🎯 设计原则

+- **智能检测**：只有包含 `multiSpeakerVoiceConfig` 的请求才启用多人TTS
 - **继承而非修改**：所有扩展都继承自原始类，不修改源码
- **向后兼容**：原始功能完全不受影响
- **环境变量控制**：通过 `ENABLE_TTS` 环境变量动态启用
+- **完全兼容**：原有TTS功能（单人TTS、OpenAI兼容TTS）完全不受影响
+- **动态模型选择**：支持用户在请求URL中指定不同的TTS模型
+- **自动回退**：多人TTS处理失败时自动回退到标准服务
 - **完整日志记录**：包含请求日志、错误日志和性能监控
 - **易于维护**：更新原始代码时不会产生冲突

@@ -14,64 +16,60 @@

 ```
 app/service/tts/
-├── tts_service.py           # 原有的基础TTS服务
+├── tts_service.py           # 原有的OpenAI兼容TTS服务
 └── multi_speaker/           # 多人对话TTS扩展
    ├── __init__.py          # 模块初始化
    ├── README.md            # 使用说明（本文件）
    ├── tts_models.py        # TTS数据模型（继承自原始模型）
    ├── tts_response_handler.py  # TTS响应处理器（继承自原始处理器）
    ├── tts_chat_service.py  # TTS聊天服务（继承自原始服务）
-    ├── tts_config.py        # TTS配置管理和工厂方法
    └── tts_routes.py        # TTS路由扩展和依赖注入
 ```

-## 🚀 启用TTS功能
+## 🚀 多人TTS功能

-### 自动集成（当前实现）
+### 智能检测机制（当前实现）

-TTS功能已经完全集成到主路由中，通过环境变量自动控制：
+多人TTS功能通过智能检测自动启用，无需任何配置：

-1. **TTS功能默认启用**：
+1. **自动启用**：
 ```bash
-# 直接启动服务，TTS功能已默认启用
+# 直接启动服务，多人TTS功能自动可用
 python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
 ```

-2. **禁用TTS功能**（如需要）：
-```bash
-# Windows PowerShell
-$env:ENABLE_TTS="false"
-python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
-
-# Linux/macOS
-export ENABLE_TTS=false
-python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
-```
+2. **无需配置**：
+- 不需要环境变量
+- 不需要修改配置文件
+- 完全基于请求内容智能判断

 ### 工作原理

-系统会自动检测 `ENABLE_TTS` 环境变量：
- `true`, `1`, `yes`, `on`（默认值）：启用TTS功能
- `false`, `0`, `no`, `off`：使用原始服务
+系统会智能检测请求内容：
+- **多人TTS请求**：包含 `multiSpeakerVoiceConfig` → 使用多人TTS增强服务
+- **单人TTS请求**：不包含 `multiSpeakerVoiceConfig` → 使用原有Gemini TTS服务
+- **普通请求**：非TTS模型 → 使用原有Gemini聊天服务

 ```python
-# app/router/gemini_routes.py 中的自动切换逻辑
-async def get_chat_service(key_manager: KeyManager = Depends(get_key_manager)):
-    import os
-    if os.getenv("ENABLE_TTS", "false").lower() in ("true", "1", "yes", "on"):
-        return await get_tts_chat_service(key_manager)
-    else:
-        return GeminiChatService(settings.BASE_URL, key_manager)
+# app/router/gemini_routes.py 中的智能检测逻辑
+if "tts" in model_name.lower():
+    # 检查是否包含多人语音配置
+    speech_config = raw_data.get("generationConfig", {}).get("speechConfig", {})
+    if "multiSpeakerVoiceConfig" in speech_config:
+        # 使用多人TTS增强服务
+        tts_service = await get_tts_chat_service(key_manager)
+        return await tts_service.generate_content(...)
+    # 否则使用原有服务
 ```

 ## 📝 使用示例

-### 多人语音TTS请求
+### 多人语音TTS请求（自动启用增强服务）

-启用TTS功能后，可以发送多人语音请求：
+包含 `multiSpeakerVoiceConfig` 的请求会自动使用多人TTS增强服务：

 ```bash
-curl -X POST "http://localhost:8000/v1beta/models/gemini-2.5-flash-preview-tts:generateContent" \
+curl -X POST "https://your-domain.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: your-token" \
  -d '{
@@ -94,7 +92,7 @@ curl -X POST "http://localhost:8000/v1beta/models/gemini-2.5-flash-preview-tts:g
              }
            },
            {
-              "speaker": "小雅", 
+              "speaker": "小雅",
              "voiceConfig": {
                "prebuiltVoiceConfig": {
                  "voiceName": "Puck"
@@ -108,12 +106,39 @@ curl -X POST "http://localhost:8000/v1beta/models/gemini-2.5-flash-preview-tts:g
  }'
 ```

-### 普通文本生成（兼容性测试）
+### 单人TTS请求（使用原有服务）

-TTS功能启用后，普通文本生成仍然正常工作：
+不包含 `multiSpeakerVoiceConfig` 的TTS请求会使用原有的Gemini TTS服务：

 ```bash
-curl -X POST "http://localhost:8000/v1beta/models/gemini-1.5-flash:generateContent" \
+curl -X POST "https://your-domain.com/v1beta/models/gemini-2.5-flash-preview-tts:generateContent" \
+  -H "Content-Type: application/json" \
+  -H "x-goog-api-key: your-token" \
+  -d '{
+    "contents": [{
+      "parts": [{
+        "text": "Hello, this is a single speaker test."
+      }]
+    }],
+    "generationConfig": {
+      "responseModalities": ["AUDIO"],
+      "speechConfig": {
+        "voiceConfig": {
+          "prebuiltVoiceConfig": {
+            "voiceName": "Kore"
+          }
+        }
+      }
+    }
+  }'
+```
+
+### 普通文本生成（使用原有服务）
+
+非TTS模型的请求会使用原有的Gemini聊天服务，完全不受影响：
+
+```bash
+curl -X POST "https://your-domain.com/v1beta/models/gemini-1.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: your-token" \
  -d '{
@@ -155,28 +180,37 @@ TTSGenerationConfig

 ### 工作流程

-1. **环境检测**：系统启动时检查 `ENABLE_TTS` 环境变量（默认为true）
-2. **服务选择**：根据环境变量选择 `GeminiChatService` 或 `TTSGeminiChatService`
-3. **请求处理**：
-   - **TTS模型**：使用 `_handle_tts_request()` 处理
-   - **普通模型**：调用父类 `generate_content()` 方法
-4. **字段处理**：从原始HTTP请求体提取TTS字段（`responseModalities`, `speechConfig`）
-5. **API调用**：构建完整payload并调用Gemini API
-6. **响应处理**：
+1. **请求接收**：系统接收到API请求
+2. **智能检测**：
+   - 检查模型名称是否包含 "tts"
+   - 如果是TTS模型，解析请求体检查是否包含 `multiSpeakerVoiceConfig`
+3. **服务选择**：
+   - **多人TTS请求**：使用 `TTSGeminiChatService` 增强服务
+   - **单人TTS请求**：使用原有 `GeminiChatService`
+   - **普通请求**：使用原有 `GeminiChatService`
+4. **请求处理**：
+   - **多人TTS**：使用 `_handle_tts_request()` 特殊处理
+   - **其他请求**：使用标准 `generate_content()` 方法
+5. **字段处理**：从原始HTTP请求体提取TTS字段（`responseModalities`, `speechConfig`）
+6. **API调用**：构建优化的payload并调用Gemini API
+7. **自动回退**：如果多人TTS处理失败，自动回退到标准服务
+8. **响应处理**：
   - **TTS响应**：检测音频数据，直接返回原始响应
-   - **普通响应**：使用父类处理方法
-7. **日志记录**：记录请求时间、成功状态、错误信息到数据库
+   - **普通响应**：使用标准处理方法
+9. **日志记录**：记录请求时间、成功状态、错误信息到数据库

 ## 📊 功能特性

 ### ✅ 已实现功能

- **多人语音合成**：支持 `multiSpeakerVoiceConfig` 配置
- **自动模型检测**：根据模型名称自动启用TTS处理
+- **智能多人语音合成**：支持 `multiSpeakerVoiceConfig` 配置
+- **智能检测机制**：只有多人TTS请求才启用增强服务
+- **动态模型选择**：支持用户在URL中指定不同TTS模型
+- **完全向后兼容**：原有TTS功能（单人TTS、OpenAI兼容TTS）完全不受影响
+- **自动回退机制**：多人TTS处理失败时自动使用标准服务
 - **完整日志记录**：请求日志、错误日志、性能监控
 - **API配额管理**：自动重试和密钥轮换
- **向后兼容性**：原始功能完全不受影响
- **环境变量控制**：TTS功能默认启用，可通过环境变量禁用
+- **零配置启用**：无需环境变量或配置文件修改
 - **错误处理**：完整的异常捕获和错误记录

 ### 🎵 支持的语音配置
@@ -233,19 +267,53 @@ export LOG_LEVEL=DEBUG
 # 查看实时日志
 tail -f logs/app.log

-# TTS功能已默认启用，如需禁用可设置：
-# export ENABLE_TTS=false
+# 多人TTS功能无需配置，自动启用
+# 可通过请求内容智能检测
+```
+
+## 🔄 TTS系统对比
+
+项目中现在有三套TTS系统，各自服务不同的用途：
+
+| TTS类型 | 路径 | 模型选择 | 语音配置 | 使用场景 | 我们的影响 |
+|---------|------|----------|----------|----------|------------|
+| **OpenAI兼容TTS** | `/v1/audio/speech` | 固定配置文件 | 单人语音 | OpenAI API兼容 | ✅ 无影响 |
+| **Gemini单人TTS** | `/v1beta/models/{model}:generateContent` | 用户指定 | 单人语音 | 原生Gemini TTS | ✅ 无影响 |
+| **Gemini多人TTS** | `/v1beta/models/{model}:generateContent` | 用户指定 | 多人语音 | 对话场景 | ✅ 我们的增强 |
+
+### 智能路由机制
+
+```mermaid
+flowchart TD
+    A[API请求] --> B{路径检查}
+    B -->|/v1/audio/speech| C[OpenAI兼容TTS服务]
+    B -->|/v1beta/models/{model}:generateContent| D{模型名包含'tts'?}
+    D -->|否| E[标准Gemini聊天服务]
+    D -->|是| F{包含multiSpeakerVoiceConfig?}
+    F -->|否| G[原有Gemini TTS服务]
+    F -->|是| H[多人TTS增强服务]
+    H --> I{处理成功?}
+    I -->|是| J[返回多人TTS响应]
+    I -->|否| K[自动回退到标准服务]
+    C --> L[完成]
+    E --> L
+    G --> L
+    J --> L
+    K --> L
 ```

 ## 🎉 成功案例

-基于继承的TTS解决方案已经成功实现：
+基于智能检测的多人TTS解决方案已经成功实现：

- ✅ **完全向后兼容**：原始功能零影响
+- ✅ **零配置启用**：无需任何环境变量或配置修改
+- ✅ **智能检测**：只有多人TTS请求才使用增强服务
+- ✅ **完全向后兼容**：所有原有TTS功能零影响
+- ✅ **动态模型选择**：支持用户指定不同TTS模型
+- ✅ **自动回退机制**：处理失败时自动使用标准服务
 - ✅ **多人语音合成**：支持复杂的对话场景
 - ✅ **完整日志记录**：可在管理界面查看所有请求
- ✅ **环境变量控制**：默认启用，可灵活控制
 - ✅ **错误处理完善**：API配额和重试机制
 - ✅ **易于维护**：更新原始代码无冲突

-这个实现展示了如何在不修改原始代码的情况下，优雅地扩展复杂系统的功能。
+这个实现展示了如何在不修改原始代码的情况下，优雅地扩展复杂系统的功能，同时保持完美的向后兼容性。