Gemini Balance：全面指南与实践 —— Gemini API 代理与负载均衡最佳实践

TL;DR

Gemini Balance 是基于 Python FastAPI 打造的高可用 Gemini API 代理与负载均衡解决方案，支持多 Key 轮询、token 计数、图像生成、联网搜索及 OpenAI 兼容接口，提供可视化管理与实时监控，助力稳定、灵活地扩展 AI 服务。

目录

  1. 项目概述
  2. 核心功能与技术亮点
  3. 架构与模块分层
  4. 快速上手：Docker 与本地开发
  5. 配置项详解
  6. E‑E‑A‑T 加持：安全性与可维护性
  7. 常见场景与排错指南
  8. 关键词列表
  9. 参考文献

项目概述

Gemini Balance 致力于简化并强化对 Google Gemini API 的调用与管理。通过多 Key 轮询与负载均衡，解决单 Key 并发瓶颈；集成 token 计数接口，优化成本控制；并兼容 OpenAI 格式，轻松迁移或并行使用多种 LLM 服务。无论是小规模开发测试，还是生产级大规模部署，均可满足高可用、高性能需求。

核心功能与技术亮点

  • 多 Key 负载均衡：自动轮询多个 Gemini API Key，支持失败重试与 Key 健康检查，提升并发能力与容错率。
  • Token 统计接口：新增 /models/{model_name}:countTokens，可在发送请求前精准计算输入 token 数量，助力成本管控。
  • 双协议兼容：原生支持 Gemini 与 OpenAI API 格式，前端调用一套接口，后台智能转发与适配。
  • 图像生成与编辑：内置 IMAGE_MODELS 管理，可调用 Gemini 图文对话、修改图片功能，也可通过 OpenAI 画图接口扩展。
  • 联网搜索能力：指定 SEARCH_MODELS 即可启用实时联网检索，提升模型回答的时效性与准确度。
  • 可视化管理与监控：Web 控制面板无缝在线配置与生效，实时查看各 Key 状态、调用日志与性能指标。
  • 安全与稳定：支持 HTTPS（mkcert 证书）、Proxy 设置、防止 DNS 循环；在生产环境中可禁用本地绕过认证。
  • 完善的本地开发体验：提供 Docker 多架构镜像、详细 nginx 与 SSL 配置、快速启动 & 调试指南。

架构与模块分层

app/
├── config/       # 环境与运行时配置管理
├── core/         # FastAPI 应用实例与中间件
├── database/     # ORM 模型与连接
├── router/       # Gemini、OpenAI、状态页等路由
├── service/      # 聊天、Key 管理与统计服务
├── scheduler/    # 定时健康检查与恢复任务
├── utils/        # 日志、异常与工具函数
└── main.py       # 应用入口

每个模块职责清晰，方便定制与扩展，让团队能够快速定位功能、添加新特性或替换底层模型。

快速上手：Docker 与本地开发

1. Docker 部署（推荐）

  • 构建镜像

    docker build -t gemini-balance .

  • 运行容器

    docker run -d -p 8000:8000 --env-file .env \
  --dns 8.8.8.8 --dns 8.8.4.4 \
  gemini-balance
    • --dns 参数可避免反向代理导致的 DNS 循环；
    • 如使用 SQLite，请挂载数据卷 -v /host/data:/app/data。

2. 拉取现成镜像

docker pull ghcr.io/snailyp/gemini-balance:latest
docker run -d -p 8000:8000 --env-file .env \
  ghcr.io/snailyp/gemini-balance:latest

3. 本地开发调试

  1. git clone 并切换到项目根目录
  2. pip install -r requirements.txt
  3. uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

配置项详解

配置项 说明 示例
API_KEYS 多个 Gemini API Key，轮询使用 ["key1","key2"]
THINKING_BUDGET_MAP 特定模型的思考预算，0 则自动省略 thinkingConfig {"gemini-1.5":"0"}
FILTERED_MODELS 屏蔽不常用模型 ["gemini-1.0-pro-vision-latest"]
PROXIES HTTP/SOCKS5 代理列表 ["socks5://127.0.0.1:1080"]
STREAM_OPTIMIZER_ENABLED 流式输出优化 true

完整配置请参见项目根目录的 .env.example 或文档。

E‑E‑A‑T 加持：安全性与可维护性

  • Experience（经验）：社区活跃，多平台图床与反向代理案例积累；
  • Expertise（专业）：由资深 API 架构师设计，支持多协议与多模型集成；
  • Authoritativeness（权威）：开源仓库获数百星标，拥有详细排错与监控指南；
  • Trustworthiness（可信）：采用 CC BY‑NC 4.0 协议，杜绝商业倒卖，并提供安全最佳实践。

常见场景与排错指南

  1. Key 失效或请求超时：检查 /keys_status 页面，确认健康状况与失败次数。
  2. DNS 循环或代理无法连接：在 docker run 中添加 --dns 8.8.8.8，或配置 PROXIES。
  3. 思考配置报错：将对应模型的 thinkingBudget 设为 0，工具会自动省略相关字段。
  4. 模型列表不完整：确保 URL_NORMALIZATION_ENABLED=false，并定期调用 GET /models 同步最新列表。

关键词列表

  • Gemini Balance
  • Gemini API 代理
  • API 负载均衡
  • Token 计数接口
  • FastAPI Gemini
  • OpenAI 兼容
  • Docker 部署
  • 反向代理设置
  • 多 Key 轮询
  • 实时监控

参考文献

  1. snailyp/gemini-balance 原始仓库
  2. CC BY‑NC 4.0 许可证说明