写在前面

自 Google 发布其强大的大型语言模型 Gemini 以来，全球的开发者都渴望将其集成到自己的应用中。Gemini API 凭借其出色的多模态能力和慷慨的免费额度，每个API每天可以提供100次Gemini 2.5 Pro 这样的顶级大模型的调用。对于简单的对话而言，这样的免费额度已经足够使用，但在更深入的实际应用中，我们常常会遇到一些棘手的问题：

  • 单一 API Key 的速率限制：免费的 Gemini API Key 有每分钟请求次数（RPM）的限制，一旦流量稍大，应用就可能陷入瘫痪。

  • 多 Key 管理的复杂性：为了绕过限制，我们可能会注册多个 Key，但在代码中手动管理和轮询这些 Key 非常繁琐且容易出错。

  • 生态工具的兼容性：许多优秀的 LLM 应用和客户端（如各种桌面客户端、VSCode 插件等）都是围绕 OpenAI 的 API 格式设计的，无法直接使用 Gemini API。

  • 网络环境的挑战：在某些网络环境下，直接访问 Google API 可能会遇到困难。

而开源项目snailyp/gemini-balance​能够轻松解决以上痛点，它是一个为 Gemini API 设计的轮询代理和负载均衡服务，它的核心使命是简化 Gemini API 的使用，让开发者能够像使用一个“超级API”一样，轻松、高效、稳定地调用 Gemini 的强大能力。

核心优势

1. 多 API Key 管理与负载均衡

这是项目的核心功能，它能够为你创建一个 API Key 池。当收到请求时，它会采用轮询策略，依次使用池中的 Key 来处理请求。

  • 突破速率限制

  • 提高可用性

2. 无缝兼容 OpenAI API 格式

它可以将标准的 OpenAI Chat API 请求格式实时转换为 Gemini API 所需的格式，并将 Gemini 的响应再转换回 OpenAI 的格式。

能够完美兼容以下核心 OpenAI API 端点：

  • ​POST /v1/chat/completions​：核心的聊天接口。

  • ​POST /v1/embeddings​：文本嵌入接口，你可以用 Gemini 的模型来生成向量。

  • ​POST /v1/images/generations​：图像生成接口，它巧妙地将 Gemini 的图像模型适配成了 OpenAI 的调用方式。

3. 强大的功能扩展

​gemini-balance​ 不仅仅是一个代理，它还解锁了 Gemini 的许多高级功能。

  • 图文聊天与修改：通过在配置中指定支持图像的模型（如 gemini-pro-vision​），你可以轻松构建能够理解和处理图片的多模态应用。

  • 网页搜索：通过配置 SEARCH_MODELS​，你可以让 Gemini 模型拥有联网搜索的能力，从而回答关于最新事件的问题，获取实时信息。

4. 自动化、安全与监控

  • 自动模型列表：你无需手动跟踪 Gemini 发布了哪些新模型，服务会自动从 Google 获取并同步最新的可用模型列表。

  • 代理支持：如果你处于特殊的网络环境中，可以通过配置 PROXIES​ 环境变量，让 gemini-balance​ 通过 HTTP 或 SOCKS5 代理来访问 Google 服务器。

  • 访问认证：你可以通过设置 AUTH_KEYS​ 环境变量，为你的代理服务设置一个或多个访问密码，防止其被未授权的用户滥用。

  • 状态监控：项目提供了一个接口，可以让你实时查看每个 API Key 的当前状态，方便排查问题。

实战指南

得益于 Docker，部署 gemini-balance​ 变得异常简单。在本次部署中，为了应对简单的生产环境，我们不使用资源占用过高的MySQL作为数据库服务，而是使用更加轻量便捷的SQ Lite。

步骤 1: 创建配置文件

首先，创建一个文件夹，并在其中创建两个文件：docker-compose.yml​ 和 .env​。

​docker-compose.yml​

version: '3.8'

volumes:
  sqlite_data:

services:
  gemini-balance:
    image: ghcr.io/snailyp/gemini-balance:latest
    container_name: gemini-balance
    restart: unless-stopped
    ports:
      - "8000:8000"
    env_file:
      - .env
    environment:
      - DATABASE_TYPE=sqlite
      - SQLITE_DATABASE=/app/data/default_db
    volumes:
      - sqlite_data:/app/data
    healthcheck:
      test: ["CMD-SHELL", "python -c \"import requests; exit(0) if requests.get('http://localhost:8000/health').status_code == 200 else exit(1)\""]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

​.env​

这是你的核心配置文件。从项目官网的 .env.example 复制内容并进行修改。

# 数据库配置
DATABASE_TYPE=sqlite
#SQLITE_DATABASE=default_db
#MYSQL_HOST=gemini-balance-mysql
#MYSQL_SOCKET=/run/mysqld/mysqld.sock
#MYSQL_PORT=3306
#MYSQL_USER=gemini
#MYSQL_PASSWORD=change_me
#MYSQL_DATABASE=default_db
API_KEYS=["YOUR_API_KEY_1","YOUR_API_KEY_2"]
ALLOWED_TOKENS=["sk-123456"]
AUTH_TOKEN=sk-123456
# For Vertex AI Platform API Keys
VERTEX_API_KEYS=["AQ.Abxxxxxxxxxxxxxxxxxxx"]
# For Vertex AI Platform Express API Base URL
VERTEX_EXPRESS_BASE_URL=https://aiplatform.googleapis.com/v1beta1/publishers/google
TEST_MODEL=gemini-1.5-flash
THINKING_MODELS=["gemini-2.5-flash-preview-04-17"]
THINKING_BUDGET_MAP={"gemini-2.5-flash-preview-04-17": 4000}
IMAGE_MODELS=["gemini-2.0-flash-exp"]
SEARCH_MODELS=["gemini-2.0-flash-exp","gemini-2.0-pro-exp"]
FILTERED_MODELS=["gemini-1.0-pro-vision-latest", "gemini-pro-vision", "chat-bison-001", "text-bison-001", "embedding-gecko-001"]
# 是否启用网址上下文，默认启用
URL_CONTEXT_ENABLED=false
URL_CONTEXT_MODELS=["gemini-2.5-pro","gemini-2.5-flash","gemini-2.5-flash-lite","gemini-2.0-flash","gemini-2.0-flash-live-001"]
TOOLS_CODE_EXECUTION_ENABLED=false
SHOW_SEARCH_LINK=true
SHOW_THINKING_PROCESS=true
BASE_URL=https://generativelanguage.googleapis.com/v1beta
MAX_FAILURES=10
MAX_RETRIES=3
CHECK_INTERVAL_HOURS=1
TIMEZONE=Asia/Shanghai
# 请求超时时间（秒）
TIME_OUT=300
# 代理服务器配置 (支持 http 和 socks5)
# 示例: PROXIES=["http://user:pass@host:port", "socks5://host:port"]
PROXIES=[]
# 对同一个API_KEY使用代理列表中固定的IP策略
PROXIES_USE_CONSISTENCY_HASH_BY_API_KEY=true
#########################image_generate 相关配置###########################
PAID_KEY=AIzaSyxxxxxxxxxxxxxxxxxxx
CREATE_IMAGE_MODEL=imagen-3.0-generate-002
UPLOAD_PROVIDER=smms
SMMS_SECRET_TOKEN=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
PICGO_API_KEY=xxxx
CLOUDFLARE_IMGBED_URL=https://xxxxxxx.pages.dev/upload
CLOUDFLARE_IMGBED_AUTH_CODE=xxxxxxxxx
CLOUDFLARE_IMGBED_UPLOAD_FOLDER=
##########################################################################
#########################stream_optimizer 相关配置########################
STREAM_OPTIMIZER_ENABLED=false
STREAM_MIN_DELAY=0.016
STREAM_MAX_DELAY=0.024
STREAM_SHORT_TEXT_THRESHOLD=10
STREAM_LONG_TEXT_THRESHOLD=50
STREAM_CHUNK_SIZE=5
##########################################################################
######################### 日志配置 #######################################
# 日志级别 (debug, info, warning, error, critical)，默认为 info
LOG_LEVEL=info
# 是否开启自动删除错误日志
AUTO_DELETE_ERROR_LOGS_ENABLED=true
# 自动删除多少天前的错误日志 (1, 7, 30)
AUTO_DELETE_ERROR_LOGS_DAYS=7
# 是否开启自动删除请求日志
AUTO_DELETE_REQUEST_LOGS_ENABLED=false
# 自动删除多少天前的请求日志 (1, 7, 30)
AUTO_DELETE_REQUEST_LOGS_DAYS=30
##########################################################################

# 假流式配置 (Fake Streaming Configuration)
# 是否启用假流式输出
FAKE_STREAM_ENABLED=True
# 假流式发送空数据的间隔时间（秒）
FAKE_STREAM_EMPTY_DATA_INTERVAL_SECONDS=5

# 安全设置 (JSON 字符串格式)
# 注意：这里的示例值可能需要根据实际模型支持情况调整
SAFETY_SETTINGS=[{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "OFF"}, {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "OFF"}, {"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "threshold": "OFF"}, {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "OFF"}, {"category": "HARM_CATEGORY_CIVIC_INTEGRITY", "threshold": "BLOCK_NONE"}]
URL_NORMALIZATION_ENABLED=false
# tts配置
TTS_MODEL=gemini-2.5-flash-preview-tts
TTS_VOICE_NAME=Zephyr
TTS_SPEED=normal
#########################Files API 相关配置########################
# 是否启用文件过期自动清理
FILES_CLEANUP_ENABLED=true
# 文件过期清理间隔（小时）
FILES_CLEANUP_INTERVAL_HOURS=1
# 是否启用用户文件隔离（每个用户只能看到自己上传的文件）
FILES_USER_ISOLATION_ENABLED=true
##########################################################################

重要：将 YOUR_API_KEY_1​, YOUR_API_KEY_2​ 等替换成你自己的真实 Gemini API Key。

步骤 2: 启动服务

在存放这两个文件的文件夹中，打开终端，运行以下命令：

docker-compose up -d

等待片刻，Docker 会自动拉取最新的镜像并启动服务。服务将运行在本地的 8000​ 端口上。

即刻开始

服务启动后，你就可以开始享受它带来的便利了。假设你的服务地址是 http://127.0.0.1:8000​。

API地址：http://127.0.0.1:8000​

API KEY：sk-123456​

总结

​snailyp/gemini-balance​ 是一个设计精巧、功能强大且极其实用的开源项目。它不仅解决了开发者在使用 Gemini API 时遇到的核心痛点——速率限制和多 Key 管理，更通过其卓越的 OpenAI API 兼容性，极大地拓宽了 Gemini 的应用场景。

它将复杂的负载均衡、格式转换和功能扩展等任务封装在一个简单的 Docker 容器中，让开发者可以专注于业务逻辑和应用创新。如果你正在使用或计划使用 Gemini API，我强烈推荐你花几分钟时间部署和体验一下 gemini-balance​。

去给这个优秀的项目一个 Star 吧，这绝对是你今年在 GitHub 上最值得的发现之一！

GitHub 仓库: https://github.com/snailyp/gemini-balance