这是一个基于 FastAPI 构建的 Gemini API 代理，旨在提供一个简单、安全且可配置的方式来访问 Google 的 Gemini 模型。适用于在 Hugging Face Spaces 上部署，并支持openai api格式的工具集成。
遇到问题请先查看以下的 错误自查 文档，确保已尝试按照其上的指示进行了相应的排查与处理。
-
termux部署的使用文档（手机使用） 感谢 @天命不又 编写
-
zeabur部署的使用文档(需付费) 感谢墨舞ink编写（已过时且暂时无人更新，欢迎提交pull requests）
-
v1.0.2
- 修复 400 错误
-
v1.0.1
- 新增
清除失效密钥功能 - 新增
输出有效秘钥功能
- 新增
- 提供
/v1/chat/completions接口，支持流式和非流式响应，支持函数调用，与 OpenAI API 格式兼容。 - 支持的输入内容: 文本、文件、图像
- 自动将 OpenAI 格式的请求转换为 Gemini 格式。
- 通过
PASSWORD环境变量设置密码。 - 提供默认密码
"123"。
- 提供的接口与 OpenAI API 格式兼容,便于接入各种服务
- 方式 1 : 通过网页前端进行配置
- 方式 2 : 根据 配置文档 中的注释说明，修改对应的变量
- 强烈建议在生产环境中设置
PASSWORD环境变量，并使用强密码。 - 根据你的使用情况调整速率限制相关的环境变量。
- 确保你的 Gemini API 密钥具有足够的配额。
-
作用： 解决部分网络环境下客户端通过非流式请求 Gemini 时可能遇到的断连问题。默认开启。
-
原理简述： 当客户端请求流式响应时，本代理会每隔一段时间向客户端发出一个空信息以维持连接，同时在后台向 Gemini 发起一个完整的、非流式的请求。等 Gemini 返回完整响应后，再一次性将响应发回给客户端。
-
注意： 如果想使用真的流式请求，请关闭该功能
-
作用： 允许您为用户的单次提问同时向 Gemini 发送多个请求，并将额外的成功响应缓存起来，用于后续重新生成回复。
-
注意： 此功能默认关闭 。只有当您将并发数设置为 2 或以上时，缓存才会生效。缓存匹配要求提问的上下文与被缓存的问题完全一致（包括标点符号）。此外，该模式目前仅支持非流式及假流式传输
Q: 新版本增加的并发缓存功能会增加 gemini 配额的使用量吗？
A: 不会。因为默认情况下该功能是关闭的。只有当你主动将并发数
CONCURRENT_REQUESTS设置为大于 1 的数值时，才会实际发起并发请求，这才会消耗更多配额。Q: 如何使用并发缓存功能？
A: 修改并发请求数，使其等于你想在一次用户提问中同时向 Gemini 发送的请求数量（例如设置为
3）。这样设置后，如果一次并发请求中收到了多个成功的响应，除了第一个返回给用户外，其他的就会被缓存起来。
-
作用： 在发送给 Gemini 的消息中添加一段随机生成的、无意义的字符串，用于"伪装"请求，可能有助于防止被识别为自动化程序。默认开启。
-
注意： 如果使用非 SillyTavern 的其余客户端 (例如 cherryStudio )，请关闭该功能
-
作用： 让 Gemini 模型能够利用搜索工具进行联网搜索，以回答需要最新信息或超出其知识库范围的问题。
-
如何使用：
在客户端请求时，选择模型名称带有
-search后缀的模型（例如gemini-2.5-pro-search，具体可用模型请通过/v1/models接口查询）。
- 通过环境变量自定义限制：
MAX_REQUESTS_PER_MINUTE：每分钟最大请求数（默认 30）。MAX_REQUESTS_PER_DAY_PER_IP：每天每个 IP 最大请求数（默认 600）。
- 超过速率限制时返回 429 错误。
- GET
/v1/models- 获取可用模型列表 - GET
/models- 获取可用模型列表（兼容旧版本）
- POST
/v1/chat/completions- 聊天补全接口，支持流式和非流式响应 - POST
/chat/completions- 聊天补全接口（兼容旧版本）
- GET
/vertex/models- 获取 Vertex 模型列表 - POST
/vertex/chat/completions- Vertex 聊天补全接口
- GET
/aistudio/models- 获取 AI Studio 模型列表 - POST
/aistudio/chat/completions- AI Studio 聊天补全接口
项目支持多种配置方式，可以通过环境变量进行配置：
PASSWORD- API访问密码，默认为"123"WEB_PASSWORD- 网页配置密码，默认与PASSWORD相同GEMINI_API_KEYS- Gemini API密钥，多个密钥用逗号分隔FAKE_STREAMING- 是否启用假流式传输，默认为trueSTORAGE_DIR- 配置持久化存储目录ENABLE_STORAGE- 是否启用配置持久化存储，默认为false
CONCURRENT_REQUESTS- 并发请求数，默认为1INCREASE_CONCURRENT_ON_FAILURE- 失败时增加的并发数，默认为0MAX_CONCURRENT_REQUESTS- 最大并发请求数，默认为3CACHE_EXPIRY_TIME- 缓存过期时间（秒），默认为21600（6小时）MAX_CACHE_ENTRIES- 最大缓存条目数，默认为500CALCULATE_CACHE_ENTRIES- 计算缓存键时使用的消息数量，默认为6PRECISE_CACHE- 是否使用精确缓存，默认为false
ENABLE_VERTEX- 是否启用Vertex AI，默认为falseGOOGLE_CREDENTIALS_JSON- Google凭证JSONENABLE_VERTEX_EXPRESS- 是否启用Vertex Express模式，默认为falseVERTEX_EXPRESS_API_KEY- Vertex Express API密钥
SEARCH_MODE- 是否启用联网搜索模式，默认为falseSEARCH_PROMPT- 联网搜索提示语
RANDOM_STRING- 是否启用随机字符串伪装，默认为trueRANDOM_STRING_LENGTH- 随机字符串长度，默认为5MAX_EMPTY_RESPONSES- 最大空响应重试次数，默认为5
MAX_RETRY_NUM- 请求时的最大总轮询key数，默认为15MAX_REQUESTS_PER_MINUTE- 每分钟最大请求数，默认为30MAX_REQUESTS_PER_DAY_PER_IP- 每天每个IP最大请求数，默认为600API_KEY_DAILY_LIMIT- 每个API密钥每天使用限制，默认为100
BLOCKED_MODELS- 屏蔽的模型列表，用逗号分隔WHITELIST_MODELS- 白名单模型列表，用逗号分隔WHITELIST_USER_AGENT- 白名单User-Agent列表，用逗号分隔
PUBLIC_MODE- 公益站模式，默认为falseDASHBOARD_URL- 前端地址ALLOWED_ORIGINS- 允许的跨域源列表，用逗号分隔
- Fork本项目到你的GitHub账户
- 在GitHub Actions中构建Docker镜像
- 在Hugging Face Spaces中创建新的Docker空间
- 配置环境变量（PASSWORD和GEMINI_API_KEYS为必需）
- 部署并访问前端界面
- 注册Claw Cloud账户
- 登录Claw Cloud控制台
- 进入APP Launchpad并创建新应用
- 使用镜像地址
ghcr.io/wyeeeee/hajimi:latest - 配置环境变量
- 部署应用并获取访问地址
- 在Google Cloud Platform中创建服务账户
- 获取服务账户的JSON凭证文件
- 在项目中启用Vertex AI API
- 配置环境变量
ENABLE_VERTEX=true和GOOGLE_CREDENTIALS_JSON - 部署应用
- 克隆项目代码
- 安装依赖：
pip install -r requirements.txt - 配置环境变量
- 运行应用：
uvicorn app.main:app --host 0.0.0.0 --port 7860
- 配置文档 - 详细的配置选项说明
- 错误自查 - 常见问题和解决方案
- Hugging Face部署指南 - 详细的Hugging Face部署教程
- Claw Cloud部署指南 - 详细的Claw Cloud部署教程
- Vertex模式指南 - Vertex AI配置和使用指南