← 返回 Blog
UseAIAPIAI API3min

用 gemini-balance 把 N 个免费Key拼成"无限池"：完整Docker部署 + OpenAI兼容接入 Cline/Cursor/OpenWebUI，本地跑零依赖

在使用 Gemini API 免费层的过程中，很多开发者都会遇到一个共同的痛点：单账号的严格限速机制。Flash-Lite 模型最高仅支持 15 次 / 分钟的请求数，每日总调用量在 250 至 1000 次之间，而真正限制吞吐量的往往不是每日请求数（RPD），而是每分钟 25 万 Token 的吞吐量限制（TPM）。不少开发者都有过这样的经历：脚本刚运行不久就频繁遭遇 429 资源耗尽错误，即使每日配额还有大量剩余，也无法继续发起请求。

GeminiGemini 免费额度

Gemini 免费额度多账号负载均衡方案 三步搭建近乎无限的 API 调用池

在使用 Gemini API 免费层的过程中，很多开发者都会遇到一个共同的痛点：单账号的严格限速机制。Flash-Lite 模型最高仅支持 15 次 / 分钟的请求数，每日总调用量在 250 至 1000 次之间，而真正限制吞吐量的往往不是每日请求数（RPD），而是每分钟 25 万 Token 的吞吐量限制（TPM）。不少开发者都有过这样的经历：脚本刚运行不久就频繁遭遇 429 资源耗尽错误，即使每日配额还有大量剩余，也无法继续发起请求。

为了解决这个问题，有开发者利用开源工具 gemini-balance，将多个免费 Gemini API Key 整合成一个统一的负载均衡池，实现了近乎无限的免费调用能力，彻底告别了限速焦虑。

单账号限速的本质：配额按项目共享而非按 Key 共享

Gemini 的免费额度其实比很多人印象中更为慷慨。每个 Google 账号都可以在 AI Studio（aistudio.google.com）免费申请一个 API Key，每天可获得约 250 至 1000 次调用权限，所有免费模型共享每分钟 25 万 Token 的 TPM 上限。但在实际使用中，这个额度往往显得捉襟见肘。

一次携带长上下文的请求可能会消耗 20 万 Token，直接占用半分钟的 TPM 额度，导致后续任何请求都会触发 429 错误。更关键的是，官方文档明确规定：Gemini 的限速是按 Google Cloud Project 计算的，而非按 API Key 计算。这意味着，同一个项目下创建的 10 个 API Key 会共享同一个配额池，只要其中一个 Key 被限流，其他九个也会同时失效。

解决这个问题的思路非常直接：使用多个独立的 Google 账号，每个账号创建一个独立的 Project 并生成一个 API Key，然后通过负载均衡机制让这些 Key 自动轮询和切换。这样就能将每日总调用上限从几百次提升到几千甚至上万次。

手工切换 Key 不仅效率低下，还会中断正在运行的任务。而开源工具 gemini-balance 完美解决了这个痛点。它是一个基于 Python FastAPI 开发的轻量级代理和负载均衡器，专门用于管理 Gemini 多 Key 池。其核心工作流程是：接收上游请求→从可用 Key 池中选择一个健康的 Key 分发请求→当某个 Key 用尽配额或返回 429 错误时自动跳过→定期检查并复活冷却后的 Key，整个过程对上层应用完全透明。

核心优势：内置协议转换 兼容所有 OpenAI 生态工具

gemini-balance 最具价值的设计是内置了协议转换层。目前绝大多数 AI 编程工具（如 Cline、Continue、Cursor 等）都只支持 OpenAI 格式的 API 接口，而 Gemini 的原生协议在路径、消息结构和流式响应格式上与 OpenAI 存在差异。

gemini-balance 能够自动将 Gemini 的请求和响应格式转换为标准的 OpenAI Chat Completions 格式。这意味着，你不需要修改任何上游工具的代码，只需将工具的 API 地址指向 gemini-balance 的服务端点，就能像使用 OpenAI API 一样使用 Gemini 服务。

gemini-balance 提供了两个主要的调用端点：

  • OpenAI 兼容模式端点：http://你的服务地址:8000/v1 或 http://你的服务地址:8000/hf/v1，适用于 Cline、Cursor、Cherry Studio 等所有支持 OpenAI 格式的工具
  • 原生 Gemini 转发端点：http://你的服务地址:8000/gemini/v1beta，适用于需要直接调用 Gemini 原生 API 的场景

三步搭建专属 Gemini 调用池 全程无需复杂配置

搭建 gemini-balance 服务非常简单，只需具备 Docker 或 Docker Compose 环境即可。如果没有本地服务器，也可以部署在 ClawCloud Run 等云平台上，这些平台通常提供 5 美元左右的免费赠金额度，足够支撑个人使用。

第一步：准备环境配置文件

创建一个名为.env的配置文件，填入以下内容：

env

# .env 示例（最小可用版本，使用SQLite数据库无需额外配置）
DATABASE_TYPE=sqlite
SQLITE_DATABASE=default_db

# 多个Gemini API Key（每个Key必须来自不同账号的不同Project）
API_KEYS=["AIzaSy...key1","AIzaSy...key2","AIzaSy...key3"]

# 访问代理服务时需要的认证令牌（相当于密码）
ALLOWED_TOKENS=["sk-my-token"]

# 管理后台登录密码
AUTH_TOKEN=admin-secret

# 设置时区为上海
TZ=Asia/Shanghai

第二步：使用 Docker Compose 一键启动服务

创建一个名为docker-compose.yml的文件，内容如下：

yaml

services:
  gemini-balance:
    image: ghcr.io/snailyp/gemini-balance:latest
    container_name: gemini-balance
    restart: unless-stopped
    ports:
      - "8000:8000"
    env_file:
      - .env

在终端中执行以下命令启动服务：

bash

运行

docker compose up -d

第三步：登录管理后台完成配置

打开浏览器访问http://localhost:8000，使用配置文件中AUTH_TOKEN的值登录管理后台。在后台中确认 Key 池中的所有 Key 状态正常，系统会自动开始进行轮询负载均衡。

配置完成后，你就获得了一个统一的调用入口：

  • Base URL：http://localhost:8000/v1
  • API Key：sk-my-token（即配置文件中ALLOWED_TOKENS的值）

无缝接入主流开发工具链

将 gemini-balance 接入你的开发工具非常简单，以下是两个最常用工具的配置方法：

Cline / Roo Code

  1. 安装扩展后，在 API Provider 中选择 "OpenAI Compatible"
  2. Base URL 填入http://localhost:8000/v1
  3. API Key 填入sk-my-token
  4. 运行两条测试请求，确认返回值正常即可使用

Cursor

  1. 打开 Settings→Models
  2. 开启 "Override OpenAI Base URL" 选项
  3. 填入http://localhost:8000/v1（注意结尾不要加斜杠，Cursor 会自动拼接路径）
  4. 点击 "Verify" 按钮，绿灯亮起后即可添加模型名称使用

成本与收益分析 以及必须遵守的使用红线

以 8 个独立 Google 账号为例，每个账号每天约有 250 次免费调用额度，通过 gemini-balance 轮询后，理论上每日可支持约 2000 次调用。按照 Gemini 官方 API 定价计算，这些调用量每天价值几十到上百美元，而整个方案的持续运行成本几乎为零 —— 本地部署仅消耗少量电费，云端部署则可以利用云平台的免费赠金额度。

更重要的是，彻底解决 429 问题后，CI/CD 流水线可以在半夜自动运行多轮回归测试，无需人工干预重启脚本。gemini-balance 会自动处理 Key 切换、失败重试和冷却复活等所有问题。

不过，在使用这个方案时，必须严格遵守以下三条红线，避免不必要的风险：

  1. 多 Key 线性放大并非绝对：Google 会检测同 IP 和同设备指纹的异常请求，少数账号在同一网络下疯狂叠加 Key 可能会被关联限速。有社区用户反馈，使用 Cloudflare AI Gateway 分散出口流量可以有效缓解这个问题。
  2. 注意免费层的数据条款：Google 对免费服务的条款明确规定，用户上传的内容可能会被用于产品改进，且可能有工作人员参与处理。因此，绝对不要通过免费池传输真实用户数据、客户文件或敏感商业信息，这类场景应直接使用付费服务。
  3. 遵守开源协议：gemini-balance 采用 CC BY-NC 4.0 协议开源，禁止任何形式的商业倒卖服务，不得将其包装成付费产品出售给他人。

结语

这套多账号负载均衡方案并不神奇，本质上是将多个独立 Project 的额度整合为一个统一的、自动管理的入口。它无法替代官方付费服务在稳定性、SLA 保障和技术支持方面的优势，但对于预算有限、需要持续运行非敏感 AI 任务的个人开发者和学生来说，无疑是一个极具性价比的选择。

对于有大规模生产需求或需要处理敏感数据的企业而言，免费方案的局限性十分明显。此时，选择一个稳定可靠、安全合规的专业 API 服务平台更为合适。UseAIAPI 作为专业的全球 AI 大模型 API 服务提供商，整合了 Gemini、Claude、ChatGPT、DeepSeek 等全球主流最新 AI 大模型，提供稳定高效的接入服务和企业级定制化解决方案。特别值得一提的是，平台目前推出了力度空前的优惠活动，所有 API 服务价格最低可达官方定价的 50%，能够帮助企业大幅降低 AI 使用成本，同时避免因使用非正规渠道服务带来的数据安全风险。