强大的API代理解决方案

Gemini Balance 是一个基于 Python FastAPI 构建的高性能应用程序，专为提供 Google Gemini API 的代理和负载均衡功能而设计。

  • 支持多个 Gemini API Key 的智能负载均衡
  • 完美兼容 OpenAI 和 Gemini 双协议格式
  • 提供可视化的Web管理界面
  • 集成图像生成和多种图床上传功能
  • 支持联网搜索和图文对话功能
  • Docker容器化部署，支持AMD/ARM架构

🎯 核心价值

通过智能的负载均衡算法和故障转移机制，确保API服务的高可用性和稳定性。支持实时监控、自动恢复和详细的日志记录，为开发者提供企业级的API代理服务。

核心特性

Gemini Balance 提供的强大功能，让您的API服务更加稳定可靠

⚖️

多Key负载均衡

支持配置多个 Gemini API Key，自动按顺序轮询使用，提高可用性和并发能力，确保服务稳定运行。

🔄

双协议兼容

同时支持 Gemini 和 OpenAI 格式的 API 请求转发，完美兼容现有的客户端和工具。

🎛️

可视化管理

提供直观的Web管理界面，配置修改后无需重启服务即可生效，支持实时监控和状态查看。

🖼️

图文对话

支持图像生成和修改功能，集成多种图床上传服务，提供完整的多媒体对话体验。

🔍

联网搜索

集成Web搜索功能，让AI模型能够获取最新的网络信息，提供更准确的回答。

📊

状态监控

实时监控各个API Key的状态和使用情况，提供详细的调用日志和错误分析。

🐳

Docker支持

支持AMD和ARM架构的Docker部署，提供官方镜像，简化部署和维护流程。

🔧

自动恢复

智能的故障检测和自动恢复机制，失效的Key会被自动禁用，恢复后自动重新启用。

🌐

代理支持

支持HTTP/SOCKS5代理配置，适应各种网络环境，确保API访问的稳定性。

📝

详细日志

提供完整的请求和错误日志记录，支持日志自动清理，便于问题排查和性能优化。

技术架构

基于现代化技术栈构建的高性能API代理服务

核心技术栈

后端框架
Python 3.9+ + FastAPI
数据库
SQLite / MySQL
容器化
Docker + Docker Compose
Web服务器
Uvicorn ASGI

🏗️ 系统架构特点

  • 基于FastAPI的异步ASGI架构，支持高并发请求处理
  • 模块化分层设计：Router → Service → Handler → Client
  • 智能Key轮询算法，支持一致性哈希代理选择
  • 完善的错误处理和自动重试机制
  • 实时监控、统计分析和详细日志记录
  • 支持SQLite和MySQL双数据库后端
  • 智能路由中间件，自动修复API路径
  • 流式响应优化器，提升长文本输出体验

📁 项目结构

app/
├── config/ # 配置管理
├── core/ # 核心应用逻辑
├── database/ # 数据库模型
├── router/ # API路由
├── service/ # 业务逻辑
├── middleware/ # 中间件
├── scheduler/ # 定时任务
├── templates/ # HTML模板
└── main.py # 应用入口

核心算法与高级特性

深入了解 Gemini Balance 的技术实现和创新功能

🔄

智能Key轮询算法

采用循环迭代器(cycle)实现Key轮询，结合异步锁确保线程安全。支持失败计数机制， 自动跳过失效Key，并提供一致性哈希算法用于代理服务器选择。

# 核心轮询逻辑
async def get_next_working_key():
  while key_failure_count < MAX_FAILURES:
    return next(key_cycle)
🛡️

智能路由中间件

自动检测和修复API路径格式，支持Gemini和OpenAI格式的智能转换。 通过URL规范化功能，自动处理不同客户端的路径差异。

# 路径自动修复
generateContent → /v1beta/models/{model}:generateContent
chat/completions → /v1/chat/completions
⚡

流式响应优化器

可配置的流式输出优化器，根据文本长度动态调整输出延迟。 支持短文本快速输出和长文本分块传输，提升用户体验。

# 动态延迟控制
STREAM_MIN_DELAY = 0.016s
STREAM_MAX_DELAY = 0.024s
CHUNK_SIZE = 5 tokens
🔍

多模态内容处理

智能检测消息中的图像内容，自动构建相应的工具配置。 支持图像生成、图像编辑、联网搜索和代码执行等多种工具。

# 工具自动配置
model-image → 图像生成工具
model-search → 联网搜索工具
codeExecution → 代码执行工具
📊

实时统计分析

完整的API调用统计系统，支持按时间段、模型、Key等维度分析。 提供详细的请求日志和错误日志，支持自动清理和数据导出。

# 统计维度
• 调用次数、成功率、响应时间
• 模型使用分布、Key状态监控
• 错误类型分析、性能趋势
🔧

动态配置系统

基于数据库的配置管理系统，支持运行时动态更新配置。 Web界面可视化编辑，配置变更无需重启服务即可生效。

# 配置同步机制
环境变量 → 内存配置 → 数据库存储
支持JSON、列表、字典等复杂类型

安装指南

选择适合您的部署方式，快速开始使用 Gemini Balance

🐳 Docker 部署（推荐）

使用 Docker 容器快速部署，支持 AMD/ARM 架构

拉取官方镜像 
docker pull ghcr.io/snailyp/gemini-balance:latest
运行容器 
docker run -d -p 8000:8000 --env-file .env \
  -v /path/to/data:/app/data \
  ghcr.io/snailyp/gemini-balance:latest

🔧 本地运行

适用于开发和测试环境

安装依赖 
git clone https://github.com/snailyp/gemini-balance.git
cd gemini-balance
pip install -r requirements.txt
启动服务 
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

API接口文档

完整的API接口说明和使用示例

📚 接口分类

GET /v1beta/models

获取可用的 Gemini 模型列表

请求示例

curl -X GET "http://localhost:8000/v1beta/models" \
  -H "Authorization: Bearer your-token"
POST /v1beta/models/{model}:generateContent

使用指定模型生成内容（Gemini 原生格式）

请求示例

curl -X POST "http://localhost:8000/v1beta/models/gemini-1.5-flash:generateContent" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "parts": [{"text": "Hello, how are you?"}]
    }],
    "generationConfig": {
      "temperature": 0.7,
      "maxOutputTokens": 1024
    }
  }'
POST /v1/chat/completions

OpenAI 格式的聊天补全接口，支持流式传输

请求示例

curl -X POST "http://localhost:8000/v1/chat/completions" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-1.5-flash",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "stream": true,
    "temperature": 0.7,
    "max_tokens": 1024
  }'
POST /v1/images/generations

OpenAI 格式的图像生成接口，使用 Imagen 模型

请求示例

curl -X POST "http://localhost:8000/v1/images/generations" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful sunset over the ocean",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
POST /v1/embeddings

OpenAI 格式的文本嵌入接口，用于向量化文本

请求示例

curl -X POST "http://localhost:8000/v1/embeddings" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-004",
    "input": "The quick brown fox jumps over the lazy dog"
  }'
GET /keys

查看所有 API Key 的状态和使用情况（需要管理员权限）

功能特性

  • 实时显示Key状态（有效/无效）
  • API调用统计和成功率
  • 错误日志查看和分析
  • 配置在线编辑和保存

部署架构与最佳实践

生产环境部署指南和性能优化建议

🏗️ 推荐部署架构

┌─ Load Balancer (Nginx/Cloudflare)
│
├─ Gemini Balance (Docker)
│ ├─ FastAPI Application
│ ├─ Key Manager
│ ├─ Request Router
│ └─ Response Handler
│
├─ Database (MySQL/SQLite)
│ ├─ Configuration Storage
│ ├─ Request Logs
│ └─ Error Logs
│
└─ External Services
   ├─ Google Gemini API
   ├─ Image Hosting (SM.MS/PicGo)
   └─ Proxy Servers (Optional)

🚀 性能优化建议

  • 使用Docker Compose进行容器编排
  • 配置MySQL主从复制提升数据库性能
  • 启用Nginx反向代理和负载均衡
  • 配置Redis缓存减少数据库查询
  • 使用CDN加速静态资源访问
  • 定期清理日志文件避免磁盘占满

⚙️ Docker Compose 配置

version: '3.8'
services:
  gemini-balance:
    image: ghcr.io/snailyp/gemini-balance:latest
    container_name: gemini-balance
    restart: unless-stopped
    ports:
      - "8000:8000"
    env_file:
      - .env
    depends_on:
      mysql:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "python -c \"import requests; exit(0) if requests.get('http://localhost:8000/health').status_code == 200 else exit(1)\""]
      interval: 30s
      timeout: 5s
      retries: 3

  mysql:
    image: mysql:8
    container_name: gemini-balance-mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: your_root_password
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1"]
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  mysql_data:

🔧 环境变量配置

# 核心配置
API_KEYS='["key1", "key2"]'
ALLOWED_TOKENS='["token1"]'
DATABASE_TYPE=mysql

# 高级功能
STREAM_OPTIMIZER_ENABLED=true
URL_NORMALIZATION_ENABLED=true
TOOLS_CODE_EXECUTION_ENABLED=true

# 监控配置
LOG_LEVEL=INFO
AUTO_DELETE_ERROR_LOGS_ENABLED=true
CHECK_INTERVAL_HOURS=1

💡 生产环境建议

🔒 安全配置

  • 使用强密码和复杂Token
  • 启用HTTPS和SSL证书
  • 配置防火墙规则
  • 定期更新Docker镜像

📊 监控告警

  • 配置健康检查端点
  • 监控API响应时间
  • 设置Key失效告警
  • 监控磁盘和内存使用

🔄 备份策略

  • 定期备份数据库
  • 配置文件版本控制
  • 日志文件归档
  • 容器镜像备份

配置参考

完整的环境变量配置说明和最佳实践

🔑 API 核心配置

API_KEYS
Gemini API 密钥列表，支持多Key负载均衡
["AIzaSy...", "AIzaSy..."]
ALLOWED_TOKENS
允许访问的客户端Token列表
["sk-123456", "sk-789012"]
BASE_URL
Gemini API 基础URL，支持自定义代理
https://generativelanguage.googleapis.com/v1beta
VERTEX_API_KEYS
Vertex AI API密钥列表（可选）
["vertex-key-1", "vertex-key-2"]

🗄️ 数据库配置

DATABASE_TYPE
数据库类型选择
mysql | sqlite
MYSQL_HOST / MYSQL_PORT
MySQL服务器地址和端口
localhost:3306
MYSQL_USER / MYSQL_PASSWORD
MySQL用户名和密码
username / password
SQLITE_DATABASE
SQLite数据库文件路径
./data/gemini_balance.db

🎨 AI功能配置

IMAGE_MODELS
支持图像生成和编辑的模型
["gemini-2.0-flash-exp"]
SEARCH_MODELS
支持联网搜索的模型
["gemini-2.0-flash-exp"]
THINKING_MODELS
支持思考过程显示的模型
["gemini-2.0-flash-thinking-exp"]
TOOLS_CODE_EXECUTION_ENABLED
是否启用代码执行工具
true | false

🌐 网络与代理

PROXIES
HTTP/SOCKS5代理服务器列表
["http://proxy:8080", "socks5://proxy:1080"]
PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY
是否使用一致性哈希选择代理
true | false
URL_NORMALIZATION_ENABLED
是否启用智能路由映射
true | false
TIME_OUT
API请求超时时间（秒）
300

⚡ 性能优化

STREAM_OPTIMIZER_ENABLED
是否启用流式输出优化器
true | false
STREAM_MIN_DELAY / STREAM_MAX_DELAY
流式输出延迟范围（秒）
0.016 / 0.024
FAKE_STREAM_ENABLED
是否启用伪流式传输
true | false
MAX_FAILURES / MAX_RETRIES
Key失败阈值和重试次数
3 / 3

📊 监控与日志

LOG_LEVEL
日志级别设置
DEBUG | INFO | WARNING | ERROR
AUTO_DELETE_ERROR_LOGS_ENABLED
是否自动删除错误日志
true | false
AUTO_DELETE_ERROR_LOGS_DAYS
错误日志保留天数
7
CHECK_INTERVAL_HOURS
Key状态检查间隔（小时）
1

社区支持

加入我们的社区，获取帮助和分享经验

📚

GitHub 仓库

查看源代码、提交Issue、参与开发

访问 GitHub
💬

Telegram 群组

实时交流、技术支持、问题解答

加入群组
📖

在线文档

详细的使用说明和配置指南

查看文档

⚠️ 重要声明

本项目采用 CC BY-NC 4.0（署名-非商业性使用）协议，禁止任何形式的商业倒卖服务。

作者从未在任何平台售卖此服务，如遇倒卖请谨防受骗！