Gemini Balance：实现多 API Key 负载均衡与高效代理管理

Gemini Balance 是一款基于 Python 与 FastAPI 构建的高性能 API 代理与负载均衡器。它通过整合多 Key 轮询、权限过滤及健康监控机制，并提供对 OpenAI 接口格式的向下兼容，帮助开发者快速搭建一个高可用、可扩展的 Gemini 服务栈。

项目核心能力

Gemini Balance 旨在解决单 API Key 容易触发速率限制（Rate Limit）的痛点，通过在同一实例中管理多组 Key 并采用轮询算法分摊流量，显著提升并发处理能力。

1. 智能负载均衡与容灾

• 多 Key 轮询 ：自动按顺序调度多个 Gemini API Key，均衡请求压力。
• 故障自愈 ：支持配置最大重试次数，失效 Key 将被自动禁用，并通过定时检测机制尝试恢复。

2. 全方位状态监控

• 可视化面板 ：通过认证访问 /keys_status 页面，实时掌控各 Key 的健康指标与使用频率。
• 可观测性 ：内置详细日志记录，便于快速定位性能瓶颈或接口错误。

3. 灵活的协议适配

• 双格式兼容 ：同时支持 Gemini 原生接口与 OpenAI 格式的 Chat、画图及 Embeddings 接口。
• 精准模型分发 ：支持 IMAGE_MODELS 和 SEARCH_MODELS 配置，分别对应图文对话、联网搜索与修图功能。
• 动态模型管理 ：可自动获取最新模型列表，并支持过滤不常用模型。

最新升级要点

• Token 预估 ：新增 countTokens API 支持，允许在发送请求前预估 Token 消耗。
• 思考配置优化 ：智能处理 thinkingConfig，当 thinkingBudget 为 0 时自动省略该配置。
• 部署指南增强 ：提供完整的反向代理与本地开发手册，涵盖 Nginx、SSL 证书及 Hosts 配置。
• 便捷管理 ：引入管理脚本，支持一键切换代理、更新端口及完整卸载。

技术架构与部署

技术栈

• 后端 ：采用 FastAPI 的异步特性，确保高并发场景下的低延迟。
• 安全 ：配合 Nginx + SSL/mkcert，可通过官方脚本快速实现 HTTPS 加密传输。
• 容器化 ：提供适配 AMD 与 ARM 架构的 Docker 镜像，通过 docker pull ghcr.io/snailyp/gemini-balance:latest 即可快速部署。

网络适配

支持为单个请求指定 HTTP/SOCKS5 代理，并允许将 Gemini 官方端点或自建的 Cloudflare Worker 代理作为上游，灵活应对不同网络环境。

快速上手指南

1. 配置环境 ：在 .env 文件中定义 API_KEYS="key1,key2"，并根据需求配置 PROXIES 和 FILTERED_MODELS。
2. 启动服务 ：运行 python main.py 或使用 docker compose up -d 启动。
3. 接口调用 ：

   # 使用 OpenAI 格式调用
   curl http://localhost:8000/v1/chat/completions -H "Authorization: Bearer sk-..."  
   
   # 使用 Gemini 格式调用
   curl http://localhost:8000/gemini/v1beta/models/gemini-pro:generateContent

适用场景

• 突破限额 ：个人或团队需要统一管理多个 Key 以提升 API 调用配额。
• 无缝迁移 ：希望在保留 OpenAI 接口习惯的同时，接入 Gemini 的多模态能力。
• 生产环境 ：对 API 调用的可观测性、安全合规性及高可用性有明确要求。

项目资源

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

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