diff --git a/.env.example b/.env.example index 35374b2..547ff66 100644 --- a/.env.example +++ b/.env.example @@ -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 diff --git a/README.md b/README.md index ef8999e..5533603 100644 --- a/README.md +++ b/README.md @@ -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 `，其中 `` 需要替换为你在 `.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 ` -- **Response**: 返回支持的所有模型列表，包括最新的`gemini-2.0-flash-exp-search`等模型 - -#### 聊天补全 (Chat Completions) - -- **URL**: `/v1/chat/completions` -- **Method**: `POST` -- **Header**: `Authorization: Bearer ` -- **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 ` +| 配置项 | 说明 | 默认值 | +| :--------------------------- | :------------------------------------------------------- | :---------------------------------------------------- | +| **数据库配置** | | | +| `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 ` +以下是服务提供的主要 API 端点： -#### 流式生成内容 +### Gemini API 相关 (`(/gemini)/v1beta`) -- **URL**: `/gemini/v1beta/models/{model_name}:streamGenerateContent` -- **Method**: `POST` -- **Header**: `Authorization: Bearer ` +* `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 ` -- **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 ` -- **功能特点**: - - 只有使用 `AUTH_TOKEN` 才能访问此接口 - - 分类展示API密钥状态（有效/无效） - - 可折叠的密钥列表分组 - - 每个密钥显示: - - 状态标识（有效/无效） - - 密钥内容 - - 失败次数统计 - - 高级功能: - - 一键复制单个密钥 - - 批量复制分组密钥（JSON格式） - - 实时刷新功能 - - 回到顶部/底部快捷按钮 - - 界面特性: - - 响应式设计，适配各种屏幕 - - 优雅的动画效果 - - 操作反馈（复制成功提示） - - PWA支持 - - 暗色主题适配 - -### 图片生成 (Image Generation) - -- **URL**: `/v1/images/generations` -- **Method**: `POST` -- **Header**: `Authorization: Bearer ` -- **说明**: 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` 即可。 + + + + + + ## 📄 许可证 -本项目采用 MIT 许可证。有关详细信息，请参阅 [LICENSE](LICENSE) 文件 (你需要创建一个 LICENSE 文件)。 +本项目采用 MIT 许可证。 diff --git a/app/database/connection.py b/app/database/connection.py index 25c4b74..061ff1a 100644 --- a/app/database/connection.py +++ b/app/database/connection.py @@ -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(): diff --git a/app/router/routes.py b/app/router/routes.py index 8c90da7..4fdc52b 100644 --- a/app/router/routes.py +++ b/app/router/routes.py @@ -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 ) diff --git a/app/templates/auth.html b/app/templates/auth.html index 9ebdcff..f789030 100644 --- a/app/templates/auth.html +++ b/app/templates/auth.html @@ -6,7 +6,7 @@