<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/PublicAffairs/openai-gemini) · [上游 README](https://github.com/PublicAffairs/openai-gemini/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

## 为什么

Gemini API 提供[免费](https://ai.google.dev/gemini-api/docs/pricing#free) 层级，*限额慷慨*，但仍有许多工具仅支持 OpenAI API。

本项目可免费提供一个个人使用的、兼容 OpenAI 的端点。


## 无服务器（Serverless）？

虽然它运行在云端，但无需自行维护服务器。
可免费轻松部署到多种云平台提供商
（限额慷慨，适合个人使用）。

> [!TIP]
> 在本地运行代理端点也是一种[选择](#serve-locally---with-node-deno-bun)！


## 如何开始

你需要一个个人的 Google [API 密钥](https://aistudio.google.com/app/api-keys).

> [!IMPORTANT]
> 即使你位于[支持的地区](https://ai.google.dev/gemini-api/docs/available-regions#available_regions), 之外，仍可通过 VPN 获取。

请按照下方说明，将项目部署到任一提供商。
你需要在那里注册账号。

如果选择“一键部署”，系统会引导你先 Fork 仓库，
这对持续集成（CI）是必需的。


### 使用 Vercel 部署

 [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/PublicAffairs/openai-gemini&repository-name=my-openai-gemini)
- 也可通过 [cli](https://vercel.com/docs/cli): 部署
  `vercel deploy`
- 本地运行：`vercel dev`
- Vercel _Functions_ [限制](https://vercel.com/docs/functions/limitations)（使用 _Edge_ 运行时）


### 部署到 Netlify

[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/PublicAffairs/openai-gemini&integrationName=integrationName&integrationSlug=integrationSlug&integrationDescription=integrationDescription)
- 也可通过 [cli](https://docs.netlify.com/cli/get-started/): 部署
  `netlify deploy`
- 本地运行：`netlify dev`
- 提供两种不同的 API 基址：
  - `/v1`（例如 `/v1/chat/completions` 端点）  
    _Functions_ [限制](https://docs.netlify.com/build/functions/get-started/#synchronous-function)
  - `/edge/v1`  
    _Edge functions_ [限制](https://docs.netlify.com/build/edge-functions/limits/)


### 部署到 Cloudflare

[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/PublicAffairs/openai-gemini)
- 也可手动部署：将 [`src/worker.mjs`](src/worker.mjs) 的内容粘贴到
  https://workers.cloudflare.com/playground（参见该页面的 `Deploy` 按钮）。
- 也可通过 [cli](https://developers.cloudflare.com/workers/wrangler/): 部署
  `wrangler deploy`
- 本地运行：`wrangler dev`
- _Worker_ [限制](https://developers.cloudflare.com/workers/platform/limits/#worker-limits)


### 部署到 Deno

详见[此处](https://github.com/PublicAffairs/openai-gemini/discussions/19).


### 本地运行 - 使用 Node、Deno、Bun

仅在 Node 环境下：`npm install`。

然后执行 `npm run start` / `npm run start:deno` / `npm run start:bun`。


#### 开发模式（监听源码变更）

仅在 Node 环境下：`npm install --include=dev`

然后：`npm run dev` / `npm run dev:deno` / `npm run dev:bun`。


## 如何使用
如果你在浏览器中打开新部署的站点，只会看到一条 `404 Not Found` 消息。这是预期行为，因为该 API 并非为浏览器直接访问而设计。
要在软件中使用，请在对应设置字段中填入 API 地址和你的 Gemini API 密钥。

> [!NOTE]
> 并非所有软件工具都允许覆盖 OpenAI 端点，但许多工具支持
> （不过这些设置有时藏得很深）。

通常应按以下格式指定 API 基址：  
`https://my-super-proxy.vercel.app/v1`

相关字段可能标记为 "_OpenAI proxy_"。
你可能需要在 "_Advanced settings_" 或类似区域中查找。
或者它可能位于某个配置文件中（详情请查阅相关文档）。

对于某些命令行工具，你可能需要设置环境变量，_例如_：
```sh
OPENAI_BASE_URL="https://my-super-proxy.vercel.app/v1"
```
_…或_：
```sh
OPENAI_API_BASE="https://my-super-proxy.vercel.app/v1"
```


## 模型

若指定的 [model] 名称以 "gemini-"、"gemma-" 或 "models/" 开头，请求将使用该模型。
否则将应用以下默认值：

- `chat/completions`：`gemini-flash-latest`
- `embeddings`：`gemini-embedding-001`

[model]: https://ai.google.dev/gemini-api/docs/models


## 内置工具

要使用 **web search** 工具，在模型名称后追加 ":search"
（例如 "gemini-2.5-flash:search"）。

注意：尚未实现 `annotations` 消息的 property。


## 媒体

支持按 OpenAI [specs] 规范输入 [Vision] 和 [audio]。
通过 [`inlineData`](https://ai.google.dev/api/caching#Part). 实现。

[vision]: https://platform.openai.com/docs/guides/images-vision?api-mode=chat&format=url#giving-a-model-images-as-input
[audio]: https://platform.openai.com/docs/guides/audio?example=audio-in&lang=curl#add-audio-to-your-existing-application
[specs]: https://platform.openai.com/docs/api-reference/chat/create


## Gemini 专属功能

Gemini 支持多项 OpenAI 模型不具备的功能，
但可通过 `extra_body` 字段启用。
其中最值得注意的是 [`thinking_config`](https://ai.google.dev/gemini-api/docs/openai#thinking).

更多详情请参阅 [Gemini API 文档](https://ai.google.dev/gemini-api/docs/openai#extra-body).

---

## 支持的 API 端点及适用参数

- [x] `chat/completions`

  目前，适用于两个 API 的大多数参数均已实现。
  <details>

  - [x] `messages`
      - [x] `content`
      - [x] `role`
          - [x] "system" (=>`system_instruction`)
          - [x] "user"
          - [x] "assistant"
          - [x] "tool"
      - [x] `tool_calls`
  - [x] `model`
  - [x] `frequency_penalty`
  - [ ] `logit_bias`
  - [ ] `logprobs`
  - [ ] `top_logprobs`
  - [x] `max_tokens`，`max_completion_tokens`
  - [x] `n`（`candidateCount` <8，不适用于流式传输）
  - [x] `presence_penalty`
  - [x] `reasoning_effort`
  - [x] `response_format`
      - [x] "json_object"
      - [x] "json_schema"（OpenAPI 3.0 schema 对象的一个选定子集）
      - [x] "text"
  - [x] `seed`
  - [x] `stop`：string|array（`stopSequences` [1,5]）
  - [x] `stream`
  - [x] `stream_options`
      - [x] `include_usage`
  - [x] `temperature`（OpenAI 为 0.0..2.0，但 Gemini 最高支持至无穷大）
  - [x] `top_p`
  - [x] `tools`
  - [x] `tool_choice`
  - [ ] `parallel_tool_calls`（在 Gemini 中始终处于启用状态）
  - [x] [`extra_body`](#gemini-specific-functions)

  </details>
- [ ] `completions`
- [x] `embeddings`
  - [x] `dimensions`
- [x] `models`