GithubBackup/gemini-balance

Fork 0

mirror of https://github.com/snailyp/gemini-balance.git synced 2026-05-07 06:13:09 +08:00

Files

History

…

__init__.py

…

README.md

…

tts_chat_service.py

…

tts_config.py

…

tts_models.py

…

tts_response_handler.py

…

tts_routes.py

…

README.md

原生Gemini TTS功能

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

🎯 设计原则

智能检测：自动检测所有原生Gemini TTS格式的请求（包含responseModalities和speechConfig）
继承而非修改：所有扩展都继承自原始类，不修改源码
完全兼容：原有TTS功能（OpenAI兼容TTS）完全不受影响
动态模型选择：支持用户在请求URL中指定不同的TTS模型
自动回退：原生TTS处理失败时自动回退到标准服务
完整日志记录：包含请求日志、错误日志和性能监控
易于维护：更新原始代码时不会产生冲突

📁 文件结构

app/service/tts/
├── tts_service.py           # 原有的OpenAI兼容TTS服务
└── native/                  # 原生Gemini TTS扩展
    ├── __init__.py          # 模块初始化
    ├── README.md            # 使用说明（本文件）
    ├── tts_models.py        # TTS数据模型（继承自原始模型）
    ├── tts_response_handler.py  # TTS响应处理器（继承自原始处理器）
    ├── tts_chat_service.py  # TTS聊天服务（继承自原始服务）
    └── tts_routes.py        # TTS路由扩展和依赖注入

🚀 原生Gemini TTS功能

智能检测机制（当前实现）

原生Gemini TTS功能通过智能检测自动启用，无需任何配置：

自动启用：

# 直接启动服务，原生TTS功能自动可用
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

无需配置：

不需要环境变量
不需要修改配置文件
完全基于请求内容智能判断

工作原理

系统会智能检测请求内容：

原生TTS请求：包含 responseModalities: ["AUDIO"] 和 speechConfig → 使用TTS增强服务
- 单人TTS：包含 voiceConfig.prebuiltVoiceConfig
- 多人TTS：包含 multiSpeakerVoiceConfig
普通请求：非TTS模型 → 使用原有Gemini聊天服务

# app/router/gemini_routes.py 中的智能检测逻辑
if "tts" in model_name.lower() and request.generationConfig:
    # 直接从解析后的request对象获取TTS配置
    response_modalities = request.generationConfig.responseModalities or []
    speech_config = request.generationConfig.speechConfig or {}

    # 如果包含AUDIO模态和语音配置，则认为是原生TTS请求
    if "AUDIO" in response_modalities and speech_config:
        # 使用TTS增强服务
        tts_service = await get_tts_chat_service(key_manager)
        return await tts_service.generate_content(...)
    # 否则使用原有服务

📝 使用示例

1. 原生Gemini单人TTS请求（使用TTS增强服务）

包含 voiceConfig.prebuiltVoiceConfig 的原生Gemini格式请求会自动使用TTS增强服务：

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"
          }
        }
      }
    }
  }'

2. 原生Gemini多人TTS请求（使用TTS增强服务）

包含 multiSpeakerVoiceConfig 的原生Gemini格式请求会自动使用TTS增强服务：

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": "Alice: Hello everyone, welcome to our show today.\nBob: Hi Alice, and hello to all our listeners! Today we are talking about AI development."
      }]
    }],
    "generationConfig": {
      "responseModalities": ["AUDIO"],
      "speechConfig": {
        "multiSpeakerVoiceConfig": {
          "speakerVoiceConfigs": [
            {
              "speaker": "Alice",
              "voiceConfig": {
                "prebuiltVoiceConfig": {
                  "voiceName": "Puck"
                }
              }
            },
            {
              "speaker": "Bob",
              "voiceConfig": {
                "prebuiltVoiceConfig": {
                  "voiceName": "Kore"
                }
              }
            }
          ]
        }
      }
    }
  }'

3. OpenAI兼容TTS请求（使用原有服务）

OpenAI兼容格式的TTS请求使用不同的API路径，不受本模块影响：

curl -X POST "https://your-domain.com/v1/audio/speech" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "model": "tts-1",
    "input": "这是一个OpenAI兼容格式的TTS测试。",
    "voice": "alloy"
  }' \
  --output openai_tts_test.wav

注意：OpenAI兼容TTS请求：

使用路径：/v1/audio/speech
使用Authorization头而不是x-goog-api-key
返回音频文件而不是JSON响应
不受本模块的TTS增强服务影响

普通文本生成（使用原有服务）

非TTS模型的请求会使用原有的Gemini聊天服务，完全不受影响：

curl -X POST "https://your-domain.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: your-token" \
  -d '{
    "contents": [{
      "parts": [{
        "text": "请简单介绍一下人工智能的发展历程。"
      }]
    }],
    "generationConfig": {
      "maxOutputTokens": 200,
      "temperature": 0.7
    }
  }'

🔧 技术实现

继承关系

GeminiChatService
    ↓ (继承)
TTSGeminiChatService
    ├── 重写 generate_content() 方法
    ├── 添加 _handle_tts_request() 方法
    └── 集成完整的日志记录功能

GeminiResponseHandler
    ↓ (继承)
TTSResponseHandler
    └── 重写 handle_response() 方法

GenerationConfig (Pydantic模型)
    ↓ (扩展)
TTSGenerationConfig
    ├── responseModalities: List[str]
    └── speechConfig: Dict[str, Any]

工作流程

请求接收：系统接收到API请求
智能检测：
- 检查模型名称是否包含 "tts"
- 如果是TTS模型，从 request.generationConfig 检查是否包含 responseModalities: ["AUDIO"] 和 speechConfig
服务选择：
- 原生TTS请求：使用 TTSGeminiChatService 增强服务
- 普通请求：使用原有 GeminiChatService
请求处理：
- 原生TTS：使用 _handle_tts_request() 特殊处理
- 其他请求：使用标准 generate_content() 方法
字段处理：从 request.generationConfig 直接获取TTS字段（responseModalities, speechConfig）
API调用：构建优化的payload并调用Gemini API
自动回退：如果原生TTS处理失败，自动回退到标准服务
响应处理：
- TTS响应：检测音频数据，直接返回原始响应
- 普通响应：使用标准处理方法
日志记录：记录请求时间、成功状态、错误信息到数据库

📊 功能特性

✅ 已实现功能

智能原生TTS支持：支持单人和多人语音合成
- 单人TTS：支持 voiceConfig.prebuiltVoiceConfig 配置
- 多人TTS：支持 multiSpeakerVoiceConfig 配置
智能检测机制：自动检测所有原生Gemini TTS格式的请求
动态模型选择：支持用户在URL中指定不同TTS模型
完全向后兼容：原有TTS功能（OpenAI兼容TTS）完全不受影响
自动回退机制：原生TTS处理失败时自动使用标准服务
完整日志记录：请求日志、错误日志、性能监控
API配额管理：自动重试和密钥轮换
零配置启用：无需环境变量或配置文件修改
错误处理：完整的异常捕获和错误记录

🎵 支持的语音配置

单人语音配置

{
  "responseModalities": ["AUDIO"],
  "speechConfig": {
    "voiceConfig": {
      "prebuiltVoiceConfig": {
        "voiceName": "Kore|Puck|其他预设语音"
      }
    }
  }
}

多人语音配置

{
  "responseModalities": ["AUDIO"],
  "speechConfig": {
    "multiSpeakerVoiceConfig": {
      "speakerVoiceConfigs": [
        {
          "speaker": "角色名称",
          "voiceConfig": {
            "prebuiltVoiceConfig": {
              "voiceName": "Kore|Puck|其他预设语音"
            }
          }
        }
      ]
    }
  }
}

⚠️ 注意事项

API要求

确保API密钥有TTS权限
TTS功能需要 gemini-2.5-flash-preview-tts 模型
注意API配额限制（免费版每天15次）

性能考虑

TTS响应通常比文本响应更大（音频数据）
建议监控API调用频率和成功率
扩展功能不影响原始功能的性能和稳定性

部署建议

生产环境建议先测试普通功能
逐步启用TTS功能并监控日志
定期检查API配额使用情况

📈 监控和调试

日志查看

服务器日志：查看TTS请求处理过程
管理界面：在"API 调用详情"中查看请求记录
错误日志：查看失败请求的详细信息

调试技巧

# 启用详细日志
export LOG_LEVEL=DEBUG

# 查看实时日志
tail -f logs/app.log

# 多人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`	用户指定	多人语音	对话场景	✅ 我们的增强

智能路由机制

flowchart TD
    A[API请求] --> B{路径检查}
    B -->|/v1/audio/speech| C[OpenAI兼容TTS服务]
    B -->|/v1beta/models/{model}:generateContent| D{模型名包含'tts'?}
    D -->|否| E[标准Gemini聊天服务]
    D -->|是| F{包含responseModalities和speechConfig?}
    F -->|否| G[标准Gemini聊天服务]
    F -->|是| H[原生TTS增强服务]
    H --> I{处理成功?}
    I -->|是| J[返回原生TTS响应]
    I -->|否| K[自动回退到标准服务]
    C --> L[完成]
    E --> L
    G --> L
    J --> L
    K --> L

🎉 成功案例

基于智能检测的原生Gemini TTS解决方案已经成功实现：

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

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

README.md Unescape Escape

原生Gemini TTS功能

🎯 设计原则

📁 文件结构

🚀 原生Gemini TTS功能

智能检测机制（当前实现）

工作原理

📝 使用示例

1. 原生Gemini单人TTS请求（使用TTS增强服务）

2. 原生Gemini多人TTS请求（使用TTS增强服务）

3. OpenAI兼容TTS请求（使用原有服务）

普通文本生成（使用原有服务）

🔧 技术实现

继承关系

工作流程

📊 功能特性

✅ 已实现功能

🎵 支持的语音配置

单人语音配置

多人语音配置

⚠️ 注意事项

API要求

性能考虑

部署建议

📈 监控和调试

日志查看

调试技巧

🔄 TTS系统对比

智能路由机制

🎉 成功案例

README.md