胖鹅爱分享

Gemini Balance 以 Python + FastAPI 为核心，整合多 Key 轮询、负载均衡、权限过滤与健康监控，并向下兼容 OpenAI 接口格式。最新版在性能、文档与安全性上全面升级，引入 countTokens 端点、自动思考配置优化、本地与云端双向代理指南，以及 ARM/AMD Docker 镜像，帮助开发者快速构建高可用的 Gemini 服务栈。

Gemini Balance介绍

Gemini Balance 是一个开源 Gemini API 代理与负载均衡器，支持在同一实例中管理多组 Gemini API Key，并通过轮询算法分摊流量，显著降低单 Key 触发速率限制的风险。相比上游版本，当前 Fork 进一步修复配置缺陷、强化安全策略，并补全繁体中文与英文文档，方便跨地区团队协作。

Gemini Balance关键功能

多 Key 轮询与负载均衡

• 自动按顺序轮询多个 Gemini API Key，均衡请求负载并提升并发能力

• 可配置最大重试次数与失败自动禁用策略，定时检测恢复失效 Key

实时状态监控

• 提供认证访问的 /keys_status页面，实时展示各 Key 的使用情况与健康指标
• 详细日志记录帮助快速排查错误与性能瓶颈

灵活的协议与模型支持

• 同时兼容 Gemini 和 OpenAI 格式的 CHAT、画图及 embeddings 接口
• 支持 IMAGE_MODELS、SEARCH_MODELS 等配置，分别用于图文对话、联网搜索和修图功能

• 可过滤不常用模型，自动从 API 获取最新模型列表

新增与优化功能

• countTokens API 支持：在发送前预估 token 数量
• 智能 thinkingConfig 处理：当 thinkingBudget 为 0 时自动省略该配置
• 反向代理与本地开发指南：包含 nginx、SSL 证书、hosts 配置等
• 管理脚本：支持一键切换代理、更新端口与完整移除

技术实现与兼容性

栈与架构

• Python + FastAPI：利用异步特性高效处理并发请求，性能优于传统同步框架。
• Nginx + SSL/mkcert：官方示例脚本一键生成本地证书，快速配置 HTTPS 反向代理。

容器化部署

• 官方镜像适配 AMD 与 ARM 架构，docker pull ghcr.io/snailyp/gemini-balance:latest即可落地生产环境；也可自行构建镜像定制插件。

网络与代理支持

• 可为每个请求单独指定 HTTP/SOCKS5 代理；亦支持将 Gemini 官方或自建 Cloudflare Worker 代理作为上游端点，灵活适配不同网络场景。

快速上手

配置环境变量：在 .env中写入 API_KEYS="key1,key2"，按需填写 PROXIES与 FILTERED_MODELS。

启动服务：本地执行 python main.py或使用 docker compose up -d。

调用接口：

# OpenAI 格式 curl http://localhost:8000/v1/chat/completions -H "Authorization: Bearer sk-..."

# Gemini 格式 curl http://localhost:8000/gemini/v1beta/models/gemini-pro:generateContent

两种协议均支持图文对话、联网搜索与自定义模型过滤。

Gemini Balance适用场景

• 个人或团队需要统一管理多把 Gemini Key，提升调用上限。
• AI 应用希望无缝迁移自 OpenAI，兼顾 Gemini 最新多模态能力。
• 对安全合规、可观测性与高可用性有硬性要求的生产部署。

借助 Gemini Balance，你可以在最短时间内获得稳定、易扩展且对开发者友好的 Gemini 代理服务，为应用接入最新多模态模型扫清障碍。

Gemini Balance 项目地址

官网地址：https://gb-docs.snaily.top/

GitHub：https://github.com/yulin0629/gemini-balance