Gemini Balance：开源API负载均衡代理服务完全指南

上个月，我的一个朋友在凌晨两点给我打电话，说他的Gemini API又炸了。这已经是这周第三次。他做了个小工具，用Gemini API给用户提供AI对话服务，结果流量一上来，API就开始各种报错、超时、限流。"有没有什么办法能让我不用半夜爬起来切换API Key？"他在电话里问我。我说有，开源社区早就有人想到这个问题了。

当API成为生产力工具时，稳定性就成了刚需

说实话，Google的Gemini API本身挺好用的。模型能力强，价格也不算离谱，对于个人开发者和小团队来说是个不错的选择。但问题在于，任何API服务都有限流、都有配额、都可能出错。

当你只是写个Demo玩玩，这些都不是问题。但一旦你把它用到了真实业务场景——哪怕只是一个小小的Chrome插件，或者一个几百人用的Telegram Bot——这些"偶尔出现"的问题就会变成"经常困扰"你的麻烦。

用户可不管你是不是超配额了，他们只知道：我点了按钮，你没给我响应 😤

这就是gemini-balance这个项目存在的意义。它不是要重新发明轮子，而是在Google官方API的基础上，加了一层更聪明的代理层。

它到底解决了什么问题？

让我用最直白的话说：

• 多个API Key自动轮询：你有5个Key，它会自动帮你轮流用，一个不行换下一个
• 失败自动重试：请求失败了？没关系，它会重试，还会自动禁用坏掉的Key
• 双协议兼容：既支持Gemini原生格式，也支持OpenAI格式，你的老代码不用改
• 可视化管理界面：不用改配置文件，网页上点几下就能管理所有Key
• 详细的监控日志：每个Key的状态、请求成功率，一目了然

这些功能听起来很基础，但恰恰是最实用的那种基础。就像你买车，ABS和安全气囊看起来不起眼，但真遇到事儿的时候，能救命。

从安装到运行：没有你想象的那么复杂

我知道，很多开发者一看到"需要部署"、"需要配置环境"这些字眼就头大。但这个项目的部署流程，真的算是我见过最友好的那一批了。

Docker一键启动（推荐）

如果你用Docker，整个过程不超过五分钟：

# 拉取镜像
docker pull ghcr.io/snailyp/gemini-balance:latest

# 准备配置文件
cp .env.example .env
# 编辑.env，填入你的API Keys和Token

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

三条命令，服务就跑起来了。访问http://localhost:8000，你就能看到管理界面。

项目同时支持AMD64和ARM架构，也就是说无论你是用X86服务器还是树莓派，都能跑。这点很贴心，因为现在越来越多人开始用ARM架构的云服务器（便宜啊）💰

本地开发部署

如果你想自己折腾源码，也很简单：

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

整个项目是用Python + FastAPI写的，代码结构很清晰。如果你想二次开发，完全可以。

配置文件里的学问：每一项都有存在的理由

.env配置文件看起来选项很多，但分类其实很明确。我挑几个最关键的说说：

核心配置

重点说说API_KEYS这一项。项目支持用正则表达式批量添加密钥，而且会自动去重。这意味着你可以直接把一堆Key扔进去，不用担心重复或者格式问题。

数据库选择

项目支持两种数据库：

• SQLite：适合个人使用，零配置
• MySQL：适合多用户场景，性能更好

如果你只是自己用，SQLite完全够了。但如果你要给团队用，或者请求量比较大，建议用MySQL。配置也很简单，就是填几个连接参数而已。

高级功能

这个项目不只是个简单的代理，它还集成了一些很实用的功能：

图片生成和上传 🎨
配置CREATE_IMAGE_MODEL和上传服务提供商（SM.MS、PicGo或CloudFlare），就能让Gemini生成的图片自动上传到图床，返回外链。这对做聊天机器人的场景特别有用。

Web搜索增强 🔍
通过SEARCH_MODELS配置，可以让指定的模型具备联网搜索能力。调用时只需在模型名后加-search后缀，比如gemini-2.0-flash-exp-search。

TTS语音合成 🎤
项目甚至还支持文字转语音功能，可以配置语音模型、说话人和语速。这个功能很多人可能不知道Gemini也能做。

流式输出优化 ⚡
开启STREAM_OPTIMIZER_ENABLED后，可以让流式响应更平滑。这对用户体验很重要——没人喜欢看到文字一次性蹦出来或者卡顿。

两套API格式：老项目不用改代码

这是我最欣赏这个项目的一点：完全兼容OpenAI的API格式。

什么意思呢？假设你之前写了一个调用OpenAI API的项目，现在想换成Gemini来省钱或者试试新模型，你需要改多少代码？

答案是：只需要改Base URL。

# 原来的OpenAI调用
client = OpenAI(
    base_url="https://api.openai.com/v1",
    api_key="sk-..."
)

# 换成Gemini Balance，其他代码一行不改
client = OpenAI(
    base_url="http://localhost:8000/openai/v1",
    api_key="你的ALLOWED_TOKEN"
)

项目提供了三套路由：

Gemini原生格式：/v1beta/models
HuggingFace格式：/hf/v1
OpenAI格式：/openai/v1（推荐）

最常用的几个API都支持：

• GET /models – 列出可用模型
• POST /chat/completions – 对话补全
• POST /embeddings – 文本向量化
• POST /images/generations – 图片生成

而且，项目会自动同步最新的模型列表。Gemini每次发布新模型，你不用手动更新配置，系统会自己去拉取。这个细节很贴心，因为Google最近发新模型的频率还挺高的。

监控和管理：你需要知道系统在干什么

生产环境最怕的是什么？是出了问题你不知道，或者知道了但找不到原因。

gemini-balance在这方面做得很细致：

密钥状态页面

访问/keys_status（需要认证），你能看到：

• 每个API Key的状态（启用/禁用）
• 累计使用次数
• 失败次数
• 最后使用时间
• 当前限流状态

这个页面是实时更新的。如果某个Key突然失效了，你一眼就能看出来。

日志系统

项目的日志分两类：

1. 请求日志：记录每次API调用的详细信息
2. 错误日志：记录所有异常和失败

而且可以配置自动删除过期日志，默认错误日志保留7天，请求日志保留30天。这样不会让磁盘被日志撑爆，又能保留足够长的追溯期。

如果你想排查问题，可以把LOG_LEVEL调成DEBUG，会输出更详细的信息。

定时任务

系统有个后台定时任务，每隔一定时间（默认1小时）会重新检查被禁用的Key。

为什么要这么做？因为有些错误是暂时性的——比如超过配额上限，过了一个小时配额刷新了，Key就又能用了。自动重试机制能让系统具备一定的"自愈"能力。

性能和稳定性：经得起实战检验

说了这么多功能，但最终还是要回到最本质的问题：它靠谱吗？

我自己测试了一段时间，也看了GitHub上其他用户的反馈，可以说几点：

并发处理能力不错 👍
FastAPI本身就是为高并发设计的异步框架，再加上负载均衡机制，处理几百个并发请求没什么压力。当然，最终瓶颈还是在Gemini API那边。

失败恢复很快
如果一个Key暂时不可用，系统会立即切换到下一个，整个过程用户几乎感知不到。而且重试机制比较激进（默认最多3次），大部分暂时性错误都能被自动处理掉。

资源占用低
我在一台1核2G的VPS上跑过，CPU和内存占用都很低。如果用SQLite，磁盘IO也不会成为瓶颈。

错误提示清晰
遇到问题时，日志会明确告诉你是哪个Key、什么请求、什么错误。这对于快速定位问题非常重要。

不过也有些需要注意的地方：

• 如果你的Key都被Google限流了，代理也救不了你 😅
• 图片上传功能依赖第三方图床，稳定性取决于图床本身
• 大流量场景建议用MySQL，SQLite可能会出现锁等待

代码质量和社区氛围

从GitHub仓库来看，这个项目维护得还不错：

• 代码结构清晰：按照FastAPI的标准项目结构组织，router、service、domain分层明确
• 文档比较详细：README写得很用心，配置项都有说明
• 持续更新：作者一直在修bug和加新功能
• 开源协议合理：使用CC BY-NC 4.0协议，允许非商业使用和修改

作者在README里明确声明禁止商业转售服务，这个态度我挺赞同的。开源是为了让更多人受益，而不是让某些人拿去做生意却不回馈社区。

项目也提供了赞助链接（爱发电），如果你觉得好用，可以请作者喝杯咖啡 ☕

谁适合用这个项目？

在我看来，以下几类人会觉得这东西很有用：

1. 个人开发者
你有好几个Gemini API Key（可能是不同账号的），想统一管理和负载均衡，同时希望兼容OpenAI的客户端代码。

2. 小团队
团队里多个人都要用Gemini API，但不想每个人都管理自己的Key，希望有统一的入口和使用统计。

3. 做聊天机器人的
需要Gemini的多模态能力（文本+图片），又需要稳定性保障，不能让用户看到各种错误信息。

4. 想省API费用的
通过负载均衡机制，可以更充分地利用每个Key的免费额度，延迟达到付费阈值的时间。

5. 有二次开发需求的
代码写得挺规范的，如果你想加点自己的业务逻辑，改起来不会太痛苦。

当然，如果你只是偶尔调用几次API，或者流量非常小，直接用官方API就行了，不用搞这么复杂。

可能的改进方向

没有什么项目是完美的，这个也一样。如果我是作者，可能会考虑加这些功能：

更智能的负载均衡策略
现在是简单的轮询，可以考虑根据每个Key的响应时间、成功率来动态调整权重，让快的Key多干活。

Key的使用配额统计
能看到每个Key还剩多少配额就更好了，这样可以提前知道什么时候需要加新Key。

Webhook通知
当Key失效或者系统出现严重错误时，能通过Webhook或者邮件通知管理员。现在只能靠你主动去看监控页面。

前端管理界面优化
现在的管理界面比较简陋，如果能做得更友好一些，加点图表什么的，体验会更好。

更多图床支持
目前只支持三种图床，可以再加点阿里云OSS、七牛云这种大厂的对象存储服务。

不过话说回来，这些都是锦上添花的东西。就现在的功能，已经能满足大部分场景了。

我那个朋友后来用上了这个项目，现在晚上能睡个安稳觉了。他说最大的感受就是省心——以前每次API出问题都要手动处理，现在系统自己就搞定了。

这可能就是好工具的标准：它不会让你感到它的存在，但少了它你会很痛苦。

如果你也有类似的需求，不妨试试这个项目。开源世界最美好的地方就在于，总有人会想到和你一样的痛点，并且把解决方案免费分享出来。而你需要做的，就是站在巨人的肩膀上，继续往前走。

或者，如果你有更好的想法，也可以给项目提PR。这才是开源精神该有的样子 🚀