综合介绍

Gemini Balance是一个使用Python FastAPI框架开发的应用程序，其核心功能是为Google Gemini API提供代理和负载均衡服务。用户可以通过简单的配置，管理多个Gemini API密钥，实现密钥的自动轮询、身份验证和状态监控。该项目不仅支持原生的Gemini API格式，还兼容OpenAI的API格式，允许用户通过统一的接口访问不同的大模型服务。此外，项目还集成了图像生成、网页搜索以及多样的图片托管上传功能。对于开发者而言，它提供了详细的日志记录和灵活的部署选项，包括Docker Compose和本地部署，大大简化了基于Gemini模型开发应用的复杂性。

功能列表

• 多密钥负载均衡: 支持配置多个Gemini API密钥，并按顺序自动进行轮询调用。
• 可视化配置: 提供管理后台，修改配置后可立即生效，无需重启服务。
• 双协议API兼容: 同时支持原生Gemini API和OpenAI Chat API格式，方便在不同服务间切换。
• 图文对话与生成: 支持具备图像理解能力的模型，可进行图文混合聊天，并能调用模型生成图片。
• 网页搜索能力: 为特定模型启用网页搜索功能，使其能够获取并整合互联网信息。
• 密钥状态监控: 提供一个需授权访问的/keys_status页面，用于实时查看每个API密钥的状态。
• 灵活的密钥管理: 支持通过正则表达式批量添加API密钥，并能自动去重。
• 失败重试与自动禁用: 当API请求失败时会自动重试；若密钥失败次数过多，则会自动禁用该密钥，并在设定时间后重新检查。
• 代理支持: 支持配置HTTP或SOCKS5代理，以应对不同的网络环境。
• Docker部署: 提供AMD和ARM架构的Docker镜像，支持通过Docker或Docker Compose快速部署。

使用帮助

Gemini Balance作为一个中间件，为开发者提供稳定、高效的Gemini API访问方式。以下是详细的安装和使用流程。

前期准备：获取Gemini API密钥

在使用此工具前，您首先需要拥有一个或多个Google Gemini API密钥。

1. 访问 Google AI for Developers 官方网站。
2. 点击 “Get API key in Google AI Studio” 按钮。
3. 使用您的Google账户登录。
4. 在AI Studio中，选择“Get API key”选项卡，然后点击“Create API key”即可生成一个新的密钥。请妥善保管好这个密钥。

安装部署

您可以根据自己的环境选择最适合的部署方式。对于大多数用户，推荐使用Docker Compose。

方法一：使用 Docker Compose（推荐）

这是最简单、最快捷的部署方式，能够一键启动应用和数据库。

1. 下载配置文件: 从项目的GitHub仓库中下载 docker-compose.yml 文件。
2. 准备环境变量文件:
   • 在docker-compose.yml文件所在的目录下，复制.env.example文件并重命名为.env。
   • 使用文本编辑器打开.env文件。
   • 找到API_KEYS和ALLOWED_TOKENS这两个关键配置项。
   • API_KEYS: 在英文方括号[]内填入你获取的Gemini API密钥，多个密钥用英文逗号,隔开，每个密钥用英文双引号""包围。

     API_KEYS=["YOUR_GEMINI_KEY_1", "YOUR_GEMINI_KEY_2"]
     

   • ALLOWED_TOKENS: 这是访问此代理服务的授权凭证，您可以自定义一个或多个密码。格式与API_KEYS类似。

     ALLOWED_TOKENS=["YOUR_CUSTOM_PASSWORD_1", "YOUR_CUSTOM_PASSWORD_2"]
     

   • 确保DATABASE_TYPE设置为mysql，并根据需要填写MYSQL_*相关信息（如果使用默认的docker-compose.yml，则无需修改）。
3. 启动服务:打开终端，进入docker-compose.yml文件所在的目录，运行以下命令：

   docker-compose up -d
   ```    Docker将会自动拉取镜像并启动`gemini-balance`服务和MySQL数据库。
   

方法二：使用 Docker 命令

如果您只想运行应用本身，并使用本地文件系统作为数据库（SQLite），可以选择此方式。

1. 拉取Docker镜像:

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

2. 准备环境变量文件:
   • 创建一个.env文件。
   • 在文件中至少配置API_KEYS和ALLOWED_TOKENS。
   • 若要使用SQLite数据库，请设置 DATABASE_TYPE=sqlite。
3. 运行容器:

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

   • -p 8000:8000: 将主机的8000端口映射到容器的8000端口。
   • -v ./data:/app/data: 将主机当前目录下的data文件夹挂载到容器内，用于持久化存储数据（如SQLite数据库文件）。
   • --env-file .env: 从.env文件加载环境变量。

方法三：本地开发环境运行

如果您希望直接在本地机器上运行源代码进行开发或调试。

1. 克隆代码并安装依赖:

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

2. 配置环境变量: 复制.env.example为.env，并填入必要的API_KEYS和ALLOWED_TOKENS信息。
3. 启动应用:

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

   服务将在本地的8000端口启动，--reload参数会使服务在代码变更后自动重启。

功能操作

服务启动后，您就可以通过API端点来使用其功能了。

1. 访问模型列表:您可以通过兼容OpenAI格式的API来获取当前可用的模型列表。
   • 端点: http://<your_server_ip>:8000/v1/models 或 http://<your_server_ip>:8000/openai/v1/models
   • 请求头: 需要包含授权信息 Authorization: Bearer YOUR_CUSTOM_PASSWORD_1
   • 示例 (使用curl):

     curl http://127.0.0.1:8000/v1/models -H "Authorization: Bearer YOUR_CUSTOM_PASSWORD_1"
     

2. 进行聊天补全 (Chat Completion):这是最核心的功能，您可以像调用OpenAI API一样调用Gemini模型。
   • 端点: http://<your_server_ip>:8000/v1/chat/completions
   • 请求头: Authorization: Bearer YOUR_CUSTOM_PASSWORD_1
   • 请求体 (Body):

     {
     "model": "gemini-1.5-flash",
     "messages": [
     {
     "role": "user",
     "content": "你好，请介绍一下你自己。"
     }
     ],
     "stream": false
     }
     

   • 将上述请求发送到端点，即可获得由Gemini模型生成的回复。model字段可以替换为API_KEYS所支持的任何模型。
3. 监控密钥状态:打开浏览器，访问 http://<your_server_ip>:8000/keys_status。系统会要求您进行身份验证，输入您在ALLOWED_TOKENS中设置的其中一个密码即可查看所有API密钥的当前状态、请求次数、失败次数等信息。

应用场景

1. 开发者集成对于需要在自己应用中集成Gemini AI功能但又担心API密钥泄露或希望管理多个密钥成本的开发者，Gemini Balance提供了一个安全可靠的中间层。开发者只需将API请求指向自己部署的Gemini Balance服务，即可实现负载均衡和统一的访问控制。
2. 团队共享在小型团队或项目中，可以部署一个Gemini Balance服务，并为团队成员分配不同的访问token。这样既可以共享一组Gemini API密钥，又能通过后台监控使用情况，方便成本核算与管理，避免了将原始API密钥直接分发给多人的安全风险。
3. 多模型服务统一接入由于Gemini Balance兼容OpenAI的API格式，已经在使用OpenAI API的应用可以几乎无缝地切换到使用Gemini模型。只需将API请求的base_url修改为Gemini Balance服务的地址，并更换模型名称，即可利用Gemini的能力，无需重写大量代码。
4. 学习与实验对于AI爱好者或学生，使用Gemini Balance可以方便地在本地环境中进行实验。通过其详细的日志功能，可以清晰地看到请求与响应的完整过程，有助于理解大模型API的工作原理。

QA

1. 使用这个项目是否会泄露我的Gemini API密钥？不会。Gemini Balance是一个开源项目，您可以自行部署在自己的服务器或本地电脑上。您的API密钥仅存储在您自己控制的环境变量文件或数据库中，不会发送给项目作者或任何第三方。
2. 为什么我向/v1/chat/completions发送请求时会收到认证失败的错误？请确保您的API请求中包含了正确的授权头。您需要在HTTP请求的Header中添加Authorization: Bearer YOUR_TOKEN，其中YOUR_TOKEN是您在.env文件里ALLOWED_TOKENS中设置的密码之一。
3. 如果我的一个API密钥额度用完了或者失效了会怎么样？Gemini Balance的自动失败重试和禁用机制会处理这种情况。当一个密钥连续请求失败达到设定的次数（默认为3次）后，系统会自动将其禁用，并在后续的请求中跳过该密钥。系统会周期性地（默认为1小时）重新检查被禁用的密钥是否恢复正常。
4. 我可以在哪些客户端或库中使用这个代理服务？任何支持配置OpenAI API base_url的客户端或库都可以使用。您只需将配置中的base_url指向您部署的Gemini Balance服务地址（例如http://127.0.0.1:8000/v1），并提供相应的api_key（即您在ALLOWED_TOKENS中设置的密码）。