GithubBackup/gemini-balance
1
0
Fork 0
mirror of https://github.com/snailyp/gemini-balance.git synced 2026-05-06 20:32:47 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: 更新文档、数据库配置和认证流程

Browse Source 
- 重构 README.md，更新项目描述、结构、配置说明和 API 端点信息。
- 在 .env.example 中添加 MySQL 数据库配置项。
- 将数据库连接池回收时间从 1 小时减少到 30 分钟 (app/database/connection.py)。
- 修复认证成功后的重定向 URL，从 /keys 指向 /config (app/router/routes.py)。
- 微调认证页面的背景透明度 (app/templates/auth.html)。
- 添加 cryptography 依赖以支持 MySQL 8+ 认证 (requirements.txt)。
- 添加示例图片文件 (files/image*.png)。
This commit is contained in:
snaily
2025-04-12 01:44:32 +08:00
parent f7cfc8952f
commit aea2f39952
15 changed files with 167 additions and 444 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.env.example
View File

@@ -1,3 +1,9 @@
# MySQL数据库配置
MYSQL_HOST=
MYSQL_PORT=
MYSQL_USER=
MYSQL_PASSWORD=
MYSQL_DATABASE=default_db
API_KEYS=["AIzaSyxxxxxxxxxxxxxxxxxxx","AIzaSyxxxxxxxxxxxxxxxxxxx"]
ALLOWED_TOKENS=["sk-123456"]
# AUTH_TOKEN=sk-123456

598
README.md
View File

@@ -1,208 +1,74 @@
# 🚀 Gemini 代理服务（支持openai/gemini格式）
# Gemini Balance - Gemini API 代理和负载均衡器
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-green.svg)](https://fastapi.tiangolo.com/)
[![Uvicorn](https://img.shields.io/badge/Uvicorn-running-purple.svg)](https://www.uvicorn.org/)
## 📝 项目简介
## 项目简介
本项目是一个基于 FastAPI 框架开发的高性能、易于部署的Gemini OpenAI兼容 和 Gemini API 代理服务。它不仅兼容 OpenAI 的 API 接口，还支持 Google 的 Gemini 原生接口。该代理服务内置了多 API Key 轮询、负载均衡、自动重试、访问控制（Bearer Token 认证）、流式响应等功能，旨在简化 AI 应用的开发和部署流程。
Gemini Balance 是一个基于 Python FastAPI 构建的应用程序，旨在提供 Google Gemini API 的代理和负载均衡功能。它允许您管理多个 Gemini API Key，并通过简单的配置实现 Key 的轮询、认证、模型过滤和状态监控。此外，项目还集成了图像生成和多种图床上传功能，并支持 OpenAI API 格式的代理。
**核心功能与优势:**
**项目结构:**
- **多协议支持**: 无缝切换 OpenAI兼容 和 Gemini 协议。
- **智能 API Key 管理**: 自动轮询多个 API Key，实现负载均衡和故障转移。
- **安全访问控制**: 使用 Bearer Token 进行身份验证，保护 API 访问。
- **流式响应支持**: 提供实时的流式数据传输，提升用户体验。
- **内置工具支持**: 支持代码执行和 Google 搜索等工具, 丰富模型功能 (可选)。
- **灵活配置**: 通过环境变量或 `.env` 文件轻松配置。
- **易于部署**: 提供 Docker 一键部署，也支持手动部署。
- **健康检查**: 提供健康检查接口，方便监控服务状态。
- **图片生成支持**: 支持使用OpenAI的DALL-E模型生成图片
```plaintext
app/
├── config/ # 配置管理
├── core/ # 核心应用逻辑 (FastAPI 实例创建, 中间件等)
├── database/ # 数据库模型和连接
├── domain/ # 业务领域对象 (可选)
├── exception/ # 自定义异常
├── handler/ # 请求处理器 (可选, 或在 router 中处理)
├── log/ # 日志配置
├── main.py # 应用入口
├── middleware/ # FastAPI 中间件
├── router/ # API 路由 (Gemini, OpenAI, 状态页等)
├── scheduler/ # 定时任务 (如 Key 状态检查)
├── service/ # 业务逻辑服务 (聊天, Key 管理, 统计等)
├── static/ # 静态文件 (CSS, JS)
├── templates/ # HTML 模板 (如 Key 状态页)
├── utils/ # 工具函数
```
## 🛠️ 技术栈
## ✨ 功能亮点
- **FastAPI**: 高性能 Web 框架。
- **Python 3.9+**: 编程语言。
- **Pydantic**: 数据验证和设置管理。
- **httpx**: 异步 HTTP 客户端。
- **uvicorn**: ASGI 服务器。
- **Docker**: 容器化部署 (可选)。
* **多 Key 负载均衡**: 支持配置多个 Gemini API Key (`API_KEYS`)，自动按顺序轮询使用，提高可用性和并发能力。
* **可视化配置即时生效**: 通过管理后台修改配置后，无需重启服务即可生效，切记要点击保存才会生效。
![配置面板](files/image4.png)
* **双协议API 兼容**: 同时支持 Gemini 和 OpenAI 格式的 CHAT API 请求转发。
```palintext
openai baseurl `http://localhost:8000(/hf)/v1`
gemini baseurl `http://localhost:8000(/gemini)/v1beta`
```
* **支持图文对话和修改图片**: `IMAGE_MODELS`配置哪个模型可以图文对话和修图的功能，实际调用的时候，用 `配置模型-image`这个模型名对话使用该功能。
![对话生图](files/image6.png)
![修改图片](files/image7.png)
* **支持联网搜索**: 支持联网搜索，`SEARCH_MODELS`配置哪些模型可以联网搜索，实际调用的时候，用 `配置模型-search`这个模型名对话使用该功能
![联网搜索](files/image8.png)
* **Key 状态监控**: 提供 `/keys_status` 页面（需要认证），实时查看各 Key 的状态和使用情况。
![监控面板](files/image.png)
* **详细的日志记录**: 提供详细的错误日志，方便排查。
![调用详情](files/image1.png)
![日志列表](files/image2.png)
![日志详情](files/image3.png)
* **支持自定义gemini代理**: 支持自定义gemini代理，比如自行在deno或者cloudflare上搭建gemini代理
* **openai画图接口兼容**: 将`imagen-3.0-generate-002`模型接口改造成openai画图接口，支持客户端调用。
* **灵活的添加密钥方式**: 灵活的添加密钥方式，采用正则匹配`gemini_key`,密钥去重
![添加密钥](files/image5.png)
* **兼容openai格式embeddings接口**：完美适配openai格式的`embeddings`接口，可用于本地文档向量化。
* **流式响应优化**: 可选的流式输出优化器 (`STREAM_OPTIMIZER_ENABLED`)，改善长文本流式响应的体验。
* **失败重试与 Key 管理**: 自动处理 API 请求失败，进行重试 (`MAX_RETRIES`)，并在 Key 失效次数过多时自动禁用 (`MAX_FAILURES`)，定时检查恢复 (`CHECK_INTERVAL_HOURS`)。
* **Docker 支持**: 支持AMD，ARM架构的docker部署，也可自行构建docker镜像。
>镜像地址: docker pull ghcr.io/snailyp/gemini-balance:latest
* **模型列表自动维护**: 支持openai和gemini模型列表获取，与newapi自动获取模型列表完美兼容，无需手动填写。
* **支持移除不使用的模型**: 默认提供的模型太多，很多用不上，可以通过`FILTERED_MODELS`过滤掉。
## 🚀 快速开始
### 环境要求
### 自行构建 Docker (推荐)
- Python 3.9 或更高版本
- Docker (可选，推荐用于生产环境)
### 📦 安装与配置
1. **克隆项目**:
```bash
git clone https://github.com/snailyp/gemini-balance.git
cd gemini-balance
```
2. **安装依赖**:
```bash
pip install -r requirements.txt
```
3. **配置**:
创建 `.env` 文件，并按以下分类配置环境变量：
```env
# 基础配置
BASE_URL="https://generativelanguage.googleapis.com/v1beta" # Gemini API 基础 URL，默认无需修改
MAX_FAILURES=3 # 允许单个key失败的次数，默认3次
TIME_OUT=300 # 请求超时时间，默认300s
# 认证与安全配置
API_KEYS=["your-gemini-api-key-1", "your-gemini-api-key-2"] # Gemini API 密钥列表，用于负载均衡
ALLOWED_TOKENS=["your-access-token-1", "your-access-token-2"] # 允许访问的 Token 列表
AUTH_TOKEN="" # 超级管理员token，具有所有权限，默认使用 ALLOWED_TOKENS 的第一个
# 模型功能配置
TEST_MODEL="gemini-1.5-flash" # 用于测试密钥是否可用的模型名
SEARCH_MODELS=["gemini-2.0-flash-exp"] # 支持搜索功能的模型列表
IMAGE_MODELS=["gemini-2.0-flash-exp"] # 支持绘图功能的模型列表
TOOLS_CODE_EXECUTION_ENABLED=false # 是否启用代码执行工具，默认false
SHOW_SEARCH_LINK=true # 是否在响应中显示搜索结果链接，默认true
SHOW_THINKING_PROCESS=true # 是否显示模型思考过程，默认true
FILTERED_MODELS=["gemini-1.0-pro-vision-latest", "gemini-pro-vision", "chat-bison-001", "text-bison-001", "embedding-gecko-001"] # 被禁用的模型列表
# 图片生成配置
PAID_KEY="your-paid-api-key" # 付费版API Key，用于图片生成等高级功能
CREATE_IMAGE_MODEL="imagen-3.0-generate-002" # 图片生成模型，默认使用imagen-3.0
# 图片上传配置
UPLOAD_PROVIDER="smms" # 图片上传提供商，目前支持smms、picgo、cloudflare_imgbed
SMMS_SECRET_TOKEN="your-smms-token" # SM.MS图床的API Token
PICGO_API_KEY="your-picogo-apikey" # PicoGo图床的API Key 可在 `https://www.picgo.net/settings/api` 获取
CLOUDFLARE_IMGBED_URL="https://xxxxxxx.pages.dev/upload" # CloudFlare 图床上传地址，可自行搭建：`https://github.com/MarSeventh/CloudFlare-ImgBed`
CLOUDFLARE_IMGBED_AUTH_CODE="your-cloudflare-imgber-auth-code" # CloudFlare图床的鉴权key，可在项目后台设置，若无鉴权则可直接置空。
# stream_optimizer 相关配置
# 是否启用流式输出优化，默认false
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
```
### 配置说明
#### 基础配置
- `BASE_URL`: Gemini API 的基础 URL
- 默认值: `https://generativelanguage.googleapis.com/v1beta`
- 说明: 通常无需修改，除非 API 地址发生变化
- `MAX_FAILURES`: API Key 允许的最大失败次数
- 默认值: `3`
- 说明: 超过此次数后，Key 将被暂时标记为无效
- `TIME_OUT`: 请求超时时间
- 默认值: `300`
- 说明: 单位为秒
#### 认证与安全配置
- `API_KEYS`: Gemini API 密钥列表
- 格式: JSON 数组字符串
- 用途: 支持多个 Key 轮询，实现负载均衡
- 建议: 至少配置 2 个 Key 以保证服务可用性
- `ALLOWED_TOKENS`: 访问令牌列表
- 格式: JSON 数组字符串
- 用途: 用于客户端认证
- 安全提示: 请使用足够复杂的令牌
- `AUTH_TOKEN`: 超级管理员令牌
- 可选配置，留空则使用 ALLOWED_TOKENS 的第一个
- 具有查看 API Key 状态等特权操作权限
#### 模型功能配置
- `TEST_MODEL`: 用于测试密钥可用性的模型
- 默认值: `"gemini-1.5-flash"`
- `SEARCH_MODELS`: 搜索功能支持的模型
- 默认值: `["gemini-2.0-flash-exp"]`
- 说明: 仅列表中的模型可使用搜索功能
- `IMAGE_MODELS`: 绘图功能支持的模型
- 默认值: `["gemini-2.0-flash-exp"]`
- 说明: 仅列表中的模型可使用绘图功能
- `FILTERED_MODELS`: 被禁用的模型列表
- 默认值: `["gemini-1.0-pro-vision-latest", "gemini-pro-vision", "chat-bison-001", "text-bison-001", "embedding-gecko-001"]`
- 说明: 列表中的模型将被禁用
- `TOOLS_CODE_EXECUTION_ENABLED`: 代码执行功能
- 默认值: `false`
- 安全提示: 生产环境建议禁用
- `SHOW_SEARCH_LINK`: 搜索结果链接显示
- 默认值: `true`
- 用途: 控制搜索结果中是否包含原始链接
- `SHOW_THINKING_PROCESS`: 思考过程显示
- 默认值: `true`
- 用途: 显示模型的推理过程，便于调试
#### 图片生成配置
- `PAID_KEY`: 付费版 API Key
- 用途: 用于图片生成等高级功能
- 说明: 需要单独申请的付费版 Key
- `CREATE_IMAGE_MODEL`: 图片生成模型
- 默认值: `imagen-3.0-generate-002`
- 说明: 当前支持的最新图片生成模型
#### 图片上传配置
- `UPLOAD_PROVIDER`: 图片上传服务提供商
- 默认值: `smms`
- 可选值: `smms`, `picgo`, `cloudflare_imgbed`
- 说明: 用于选择图片上传的服务提供商。目前支持 SM.MS 图床, PicGo 图床, 以及 Cloudflare ImgBed。
- `SMMS_SECRET_TOKEN`: SM.MS API Token
- 用途: 用于图片上传到 SM.MS 图床的身份验证。
- 获取方式: 需要在 [SM.MS 官网](https://sm.ms/) 注册并获取。
- `PICGO_API_KEY`: PicGo API Key
- 用途: 用于图片上传到 PicGo 图床的身份验证。
- 获取方式: 可在 [PicGo 官网](https://www.picgo.net/settings/api) 的设置页面 API 选项中获取。
- `CLOUDFLARE_IMGBED_URL`: Cloudflare ImgBed 上传地址
- 用途: 指定 Cloudflare ImgBed 图床的上传 API 地址。
- 获取方式: 如果您自行搭建了 Cloudflare ImgBed 服务，请填写您的服务部署地址。参考 [Cloudflare-ImgBed 项目](https://github.com/MarSeventh/CloudFlare-ImgBed) 自行搭建。
- 注意: URL 必须以 `https://` 开头，并指向 `/upload` 路径 ，例如 `https://cloudflare-imgbed-7b0.pages.dev/upload`。
- `CLOUDFLARE_IMGBED_AUTH_CODE`: Cloudflare ImgBed 鉴权 Key
- 用途: 用于 Cloudflare ImgBed 图床的身份验证。
- 说明: 如果您的 Cloudflare ImgBed 服务启用了鉴权，请填写鉴权 Key。若未启用鉴权，则留空即可。
- 获取方式: 在 Cloudflare ImgBed 项目的后台设置中获取，或在搭建时自行设置。
#### 流式输出优化配置
- `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`（字符）
- 说明: 长文本分块输出时，每个块的大小
### ▶️ 运行
#### 使用 Docker (推荐)
#### a) dockerfile构建
1. **构建镜像**:
@@ -216,282 +82,132 @@
docker run -d -p 8000:8000 --env-file .env gemini-balance
```
- `-d`: 后台运行。
- `-p 8000:8000`: 将容器的 8000 端口映射到主机的 8000 端口。
- `--env-file .env`: 使用 `.env` 文件设置环境变量。
* `-d`: 后台运行。
* `-p 8000:8000`: 将容器的 8000 端口映射到主机的 8000 端口。
* `--env-file .env`: 使用 `.env` 文件设置环境变量。
#### 手动运行
#### b) 用现有的docker镜像部署
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
1. **拉取镜像**:
- `--reload`: 开启热重载，方便开发调试 (生产环境不建议开启)。
```bash
docker pull ghcr.io/snailyp/gemini-balance:latest
```
## 🔌 API 接口
2. **运行容器**:
### 认证
```bash
docker run -d -p 8000:8000 --env-file .env ghcr.io/snailyp/gemini-balance:latest
```
所有 API 请求都需要在 Header 中添加 `Authorization` 字段，值为 `Bearer <your-token>`，其中 `<your-token>` 需要替换为你在 `.env` 文件中配置的 `ALLOWED_TOKENS` 中的一个或者 `AUTH_TOKEN`。
* `-d`: 后台运行。
* `-p 8000:8000`: 将容器的 8000 端口映射到主机的 8000 端口 (根据需要调整)。
* `--env-file .env`: 使用 `.env` 文件设置环境变量 (确保 `.env` 文件存在于执行命令的目录)。
### API 路由
### 本地运行 (适用于开发和测试)
本服务提供两种API路由：
如果您想在本地直接运行源代码进行开发或测试，请按照以下步骤操作：
1. **OpenAI 兼容路由** (推荐)
- 基础路径: `/v1`
- 完全兼容OpenAI API格式
- 支持所有Gemini模型
1. **确保已完成准备工作**:
* 克隆仓库到本地。
* 安装 Python 3.9 或更高版本。
* 在项目根目录下创建并配置好 `.env` 文件 (参考前面的“配置环境变量”部分)。
* 安装项目依赖：
2. **Gemini 原生路由**
- 基础路径: `/gemini/v1beta` 或 `/v1beta`
- 遵循Google原生API格式
- 适用于需要直接使用Gemini API的场景
```bash
pip install -r requirements.txt
```
### OpenAI兼容路由
2. **启动应用**:
在项目根目录下运行以下命令：
#### 获取模型列表
- **URL**: `/v1/models`
- **Method**: `GET`
- **Header**: `Authorization: Bearer <your-token>`
- **Response**: 返回支持的所有模型列表，包括最新的`gemini-2.0-flash-exp-search`等模型
#### 聊天补全 (Chat Completions)
- **URL**: `/v1/chat/completions`
- **Method**: `POST`
- **Header**: `Authorization: Bearer <your-token>`
- **Body** (JSON):
```json
{
"messages": [
{
"role": "user",
"content": "你好"
}
],
"model": "gemini-1.5-flash",
"temperature": 0.7,
"stream": false,
"tools": [],
"max_tokens": 8192,
"stop": [],
"top_p": 0.9,
"top_k": 40
}
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
- `messages`: 消息列表，格式与 OpenAI API 相同
- `model`: 模型名称，支持所有Gemini模型，包括:
- `gemini-1.5-flash`: 快速响应模型
- `gemini-2.0-flash-exp`: 实验性快速响应模型
- `gemini-2.0-flash-exp-search`: 支持搜索功能的实验性模型
- `stream`: 是否开启流式响应，`true` 或 `false`
- `tools`: 使用的工具列表
- 其他参数：与 OpenAI API 兼容的参数，如 `temperature`, `max_tokens` 等
* `app.main:app`: 指定 FastAPI 应用实例的位置 (`app` 模块中的 `main.py` 文件里的 `app` 对象)。
* `--host 0.0.0.0`: 使应用可以从本地网络中的任何 IP 地址访问。
* `--port 8000`: 指定应用监听的端口号 (您可以根据需要修改)。
* `--reload`: 启用自动重载功能。当您修改代码时，服务会自动重启，非常适合开发环境 (生产环境请移除此选项)。
### Gemini原生路由
3. **访问应用**:
应用启动后，您可以通过浏览器或 API 工具访问 `http://localhost:8000` (或您指定的主机和端口)。
#### 获取模型列表
### 完整配置项列表
- **URL**: `/gemini/v1beta/models` 或 `/v1beta/models`
- **Method**: `GET`
- **Header**: `Authorization: Bearer <your-token>`
| 配置项 | 说明 | 默认值 |
| :--------------------------- | :------------------------------------------------------- | :---------------------------------------------------- |
| **数据库配置** | | |
| `MYSQL_HOST` | 必填，MySQL 数据库主机地址 | `localhost` |
| `MYSQL_PORT` | 必填，MySQL 数据库端口 | `3306` |
| `MYSQL_USER` | 必填，MySQL 数据库用户名 | `your_db_user` |
| `MYSQL_PASSWORD` | 必填，MySQL 数据库密码 | `your_db_password` |
| `MYSQL_DATABASE` | 必填，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` | 可选，超级管理员token，具有所有权限，不填默认使用 ALLOWED_TOKENS 的第一个 | `""` |
| `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` |
| `BASE_URL` | 可选，Gemini API 基础 URL，默认无需修改 | `https://generativelanguage.googleapis.com/v1beta` |
| `MAX_FAILURES` | 可选，允许单个key失败的次数 | `3` |
| `MAX_RETRIES` | 可选，API 请求失败时的最大重试次数 | `3` |
| `CHECK_INTERVAL_HOURS` | 可选，检查禁用 Key 是否恢复的时间间隔 (小时) | `1` |
| `TIMEZONE` | 可选，应用程序使用的时区 | `Asia/Shanghai` |
| `TIME_OUT` | 可选，请求超时时间 (秒) | `300` |
| **图像生成相关** | | |
| `PAID_KEY` | 可选，付费版API Key，用于图片生成等高级功能 | `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 Token | `your-smms-token` |
| `PICGO_API_KEY` | 可选，PicoGo图床的API Key | `your-picogo-apikey` |
| `CLOUDFLARE_IMGBED_URL` | 可选，CloudFlare 图床上传地址 | `https://xxxxxxx.pages.dev/upload` |
| `CLOUDFLARE_IMGBED_AUTH_CODE`| 可选，CloudFlare图床的鉴权key | `your-cloudflare-imgber-auth-code` |
| **流式优化器相关** | | |
| `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` |
#### 生成内容
## ⚙️ API 端点
- **URL**: `/gemini/v1beta/models/{model_name}:generateContent`
- **Method**: `POST`
- **Header**: `Authorization: Bearer <your-token>`
以下是服务提供的主要 API 端点：
#### 流式生成内容
### Gemini API 相关 (`(/gemini)/v1beta`)
- **URL**: `/gemini/v1beta/models/{model_name}:streamGenerateContent`
- **Method**: `POST`
- **Header**: `Authorization: Bearer <your-token>`
* `GET /models`: 列出可用的 Gemini 模型。
* `POST /models/{model_name}:generateContent`: 使用指定的 Gemini 模型生成内容。
* `POST /models/{model_name}:streamGenerateContent`: 使用指定的 Gemini 模型流式生成内容。
### 获取词向量 (Embeddings)
### OpenAI API 相关 (`(/hf)/v1`)
- **URL**: `/v1/embeddings`
- **Method**: `POST`
- **Header**: `Authorization: Bearer <your-token>`
- **Body** (JSON):
```json
{
"input": "你的文本",
"model": "text-embedding-004"
}
```
- `input`: 输入文本。
- `model`: 模型名称。
### 健康检查
- **URL**: `/health`
- **Method**: `GET`
### Web界面功能
#### 验证页面 (auth.html)
- **URL**: `/auth`
- **说明**: 提供了一个简洁的Web界面用于验证访问令牌
- **功能特点**:
- 现代化的渐变背景设计
- 响应式布局，完美支持移动端
- 毛玻璃效果的卡片设计
- 优雅的动画效果（淡入、滑动、悬浮）
- 安全的令牌验证机制
- 清晰的错误提示功能
- PWA支持，可安装为本地应用
- 底部版权信息和GitHub链接
- 支持暗色主题适配
#### API密钥状态管理 (keys_status.html)
- **URL**: `/v1/keys/list`
- **Method**: `GET`
- **Header**: `Authorization: Bearer <your-auth-token>`
- **功能特点**:
- 只有使用 `AUTH_TOKEN` 才能访问此接口
- 分类展示API密钥状态（有效/无效）
- 可折叠的密钥列表分组
- 每个密钥显示:
- 状态标识（有效/无效）
- 密钥内容
- 失败次数统计
- 高级功能:
- 一键复制单个密钥
- 批量复制分组密钥（JSON格式）
- 实时刷新功能
- 回到顶部/底部快捷按钮
- 界面特性:
- 响应式设计，适配各种屏幕
- 优雅的动画效果
- 操作反馈（复制成功提示）
- PWA支持
- 暗色主题适配
### 图片生成 (Image Generation)
- **URL**: `/v1/images/generations`
- **Method**: `POST`
- **Header**: `Authorization: Bearer <your-auth-token>`
- **说明**: Body示例和参数说明
```json
{
"model": "dall-e-3",
"prompt": "{n:2} {ratio:16:9} 汉服美女",
"n": 1,
"size": "1024x1024"
}
```
**Prompt参数说明:**
prompt支持通过特殊标记来控制生成参数：
1. 图片数量控制:
- 格式: `{n:数量}`
- 示例: `{n:2} 一只可爱的猫` - 生成2张图片
- 取值范围: 1-4
- 说明: 如果在prompt中指定了n，将覆盖请求body中的n参数
2. 图片比例控制:
- 格式: `{ratio:宽:高}`
- 示例: `{ratio:16:9} 一片森林` - 生成16:9比例的图片
- 支持的比例: "1:1"、"3:4"、"4:3"、"9:16"、"16:9"
- 说明: 如果指定了size参数，将优先使用size对应的比例
3. 参数组合:
- 示例: `{n:2} {ratio:16:9} 一片美丽的森林` - 生成2张16:9比例的图片
- 说明: 这些参数标记会自动从prompt中移除，不会影响实际的图片生成提示词
> 注意：n的取值范围[1,4], ratio取值范围"1:1"、"3:4"、"4:3"、"9:16" 和 "16:9"
## 📚 代码结构
```plaintext
.
├── app/
│ ├── api/ # API 路由
│ │ ├── gemini_routes.py # Gemini 模型路由
│ │ └── openai_routes.py # OpenAI 兼容路由
│ ├── core/ # 核心组件
│ │ ├── config.py # 配置管理
│ │ ├── logger.py # 日志配置
│ │ └── security.py # 安全认证
│ ├── middleware/ # 中间件
│ │ └── request_logging_middleware.py # 请求日志中间件
│ ├── schemas/ # 数据模型
│ │ ├── gemini_models.py # Gemini 原始请求/响应模型
│ │ └── openai_models.py # OpenAI 兼容请求/响应模型
│ ├── services/ # 服务层
│ │ ├── chat/ # 聊天相关服务
│ │ │ ├── api_client.py # API 客户端
│ │ │ ├── message_converter.py # 消息转换器
│ │ │ ├── response_handler.py # 响应处理器
│ │ │ └── retry_handler.py #重试处理器
│ │ ├── gemini_chat_service.py # Gemini 原始聊天服务
│ │ ├── openai_chat_service.py # OpenAI 兼容聊天服务
│ │ ├── embedding_service.py # 向量服务
│ │ ├── key_manager.py # API Key 管理
│ │ └── model_service.py # 模型服务
│ └── main.py # 主程序入口
├── Dockerfile # Dockerfile
├── requirements.txt # 项目依赖
└── README.md # 项目说明
```
## 🔒 安全性
- **API Key 轮询**: 自动轮换 API Key，提高可用性和负载均衡。
- **Bearer Token 认证**: 保护 API 端点，防止未经授权的访问。
- **请求日志记录**: 记录详细的请求信息，便于调试和审计 (可选，通过取消 `app.add_middleware(RequestLoggingMiddleware)` 的注释来启用)。
- **自动重试**: 在 API 请求失败时自动重试，提高服务的稳定性。
* `GET /v1/models`: 列出可用的 OpenAI 模型。
* `POST /v1/chat/completions`: 通过 OpenAI API 进行聊天补全。
* `POST /v1/images/generations`: 通过 OpenAI API 生成图像。
* `POST /v1/embeddings`: 通过 OpenAI API 创建文本嵌入。
## 🤝 贡献
欢迎任何形式的贡献！如果你发现 bug、有新功能建议或者想改进代码，请随时提交 Issue 或 Pull Request。
欢迎提交 Pull Request 或 Issue。
1. Fork 本项目。
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)。
3. 提交你的改动 (`git commit -m 'Add some AmazingFeature'`)。
4. 推送到你的分支 (`git push origin feature/AmazingFeature`)。
5. 创建一个新的 Pull Request。
## 🙏 感谢贡献者
## ❓ 常见问题解答 (FAQ)
感谢所有为本项目做出贡献的开发者！
**Q: 如何获取 Gemini API Key？**
A: 请参考 Gemini API 的官方文档，申请 API Key。
**Q: 如何配置多个 API Key？**
A: 在 `.env` 文件的 `API_KEYS` 变量中，用列表的形式添加多个 Key，例如：`API_KEYS=["key1", "key2", "key3"]`。
**Q: 为什么我的 API Key 总是失败？**
A: 请检查以下几点：
- API Key 是否正确。
- API Key 是否已过期或被禁用。
- 是否超出了 API Key 的速率限制或配额。
- 网络连接是否正常。
**Q: 如何启用流式响应？**
A: 在请求的 Body 中，将 `stream` 参数设置为 `true` 即可。
**Q: 如何启用代码执行工具？**
A: 在 `.env` 文件的 `TOOLS_CODE_EXECUTION_ENABLED` 变量中, 设置为 `true` 即可。
<a href="https://github.com/toddyoe" title="toddyoe"><img src="https://avatars.githubusercontent.com/u/167494546?s=64&v=4" width="64" height="64"></a>
<a href="https://github.com/yangtb2024" title="yangtb2024"><img src="https://avatars.githubusercontent.com/u/164613316?s=64&v=4" width="64" height="64"></a>
<a href="https://github.com/cr-zhichen" title="cr-zhichen"><img src="https://avatars.githubusercontent.com/u/57337795?s=64&v=4" width="64" height="64"></a>
<a href="https://github.com/BetterAndBetterII" title="BetterAndBetterII"><img src="https://avatars.githubusercontent.com/u/141388234?s=96&v=4" width="64" height="64"></a>
<a href="https://github.com/yanhao98" title="yanhao98"><img src="https://avatars.githubusercontent.com/u/37316281?s=64&v=4" width="64" height="64"></a>
<a href="https://github.com/Haoyu99" title="Haoyu99"><img src="https://avatars.githubusercontent.com/u/93185981?s=60&v=4" width="64" height="64"></a>
## 📄 许可证
本项目采用 MIT 许可证。有关详细信息，请参阅 [LICENSE](LICENSE) 文件 (你需要创建一个 LICENSE 文件)。
本项目采用 MIT 许可证。

2
app/database/connection.py
View File

@@ -29,7 +29,7 @@ Base = declarative_base(metadata=metadata)
# 设置为 3600 秒（1小时），确保在 MySQL 默认的 wait_timeout (通常8小时) 或其他网络超时之前回收连接。
# 如果遇到连接失效问题，可以尝试调低此值，使其小于实际的 wait_timeout 或网络超时时间。
# databases 库会自动处理连接失效后的重连尝试。
database = Database(DATABASE_URL, min_size=5, max_size=20, pool_recycle=3600)
database = Database(DATABASE_URL, min_size=5, max_size=20, pool_recycle=1800) # Reduced recycle time to 30 mins
async def connect_to_db():

2
app/router/routes.py
View File

@@ -66,7 +66,7 @@ def setup_page_routes(app: FastAPI) -> None:
if verify_auth_token(auth_token):
logger.info("Successful authentication")
response = RedirectResponse(url="/keys", status_code=302)
response = RedirectResponse(url="/config", status_code=302)
response.set_cookie(
key="auth_token", value=auth_token, httponly=True, max_age=3600
)

2
app/templates/auth.html
View File

@@ -6,7 +6,7 @@
<style>
/* auth.html specific styles */
.auth-glass-card { /* Renamed to avoid conflict if base.html has .glass-card */
background: rgba(255, 255, 255, 0.7);
background: rgba(255, 255, 255, 0.85); /* Increased opacity */
backdrop-filter: blur(20px);
-webkit-backdrop-filter: blur(20px);
border: 1px solid rgba(255, 255, 255, 0.2);

BIN
files/image.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 347 KiB

BIN
files/image1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 281 KiB

BIN
files/image2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 328 KiB

BIN
files/image3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 230 KiB

BIN
files/image4.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 459 KiB

BIN
files/image5.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 292 KiB

BIN
files/image6.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 163 KiB

BIN
files/image7.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 665 KiB

BIN
files/image8.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 97 KiB

1
requirements.txt
View File

@@ -9,6 +9,7 @@ uvicorn
google-genai
jinja2
python-multipart
cryptography # 支持 MySQL 8+ caching_sha2_password 验证
# 数据库相关依赖
pymysql
sqlalchemy