Gemini Balance 部署与使用教程：
开源负载均衡工具详解
Gemini Balance 是一款强大的 Gemini API 代理工具，支持多 Key 轮询、OpenAI 协议兼容和即时监控。本文手把手教你如何部署和使用。
在开发 AI 应用时，直接使用 Gemini API 可能会遇到单 Key 限速、网络连接不稳或协议不兼容等问题。Gemini Balance 正是为了解决这些痛点而诞生的开源工具。
一、为什么选择 Gemini Balance？
Gemini Balance 基于 Python FastAPI 构建，是一个专为 Google Gemini API 设计的代理网关和负载均衡器。它的核心优势包括：
- 多 Key 负载均衡： 自动轮询多个 API Key，避免单 Key 被限流（429 错误），提高并发上限。
- OpenAI 协议兼容： 模拟 OpenAI API 格式，让你的现有代码（如使用 OpenAI SDK 的应用）无需修改即可无缝切换到 Gemini。
- 可视化监控： 提供 Web 后台，实时查看 Key 的状态、调用次数和错误日志。
- 智能故障处理： 自动重试失败请求，连续失败自动禁用异常 Key。
二、Docker 快速部署教程 (推荐)
对于大多数开发者，使用 Docker 是最简单、最干净的部署方式。
1. 准备工作
- 一台安装了 Docker 的服务器（推荐 Linux 或 macOS）。
- 若干个 Gemini API Key（可在 Google AI Studio 申请）。
2. 配置文件
创建一个名为 .env 的文件，填入以下内容：
.env
# Gemini API Keys (用逗号分隔)
api_keys=("key1","key2","key3")
# 你的访问密码 (类似 OpenAI 的 API Key，用于客户端连接)
allowed_tokens=("sk-mytoken123")
# 管理后台密码
auth_token="admin123"
# 数据库类型 (默认 sqlite)
database_type=sqlite
tz=Asia/Shanghai3. 启动容器
在终端运行以下命令：
docker run -d \
-p 8000:8000 \
--name gemini-balance \
--env-file .env \
-v $(pwd)/data:/app/data \
ghcr.io/snailyp/gemini-balance:latest部署完成后，访问 http://服务器IP:8000/keys_status 即可查看监控面板。
三、如何接入客户端？
部署成功后，你可以像使用 OpenAI API 一样使用它。
配置参数
| 参数 | 值 |
|---|---|
| Base URL | http://服务器IP:8000/v1 |
| API Key | sk-mytoken123 (你在 .env 中设置的 allowed_tokens) |
| Model | gemini-2.0-flash, gemini-1.5-pro 等 |
Python 示例代码
from openai import OpenAI
client = OpenAI(
api_key="sk-mytoken123",
base_url="http://localhost:8000/v1"
)
response = client.chat.completions.create(
model="gemini-2.0-flash",
messages=[{"role": "user", "content": "你好，Gemini！"}]
)
print(response.choices[0].message.content)四、不想折腾服务器？
虽然 Gemini Balance 很强大，但自建服务需要维护服务器、更新版本，还要担心 IP 被 Google 封禁。如果你希望开箱即用，可以考虑使用我们维护好的企业级中转服务。
相关阅读： API Key 申请攻略 API 额度与限制详解