Gemini Balance
综合介绍
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密钥。
- 访问 Google AI for Developers 官方网站。
- 点击 “Get API key in Google AI Studio” 按钮。
- 使用您的Google账户登录。
- 在AI Studio中,选择“Get API key”选项卡,然后点击“Create API key”即可生成一个新的密钥。请妥善保管好这个密钥。
安装部署
您可以根据自己的环境选择最适合的部署方式。对于大多数用户,推荐使用Docker Compose。
方法一:使用 Docker Compose(推荐)
这是最简单、最快捷的部署方式,能够一键启动应用和数据库。
- 下载配置文件: 从项目的GitHub仓库中下载
docker-compose.yml
文件。 - 准备环境变量文件:
- 在
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
,则无需修改)。
- 在
- 启动服务:打开终端,进入
docker-compose.yml
文件所在的目录,运行以下命令:docker-compose up -d ``` Docker将会自动拉取镜像并启动`gemini-balance`服务和MySQL数据库。
方法二:使用 Docker 命令
如果您只想运行应用本身,并使用本地文件系统作为数据库(SQLite),可以选择此方式。
- 拉取Docker镜像:
docker pull ghcr.io/snailyp/gemini-balance:latest
- 准备环境变量文件:
- 创建一个
.env
文件。 - 在文件中至少配置
API_KEYS
和ALLOWED_TOKENS
。 - 若要使用SQLite数据库,请设置
DATABASE_TYPE=sqlite
。
- 创建一个
- 运行容器:
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
文件加载环境变量。
方法三:本地开发环境运行
如果您希望直接在本地机器上运行源代码进行开发或调试。
- 克隆代码并安装依赖:
git clone https://github.com/snailyp/gemini-balance.git cd gemini-balance pip install -r requirements.txt
- 配置环境变量: 复制
.env.example
为.env
,并填入必要的API_KEYS
和ALLOWED_TOKENS
信息。 - 启动应用:
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
服务将在本地的8000端口启动,
--reload
参数会使服务在代码变更后自动重启。
功能操作
服务启动后,您就可以通过API端点来使用其功能了。
- 访问模型列表:您可以通过兼容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"
- 端点:
- 进行聊天补全 (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
所支持的任何模型。
- 端点:
- 监控密钥状态:打开浏览器,访问
http://<your_server_ip>:8000/keys_status
。系统会要求您进行身份验证,输入您在ALLOWED_TOKENS
中设置的其中一个密码即可查看所有API密钥的当前状态、请求次数、失败次数等信息。
应用场景
- 开发者集成对于需要在自己应用中集成Gemini AI功能但又担心API密钥泄露或希望管理多个密钥成本的开发者,Gemini Balance提供了一个安全可靠的中间层。开发者只需将API请求指向自己部署的Gemini Balance服务,即可实现负载均衡和统一的访问控制。
- 团队共享在小型团队或项目中,可以部署一个Gemini Balance服务,并为团队成员分配不同的访问
token
。这样既可以共享一组Gemini API密钥,又能通过后台监控使用情况,方便成本核算与管理,避免了将原始API密钥直接分发给多人的安全风险。 - 多模型服务统一接入由于Gemini Balance兼容OpenAI的API格式,已经在使用OpenAI API的应用可以几乎无缝地切换到使用Gemini模型。只需将API请求的
base_url
修改为Gemini Balance服务的地址,并更换模型名称,即可利用Gemini的能力,无需重写大量代码。 - 学习与实验对于AI爱好者或学生,使用Gemini Balance可以方便地在本地环境中进行实验。通过其详细的日志功能,可以清晰地看到请求与响应的完整过程,有助于理解大模型API的工作原理。
QA
- 使用这个项目是否会泄露我的Gemini API密钥?不会。Gemini Balance是一个开源项目,您可以自行部署在自己的服务器或本地电脑上。您的API密钥仅存储在您自己控制的环境变量文件或数据库中,不会发送给项目作者或任何第三方。
- 为什么我向
/v1/chat/completions
发送请求时会收到认证失败的错误?请确保您的API请求中包含了正确的授权头。您需要在HTTP请求的Header中添加Authorization: Bearer YOUR_TOKEN
,其中YOUR_TOKEN
是您在.env
文件里ALLOWED_TOKENS
中设置的密码之一。 - 如果我的一个API密钥额度用完了或者失效了会怎么样?Gemini Balance的自动失败重试和禁用机制会处理这种情况。当一个密钥连续请求失败达到设定的次数(默认为3次)后,系统会自动将其禁用,并在后续的请求中跳过该密钥。系统会周期性地(默认为1小时)重新检查被禁用的密钥是否恢复正常。
- 我可以在哪些客户端或库中使用这个代理服务?任何支持配置OpenAI API
base_url
的客户端或库都可以使用。您只需将配置中的base_url
指向您部署的Gemini Balance服务地址(例如http://127.0.0.1:8000/v1
),并提供相应的api_key
(即您在ALLOWED_TOKENS
中设置的密码)。