在中文中阅读此文档

Gemini Balance - Gemini API 代理与负载均衡器

⚠️ 重要提示: 本项目采用 CC BY-NC 4.0 许可证。严禁任何形式的商业转售服务。 我从未在任何平台上出售过此服务。如果您遇到有人出售该服务，那便是转售者，请勿上当。

📖 项目介绍

Gemini Balance 是一个基于 Python FastAPI 构建的应用程序，旨在为 Google Gemini API 提供代理和负载均衡功能。它允许您管理多个 Gemini API 密钥，并通过简单的配置实现密钥轮换、身份验证、模型筛选以及状态监控。此外，该项目还集成了图像生成和多种图片托管上传功能，并支持以 OpenAI API 格式进行代理。

app/
├── config/       # 配置管理
├── core/         # 应用核心逻辑（创建 FastAPI 实例、中间件等）
├── database/     # 数据库模型及连接
├── domain/       # 业务领域对象
├── exception/    # 自定义异常
├── handler/      # 请求处理器
├── log/          # 日志配置
├── main.py       # 应用入口
├── middleware/   # FastAPI 中间件
├── router/       # API 路由（Gemini、OpenAI、状态页面等）
├── scheduler/    # 定时任务（如密钥状态检查）
├── service/      # 业务逻辑服务（聊天、密钥管理、统计等）
├── static/       # 静态文件（CSS、JS）
├── templates/    # HTML 模板（如密钥状态页面）
└── utils/        # 工具函数

✨ 功能亮点

• 多密钥负载均衡: 支持配置多个 Gemini API 密钥 (API_KEYS)，实现自动轮询。
• 可视化配置: 通过管理后台修改的配置会立即生效，无需重启。
• 双协议 API 兼容: 同时支持 Gemini 和 OpenAI CHAT API 格式。
  • OpenAI 基础 URL: http://localhost:8000(/hf)/v1
  • Gemini 基础 URL: http://localhost:8000(/gemini)/v1beta
• 图文聊天与编辑: 使用 IMAGE_MODELS 配置模型，支持图文聊天和编辑。调用时使用 configured_model-image 模型名称。
• 网页搜索: 使用 SEARCH_MODELS 配置模型，支持网页搜索。调用时使用 configured_model-search 模型名称。
• 密钥状态监控: 提供 /keys_status 页面（需认证），用于实时监控。
• 详细日志记录: 提供详细的错误日志，便于排查问题。
• 灵活添加密钥: 使用 gemini_key 正则表达式批量添加密钥，并自动去重。
• 失败重试与自动禁用: 自动重试失败的 API 请求（MAX_RETRIES），并在多次失败后禁用密钥（MAX_FAILURES）。
• 全面的 API 兰兼容性:
  • 嵌入 API: 完全兼容 OpenAI 的 embeddings API 格式。
  • 图像生成 API: 将 imagen-3.0-generate-002 模型适配为 OpenAI 图像生成 API 格式。
• 自动维护模型列表: 自动从 Gemini 和 OpenAI 获取并同步最新的模型列表。
• 代理支持: 支持 HTTP/SOCKS5 代理 (PROXIES)。
• Docker 支持: 提供适用于 AMD 和 ARM 架构的 Docker 镜像。
  • 镜像地址: ghcr.io/snailyp/gemini-balance:latest

🚀 快速开始

选项 1: Docker Compose（推荐）

1. 获取 docker-compose.yml: 从项目仓库下载 docker-compose.yml 文件。
2. 准备 .env 文件: 复制 .env.example 到 .env 并进行配置。确保将 DATABASE_TYPE 设置为 mysql，并填写 MYSQL_* 相关信息。
3. 启动服务: 在包含 docker-compose.yml 和 .env 的目录下，运行：

   docker-compose up -d
   

选项 2: Docker 命令

1. 拉取镜像:

   docker pull ghcr.io/snailyp/gemini-balance:latest
   

2. 准备 .env 文件: 复制 .env.example 到 .env 并进行配置。
3. 运行容器:

   docker run -d -p 8000:8000 --name gemini-balance \
   -v ./data:/app/data \
   --env-file .env \
   ghcr.io/snailyp/gemini-balance:latest
   

   • -d: 以分离模式运行。
   • -p 8000:8000: 将容器端口 8000 映射到主机。
   • -v ./data:/app/data: 挂载卷以保存持久化数据。
   • --env-file .env: 加载环境变量。

选项 3: 本地开发

1. 克隆并安装:

   git clone https://github.com/snailyp/gemini-balance.git
   cd gemini-balance
   pip install -r requirements.txt
   

2. 配置环境: 复制 .env.example 到 .env 并进行配置。
3. 启动应用:

   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
   

   您可以通过 http://localhost:8000 访问应用程序。

⚙️ API 端点

Gemini API 格式 (/gemini/v1beta)

此端点直接转发至官方 Gemini API 格式的端点，不包含高级功能。

• GET /models: 列出可用的 Gemini 模型。
• POST /models/{model_name}:generateContent: 生成内容。
• POST /models/{model_name}:streamGenerateContent: 流式内容生成。

OpenAI API 格式

Hugging Face (HF) 兼容

如果您希望使用高级功能，例如假流式传输，请使用此端点。

• GET /hf/v1/models: 列出模型。
• POST /hf/v1/chat/completions: 聊天补全。
• POST /hf/v1/embeddings: 创建文本嵌入。
• POST /hf/v1/images/generations: 生成图片。

标准 OpenAI

此端点会直接转发到官方的 OpenAI 兼容 API 格式端点，不包含高级功能。

• GET /openai/v1/models: 列出模型。
• POST /openai/v1/chat/completions: 聊天补全（推荐）。
• POST /openai/v1/embeddings: 创建文本嵌入。
• POST /openai/v1/images/generations: 生成图片。

🤝 贡献

欢迎提交 Pull Request 或 Issues。

⭐ 星标历史

🎉 特别感谢

• PicGo
• SM.MS
• CloudFlare-ImgBed

🙏 我们的赞助商

特别鸣谢 DigitalOcean，他们提供了坚固可靠的云基础设施，让本项目得以顺利运行！

本项目的 CDN 加速和安全防护由 腾讯 EdgeOne 赞助。

💖 友好项目

• OneLine 由 chengtx809 开发 - 基于 AI 的热点事件时间线生成工具。

🎁 项目支持

如果您觉得这个项目很有帮助，请考虑通过 Afdian 支持我。

许可证

本项目采用 CC BY-NC 4.0（署名-非商业性使用）许可证。

Gemini Balance 快速上手指南

Gemini Balance 是一个基于 Python FastAPI 构建的 Google Gemini API 代理与负载均衡工具。它支持多 Key 轮询、自动故障转移、OpenAI 格式兼容以及图像生成等功能。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS 或 Windows (推荐 Linux 服务器)
• 容器化方案 (推荐)：
  • Docker Engine 20.10+
  • Docker Compose v2.0+
• 本地运行方案：
  • Python 3.9 或更高版本
  • pip (Python 包管理工具)
  • 数据库：MySQL (推荐) 或 SQLite (轻量级测试用)

提示：国内用户若拉取 Docker 镜像困难，可配置 Docker 镜像加速器（如阿里云、腾讯云等）后再执行拉取命令。

安装步骤

推荐使用 Docker Compose 方式进行部署，管理更便捷且数据持久化配置更清晰。

方式一：Docker Compose 部署（推荐）

1. 获取配置文件 从项目仓库下载 docker-compose.yml 和 .env.example 文件。

   wget https://raw.githubusercontent.com/snailyp/gemini-balance/main/docker-compose.yml
   wget https://raw.githubusercontent.com/snailyp/gemini-balance/main/.env.example -O .env
   

2. 配置环境变量 编辑 .env 文件，填入必要的配置信息。

   • 必填项：
     • API_KEYS: 填入您的 Gemini API Key 列表（例如：["sk-abc...", "sk-def..."]）。
     • ALLOWED_TOKENS: 设置访问令牌，用于客户端鉴权。
     • DATABASE_TYPE: 设置为 mysql 并填写下方的 MYSQL_* 相关信息；若使用 SQLite 则设为 sqlite。
   • 可选项：根据需求配置图片存储、代理地址等。

3. 启动服务 在包含上述文件的目录下执行：

   docker-compose up -d
   

方式二：Docker 单命令部署

如果您不想使用 compose 文件，可以直接运行以下命令（需提前准备好 .env 文件）：

docker run -d -p 8000:8000 --name gemini-balance \
-v ./data:/app/data \
--env-file .env \
ghcr.io/snailyp/gemini-balance:latest

方式三：本地源码运行（开发模式）

1. 克隆代码并安装依赖

   git clone https://github.com/snailyp/gemini-balance.git
   cd gemini-balance
   pip install -r requirements.txt
   # 国内用户可使用清华源加速：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
   

2. 配置环境 复制并编辑配置文件：

   cp .env.example .env
   # 使用编辑器修改 .env 文件
   

3. 启动应用

   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
   

基本使用

服务启动后，默认监听在 http://localhost:8000。

1. 验证服务状态

访问管理面板查看 Key 状态和日志（需要鉴权）：

• 地址：http://localhost:8000/keys_status
• 鉴权 Token：即 .env 中配置的 AUTH_TOKEN 或 ALLOWED_TOKENS 中的第一个。

2. 调用 API (OpenAI 兼容格式)

Gemini Balance 完美兼容 OpenAI SDK。您可以将 Base URL 指向本地服务，即可复用现有的 ChatGPT 客户端或代码。

• Base URL: http://localhost:8000/openai/v1
• API Key: 填写您在 .env 中配置的 ALLOWED_TOKENS 中的任意一个。

Python 调用示例：

from openai import OpenAI

client = OpenAI(
    api_key="your_allowed_token",  # 替换为 .env 中配置的 ALLOWED_TOKENS
    base_url="http://localhost:8000/openai/v1"
)

response = client.chat.completions.create(
    model="gemini-2.5-flash",  # 模型名称会自动同步，也可使用 configured_model-search 等特性模型
    messages=[
        {"role": "system", "content": "你是一个有用的助手。"},
        {"role": "user", "content": "你好，请介绍一下你自己。"}
    ]
)

print(response.choices[0].message.content)

3. 使用高级特性

• 联网搜索：将模型名指定为 configured_model-search 即可触发联网搜索功能（需在 .env 中配置 SEARCH_MODELS）。
• 图片生成/理解：将模型名指定为 configured_model-image 即可使用图文对话或生成功能。
• 负载均衡：只需在 .env 的 API_KEYS 中填入多个 Key，程序会自动进行轮询和故障剔除，无需修改调用代码。

注意：本项目遵循 CC BY-NC 4.0 协议，严禁用于任何形式的商业转售服务。