Gemini Balance：轻松实现Gemini API负载均衡与无缝切换的终极指南

CodeDevMaster2025-08-18 14:27

Gemini Balance

概述

gemini-balance是一个基于Python FastAPI构建的开源代理服务，专门为Google Gemini API提供代理和负载均衡功能。 它的核心价值在于，允许通过简单的配置来管理多个Gemini API密钥，并实现密钥轮询、故障自动切换、统一认证和状态监控等高级功能。 更出色的是，它还集成了对OpenAI API格式的兼容、图像生成以及多种图床上传等实用功能，极大地提升了开发灵活性。

核心功能

gemini-balance提供了以下几大核心功能：

1.多密钥负载均衡

可以在配置中添加多个Gemini API密钥。gemini-balance会自动对这些密钥进行轮询调用，有效分散请求压力，提高并发处理能力和服务的整体可用性。

2.可视化配置与热加载

项目内置了一个管理后台，可以在网页上直观地修改配置。所有更改都能立即生效，无需重启服务，极大地简化了运维流程。

3.双协议API兼容

gemini-balance 同时支持原生Gemini API和OpenAI API的请求格式。这意味着，可以将现有使用OpenAI API 开发的应用程序无缝迁移，只需将API的base_url指向gemini-balance服务即可。

4.强大的扩展功能

项目不仅支持图文对话和图像修改，还支持网页搜索功能，让AI应用更加全能。

5.健康状态监控

当某个API密钥连续多次请求失败后，系统会自动禁用该密钥，并在一定时间后尝试恢复，确保了服务的健壮性。还可以通过专门的页面实时查看每个密钥的状态。

快速上手

gemini-balance 提供了多种部署方式，其中使用Docker是官方推荐的最便捷方式。

使用Docker部署（推荐）

这种方式无需在本地配置复杂的Python环境，是生产环境和快速体验的首选。

1.克隆项目

首先，将 gemini-balance 的代码库克隆到本地或服务器上

bash 复制代码 
https://github.com/snailyp/gemini-balance

cd gemini-balance

2.配置环境变量

项目通过一个名为 .env 的文件来管理配置，具体参考官方环境变量说明。

复制项目中的.env.example文件并进行修改。

bash 复制代码 
cp .env.example .env

使用文本编辑器打开 .env文件，填入相应的配置。以下是几个核心配置项：

bash 复制代码 
# Google Gemini API密钥列表，用逗号分隔
API_KEYS=["",""]
# 访问此代理服务所需的认证令牌，同样用逗号分隔
ALLOWED_TOKENS=[""]
# 数据库类型，支持sqlite和mysql。默认为sqlite，对于简单部署已足够
DATABASE_TYPE=sqlite
# 可选参数,超级管理员token，具有所有权限，不填默认使用ALLOWED_TOKENS的第一个
AUTH_TOKEN="Password"
# 时区
TZ=Asia/Shanghai

3.拉取并运行Docker镜像

可以直接从ghcr.io拉取官方构建好的镜像来运行。

bash 复制代码 
docker run -d -p 8000:8000 --name gemini-balance --env-file .env -v $(pwd)/data:/app/data ghcr.io/snailyp/gemini-balance:latest

命令解析：

bash 复制代码 
-d: 后台运行容器

-p 8000:8000: 将容器的 8000 端口映射到主机的8000端口

--name gemini-balance: 为容器命名

--env-file .env: 加载刚刚配置的.env 文件

-v $(pwd)/data:/app/data: 将本地的 data 目录挂载到容器内，用于持久化存储 SQLite 数据库等数据

 ghcr.io/snailyp/gemini-balance:latest: 指定要运行的镜像

4.访问应用程序

应用程序启动后，通过浏览器访问http://localhost:8000管理控制台

认证方式:

  • 1.优先使用AUTH_TOKEN值来登录

  • 2.其次使用ALLOWED_TOKENS中的第一个值登录

使用Docker Compose部署

对于需要同时管理数据库等多个服务的场景，docker-compose是更优雅的选择。项目根目录已提供 docker-compose.yml文件。

1.配置环境变量

项目通过一个名为 .env 的文件来管理配置，具体参考官方环境变量说明。

复制项目中的.env.example文件并进行修改。

bash 复制代码 
cp .env.example .env

使用文本编辑器打开 .env文件，复制.env.example文件前10行左右内容即可完成Docker Compose部署基本配置

bash 复制代码 
# 数据库配置
DATABASE_TYPE=mysql
# 数据库地址，默认指向docker-compose文件的MySQL容器名称
MYSQL_HOST=gemini-balance-mysql
# 数据库端口
MYSQL_PORT=3306
# 数据库用户名
MYSQL_USER=gemini
# 数据库密码
MYSQL_PASSWORD=change_me
# 数据库名称
MYSQL_DATABASE=default_db
# API 密钥列表
API_KEYS=["AIzaSyxxxxxxxxxxxxxxxxxxx","AIzaSyxxxxxxxxxxxxxxxxxxx"]
# 允许访问的Token列表
ALLOWED_TOKENS=["sk-123456"]
# 可选参数,超级管理员token，具有所有权限，不填默认使用ALLOWED_TOKENS的第一个
AUTH_TOKEN="Password"
# 时区
TZ=Asia/Shanghai

2.启动服务

默认情况下，docker-compose会读取 .env文件中的配置，并启动gemini-balance服务以及一个 MySQL数据库服务。

只需执行以下命令即可一键启动所有服务

bash 复制代码 
docker-compose up -d

本地运行（适合开发测试）

如果希望在本地进行开发或调试，可以按照以下步骤操作：

1.安装Python 3.9或更高版本

2.克隆项目并进入目录

python 复制代码 
https://github.com/snailyp/gemini-balance

cd gemini-balance

3.安装项目依赖

bash 复制代码 
pip install -r requirements.txt

4.配置 .env 文件

复制项目中的.env.example文件并进行修改。

bash 复制代码 
cp .env.example .env

使用文本编辑器打开 .env文件，填入相应的配置。以下是几个核心配置项：

bash 复制代码 
# Google Gemini API密钥列表，用逗号分隔
API_KEYS=["",""]
# 访问此代理服务所需的认证令牌，同样用逗号分隔
ALLOWED_TOKENS=[""]
# 数据库类型，支持sqlite和mysql。默认为sqlite，对于简单部署已足够
DATABASE_TYPE=sqlite
# 可选参数,超级管理员token，具有所有权限，不填默认使用ALLOWED_TOKENS的第一个
AUTH_TOKEN="Password"
# 时区
TZ=Asia/Shanghai

5.启动应用：

bash 复制代码 
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
python 复制代码 
app.main:app：指定FastAPI应用程序实例（模块内文件app中的对象）的位置。main.pyapp

--host 0.0.0.0：使应用程序可从本地网络上的任何 IP 地址访问

--port 8000：指定应用程序监听的端口号

--reload：启用自动重新加载。当修改代码时，服务会自动重启，非常适合开发环境

6.访问应用程序

应用程序启动后，通过浏览器访问http://localhost:8000或者API工具来访问

云部署

ClawCloud

指定应用名称、镜像信息、硬件配置、网络访问、域名等信息 参数如下：

bash 复制代码 
Application Name: geminibalance

Image： Public

Image Name：ghcr.io/snailyp/gemini-balance:latest

Fixed：固定硬件配置 Scaling: 动态伸缩硬件配置

Replicas：1个副本数量

CPU：0.5

Memory：256

Container Port：容器内部程序运行端口8000

Public Access: 允许外部网络访问

Custom Domain: 使用自定义域名

配置环境变量与磁盘存储

环境变量如下：

python 复制代码 
DATABASE_TYPE=sqlite
SQLITE_DATABASE=default_db
API_KEYS=["AIzaS123456"]
ALLOWED_TOKENS=["sk-123456"]
AUTH_TOKEN=
TZ=Asia/Shanghai

也可以使用MySQL数据库

python 复制代码 
DATABASE_TYPE=mysql
MYSQL_HOST=
MYSQL_PORT=
MYSQL_USER=
MYSQL_PASSWORD=
MYSQL_DATABASE=

AI绘画配置

配置

进入Gemini Balance控制台，在配置编辑->图像生成菜单栏下配置图像生成模型与图床信息

这里使用gemini-2.0-flash-preview-image-generation图像生成模型与基于Cloudflare搭建的图床

使用测试

这里使用Cherry Studio接入Gemini Balance，同时使用它进行对话、图像生成等操作。

使用提示词：一只可爱的老鼠驾驶着一架炫酷的战斗机生成如下图像：

配置参数说明

数据库配置

配置项 描述 默认值
DATABASE_TYPE 可选，数据库类型，支持mysql或sqlite mysql
SQLITE_DATABASE 可选，使用sqlite时必填，SQLite 数据库文件路径 default_db
MYSQL_HOST 使用mysql时必填，MySQL 数据库主机地址 localhost
MYSQL_SOCKET 可选，MySQL数据库套接字地址 /var/run/mysqld/mysqld.sock
MYSQL_PORT 使用mysql时必需，MySQL 数据库端口 3306
MYSQL_USER 使用mysql时必填，MySQL 数据库用户名 your_db_user
MYSQL_PASSWORD 使用mysql时必填，MySQL 数据库密码 your_db_password
MYSQL_DATABASE 使用mysql时必填，MySQL 数据库名称 defaultdb

API相关配置

配置项 描述 默认值
API_KEYS 必填，用于负载平衡的 Gemini API 密钥列表 ["your-gemini-api-key-1", "your-gemini-api-key-2"]
ALLOWED_TOKENS 必填，允许访问的token列表 ["your-access-token-1", "your-access-token-2"]
AUTH_TOKEN 可选，具有所有权限的超级管理员令牌，若ALLOWED_TOKENS未设置则默认为第一个 sk-123456
TEST_MODEL 可选，用于测试密钥是否可用的模型名称 gemini-1.5-flash
IMAGE_MODELS 可选，支持绘图功能的机型列表 ["gemini-2.0-flash-exp"]
SEARCH_MODELS 可选，支持搜索功能的型号列表 ["gemini-2.0-flash-exp"]
FILTERED_MODELS 可选，禁用模型列表 ["gemini-1.0-pro-vision-latest", ...]
TOOLS_CODE_EXECUTION_ENABLED 可选，是否启用代码执行工具 false
SHOW_SEARCH_LINK 可选，是否在响应中显示搜索结果链接 true
SHOW_THINKING_PROCESS 可选，是否显示模型的思考过程 true
THINKING_MODELS 可选，支持思考功能的模型列表 []
THINKING_BUDGET_MAP 可选，思考函数预算映射（model_name：budget_value） {}
URL_NORMALIZATION_ENABLED 可选，是否启用智能URL路由映射 false
BASE_URL 可选，Gemini API 基础 URL，默认无需修改 https://generativelanguage.googleapis.com/v1beta
MAX_FAILURES 可选，允许单个密钥失败的次数 3
MAX_RETRIES 可选，失败 API 请求的最大重试次数 3
CHECK_INTERVAL_HOURS 可选，检查禁用密钥是否已恢复的时间间隔（小时） 1
TIMEZONE 可选，应用程序使用的时区 Asia/Shanghai
TIME_OUT 可选，请求超时（秒） 300
PROXIES 可选，代理服务器列表（例如 http://user:pass@host:port，socks5://host:port） []
LOG_LEVEL 可选，日志级别，例如 DEBUG, INFO, WARNING, ERROR, CRITICAL INFO
AUTO_DELETE_ERROR_LOGS_ENABLED 可选，是否启用自动删除错误日志 true
AUTO_DELETE_ERROR_LOGS_DAYS 可选，自动删除超过此天数的错误日志（例如 1, 7, 30） 7
AUTO_DELETE_REQUEST_LOGS_ENABLED 可选，是否启用自动删除请求日志 false
AUTO_DELETE_REQUEST_LOGS_DAYS 可选，自动删除超过此天数的请求日志（例如 1, 7, 30） 30
SAFETY_SETTINGS 可选，安全设置（JSON 字符串格式），用于配置内容安全阈值。 [{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "OFF"}, ...]

TTS相关

配置项 描述 默认值
TTS_MODEL 可选，TTS 模型名称 gemini-2.5-flash-preview-tts
TTS_VOICE_NAME 可选，TTS语音名称 Zephyr
TTS_SPEED 可选，TTS 速度 normal

图像生成相关

配置项 描述 默认值
PAID_KEY 可选的付费 API 密钥，用于图像生成等高级功能 your-paid-api-key
CREATE_IMAGE_MODEL 可选，图像生成模型 imagen-3.0-generate-002
UPLOAD_PROVIDER 可选，图片上传提供商：smms，picgo，cloudflare_imgbed smms
SMMS_SECRET_TOKEN 可选，用于 SM.MS 图像托管的 API 令牌 your-smms-token
PICGO_API_KEY 可选，PicoGo 图像托管的 API 密钥 your-picogo-apikey
CLOUDFLARE_IMGBED_URL 可选，CloudFlare图片托管上传地址 https://xxxxxxx.pages.dev/upload
CLOUDFLARE_IMGBED_AUTH_CODE 可选，CloudFlare 图像托管的身份验证密钥 your-cloudflare-imgber-auth-code
CLOUDFLARE_IMGBED_UPLOAD_FOLDER 可选，CloudFlare图片托管的上传文件夹路径 ""

流优化器相关

配置项 描述 默认值
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

虚假流相关

配置项 描述 默认值
FAKE_STREAM_ENABLED 可选，是否为不支持流式传输的模型或场景启用虚假流式传输 false
FAKE_STREAM_EMPTY_DATA_INTERVAL_SECONDS 可选，在伪流期间发送心跳空数据的间隔（秒） 5

API端点

Gemini API相关

Base Path: /gemini/v1beta

Method Endpoint Path 描述
GET /models 列出可用的 Gemini 型号。
POST /models/{model_name}:generateContent 使用指定的 Gemini 模型生成内容。
POST /models/{model_name}:streamGenerateContent 使用指定的 Gemini 模型生成流内容。

OpenAI API相关

为了兼容不同的客户端，服务提供了两种OpenAI格式的端点。

HF兼容接口 (底层使用Gemini格式)

Base Path: /hf/v1

Method Endpoint Path 描述
GET /models 列出可用的模型。
POST /chat/completions 执行聊天补全（支持流式传输）。
POST /embeddings 创建文本嵌入。
POST /images/generations 生成图像。

OpenAI原生格式接口

Base Path: /openai/v1

Method Endpoint Path 描述
GET /models 列出可用的模型。
POST /chat/completions 执行聊天补全（支持流式传输，可防止截断，速度更快）。
POST /embeddings 创建文本嵌入。
POST /images/generations 生成图像。
相关推荐
Xi_Xu2 天前
Xget：为您的开发工作流解锁极致速度
javascript·api
电商API大数据接口开发Cris3 天前
基于 Flink 的淘宝实时数据管道设计：商品详情流式处理与异构存储
前端·数据挖掘·api
扶风呀3 天前
具有熔断能力和活性探测的服务负载均衡解决方案
运维·负载均衡
Hello World呀3 天前
springcloud负载均衡测试类
spring·spring cloud·负载均衡
一个专注api接口开发的小白4 天前
Python/Node.js 调用taobao API：构建实时商品详情数据采集服务
前端·数据挖掘·api
菜菜子爱学习4 天前
Nginx学习笔记（七）——Nginx负载均衡
笔记·学习·nginx·负载均衡·运维开发
扶风呀4 天前
负载均衡详解
运维·后端·微服务·面试·负载均衡
PXM的算法星球4 天前
spring gateway配合nacos实现负载均衡
spring·gateway·负载均衡
onelafite5 天前
一键式商品信息获取：京东API返回值深度挖掘
api·fastapi
热门推荐
01UV安装并设置国内源02Qwen3-Coder 快速上手教程 | Qwen Code + Claude Code03【2025.08.06最新版】Android Studio下载、安装及配置记录（自动下载sdk）04KGG转MP3工具|非KGM文件|解密音频052025最新国内服务器可用docker源仓库地址大全（2025年8月更新）06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接07TRAE 规则（Rules）配置指南：个人习惯、团队规范与最佳实践08NVIDIA显卡驱动、CUDA、cuDNN 和 TensorRT 版本匹配指南09阿里开源首个图像生成基础模型——Qwen-Image本地部署教程，超强中文渲染能力刷新SOTA！10TRAE Rules 实践：为项目配置 6A 工作流