mirror of
https://github.com/fawney19/Aether.git
synced 2026-09-01 17:00:21 +08:00
fix(gateway): cover Google OpenAI-compatible roots
This commit is contained in:
MMEXA
@@ -1,7 +1,7 @@
|
||||
# Gemini API Endpoint Routing Design
|
||||
|
||||
**状态:** implementation design
|
||||
**最后更新:** 2026-05-17
|
||||
**最后更新:** 2026-05-18
|
||||
**目标:** 把 Gemini Developer API 和 Vertex AI 的端点语义在 Aether 内部做成明确、可测试、可审计的一等路由语义，根治 `generativelanguage.googleapis.com` 与 `aiplatform.googleapis.com` 混用、批量 embedding 伪成功、provider 能力声明不完整等问题。
|
||||
|
||||
---
|
||||
@@ -15,6 +15,13 @@ Aether 里同一个 `api_format` 只描述请求/响应数据形态，不等于
|
||||
| Google / Gemini Developer API | Gemini Developer API, 也就是 AI Studio 这条 Gemini API | `generativelanguage.googleapis.com` | API key | 默认 Gemini provider 应走这里 |
|
||||
| Vertex AI | Vertex AI Gemini API | `aiplatform.googleapis.com` 或 `{region}-aiplatform.googleapis.com` | service account / Vertex API key | `provider_type = vertex_ai` 应走这里 |
|
||||
|
||||
Aether 还必须区分 Google 官方的 OpenAI-compatible 表面。它们使用 OpenAI request/response schema，但不等于 native `generateContent` / `embedContent` endpoint：
|
||||
|
||||
| OpenAI-compatible 表面 | 后端产品面 | 官方 API root | 主要认证形态 | Aether 处理原则 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| Gemini Developer API OpenAI compatibility | Gemini Developer API / AI Studio | `https://generativelanguage.googleapis.com/v1beta/openai` | Gemini API key as Bearer | 只在 provider format 是 `openai:*` 且显式配置该 root 时使用 |
|
||||
| Vertex AI OpenAI compatibility | Vertex AI / Google Cloud | `https://aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/endpoints/openapi` | Google Cloud access token / service account | 只在显式 OpenAI-compatible endpoint 上使用；不得替代 native Vertex provider 主链 |
|
||||
|
||||
端点动作必须按后端产品面区分：
|
||||
|
||||
| 能力 | Gemini Developer API | Vertex AI | Aether 处理原则 |
|
||||
@@ -31,6 +38,8 @@ Aether 里同一个 `api_format` 只描述请求/响应数据形态，不等于
|
||||
3. Vertex embedding 批量请求在没有官方 batch 端点前不能静默改走 `generativelanguage.googleapis.com:batchEmbedContents`。
|
||||
4. 任何“不支持”的情况必须在调度/URL 构造阶段显式暴露为不可用，不能伪成功。
|
||||
5. Provider 模板、runtime policy、URL builder、conversion policy、测试连接、live DB reconciliation 必须消费同一个语义模型。
|
||||
6. Google 官方 OpenAI-compatible root 已经包含 API root，Aether 不得额外拼接 `/v1`，否则会生成 `.../openai/v1/...` 或 `.../endpoints/openapi/v1/...` 这类错误 URL。
|
||||
7. Native Gemini endpoint 与 Google OpenAI-compatible endpoint 不是互相 fallback 的关系。显式配置 `openai:*` 才能走 OpenAI-compatible；显式配置 `gemini:*` 才能走 native Gemini REST。
|
||||
|
||||
---
|
||||
|
||||
@@ -48,6 +57,7 @@ Aether 里同一个 `api_format` 只描述请求/响应数据形态，不等于
|
||||
- Gemini API Generate Content: <https://ai.google.dev/api/generate-content>
|
||||
- Gemini API Embeddings guide: <https://ai.google.dev/gemini-api/docs/embeddings>
|
||||
- Gemini API embeddings reference: <https://ai.google.dev/api/embeddings>
|
||||
- Gemini API OpenAI compatibility: <https://ai.google.dev/gemini-api/docs/openai>
|
||||
- Gemini API migrate to cloud / Vertex AI: <https://ai.google.dev/gemini-api/docs/migrate-to-cloud>
|
||||
|
||||
工程含义：
|
||||
@@ -56,6 +66,7 @@ Aether 里同一个 `api_format` 只描述请求/响应数据形态，不等于
|
||||
- `embedContent` 是单条 embedding。
|
||||
- `batchEmbedContents` 是 Developer API 的批量 embedding 方法；批量 body 形态是顶层 `requests[]`，每项包含 `model` 和 `content`。
|
||||
- Developer API key 不应被拼进 path；Aether URL builder 应继续过滤或独立处理 `key` query，避免 query 重复或泄露。
|
||||
- Developer API 的 OpenAI-compatible root 是 `/v1beta/openai`，其 chat / embedding path 是 `/chat/completions` 与 `/embeddings`，不是 `/v1/chat/completions` 与 `/v1/embeddings`。
|
||||
|
||||
### Vertex AI Gemini API
|
||||
|
||||
@@ -68,6 +79,7 @@ Vertex AI 的 Gemini API REST reference 使用 `aiplatform.googleapis.com` 或 r
|
||||
- Vertex AI Embed Content REST: <https://docs.cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/v1/projects.locations.publishers.models/embedContent>
|
||||
- Vertex AI REST resources: <https://docs.cloud.google.com/vertex-ai/generative-ai/docs/reference/rest/v1/projects.locations.publishers.models>
|
||||
- Vertex AI text embeddings API: <https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api>
|
||||
- Vertex AI OpenAI compatibility: <https://cloud.google.com/vertex-ai/generative-ai/docs/start/openai>
|
||||
|
||||
工程含义：
|
||||
|
||||
@@ -77,6 +89,8 @@ Vertex AI 的 Gemini API REST reference 使用 `aiplatform.googleapis.com` 或 r
|
||||
- Vertex API key 路径可走：
|
||||
- `https://aiplatform.googleapis.com/v1/publishers/google/models/{model}:{action}?key=...`
|
||||
- Vertex REST reference 当前列出 `embedContent`，未列出 `batchEmbedContents`。因此 Aether 不得自行构造 Vertex batch endpoint。
|
||||
- Vertex OpenAI-compatible root 是 `/v1/projects/{project}/locations/{location}/endpoints/openapi`，其 OpenAI path 直接挂在这个 root 之后。
|
||||
- 自定义 Vertex OpenAI-compatible endpoint 可以使用 service account token 刷新，但只有 base URL 明确落在 `/endpoints/openapi` 时才能启用该 Vertex auth 语义。普通 `aiplatform.googleapis.com` + `openai:*` 不能被误判成 Vertex OpenAI compatibility。
|
||||
|
||||
### Google Gen AI SDK 的后端切换语义
|
||||
|
||||
@@ -171,6 +185,23 @@ Vertex 单条 embedding 的模型由 URL path 承载，body 不得重复携带
|
||||
|
||||
本次先做第一阶段，因为它不会隐藏批量语义差异；后续如果实现 fan-out，必须有单独设计与负载控制，不得把 fan-out 塞进 URL builder。
|
||||
|
||||
### Google OpenAI-Compatible URL
|
||||
|
||||
OpenAI-compatible URL 属于显式 passthrough root，不参与 native Gemini URL builder。
|
||||
|
||||
| Aether api_format | Gemini Developer API OpenAI compatibility | Vertex AI OpenAI compatibility | Aether 处理原则 |
|
||||
| --- | --- | --- | --- |
|
||||
| `openai:chat` | `/v1beta/openai/chat/completions` | `/v1/projects/{project}/locations/{location}/endpoints/openapi/chat/completions` | root 已含 API 版本，不再补 `/v1` |
|
||||
| `openai:embedding` | `/v1beta/openai/embeddings` | `/v1/projects/{project}/locations/{location}/endpoints/openapi/embeddings` | root 已含 API 版本，不再补 `/v1` |
|
||||
|
||||
这条链路的关键边界：
|
||||
|
||||
1. `openai:*` provider format 走 OpenAI-compatible schema，不做 OpenAI -> Gemini native body 转换。
|
||||
2. `gemini:*` provider format 走 native Gemini schema，不因目标是 Google provider 就切到 OpenAI-compatible endpoint。
|
||||
3. 如果用户请求 `openai:*`、provider endpoint 是 `gemini:*`，Aether 走格式转换后打 native Gemini endpoint。
|
||||
4. 如果用户请求 `openai:*`、provider endpoint 也是 `openai:*`，Aether 保持 OpenAI schema 并打显式 OpenAI-compatible root。
|
||||
5. 以上两条都是正式主链，不能互相静默顶替。
|
||||
|
||||
---
|
||||
|
||||
## 请求体转换边界
|
||||
@@ -210,6 +241,8 @@ Vertex 单条 embedding 的模型由 URL path 承载，body 不得重复携带
|
||||
| `gemini:embedding` 批量 | `openai:embedding` | 支持 | 支持于格式层；执行层仍受 Vertex batch 限制 | Gemini `requests[]` -> OpenAI `input[]` |
|
||||
| `gemini:embedding` response | `openai:embedding` response | 支持 | 支持 | Gemini `embedding.values` / `embeddings[].values` -> OpenAI `data[].embedding` |
|
||||
| `openai:embedding` response | `gemini:embedding` response | 支持 | 支持于格式层 | OpenAI `data[]` -> Gemini single `embedding` 或 batch `embeddings[]` |
|
||||
| `openai:chat` | `openai:chat` on Google OpenAI-compatible root | 支持 | 支持 | passthrough OpenAI schema，不做 native Gemini 转换 |
|
||||
| `openai:embedding` | `openai:embedding` on Google OpenAI-compatible root | 支持 | 支持 | passthrough OpenAI schema，不做 native Gemini 转换 |
|
||||
|
||||
这张矩阵的关键点：
|
||||
|
||||
@@ -217,6 +250,7 @@ Vertex 单条 embedding 的模型由 URL path 承载，body 不得重复携带
|
||||
2. Vertex 不支持 batch endpoint 是 transport/execution 能力限制，不是格式转换器不能表达 batch。
|
||||
3. 一旦 provider family 是 Vertex，批量请求不能借格式转换之名回退到 Developer API。
|
||||
4. 对 OpenAI embedding 单项数组，转换器必须生成 Gemini 单条 body，避免把“单条业务请求”误判成 Vertex batch。
|
||||
5. Google OpenAI-compatible passthrough 与 OpenAI -> Gemini native conversion 是两条显式路径。管理员通过 provider endpoint format 选择路径，Aether 不得自动“择优”改路。
|
||||
|
||||
---
|
||||
|
||||
@@ -274,6 +308,14 @@ Runtime policy 必须表达：
|
||||
8. Gateway test connection:
|
||||
- Gemini generate content 测试不能强制 `maxOutputTokens = 5`
|
||||
- Gemini 3 / thinking 模型返回 HTTP 200 但无 visible content 时必须判失败，不能写成成功
|
||||
9. Google OpenAI-compatible roots:
|
||||
- Developer API OpenAI root `.../v1beta/openai` 打 `openai:chat` 时生成 `.../chat/completions`，不得生成 `.../openai/v1/chat/completions`
|
||||
- Developer API OpenAI root `.../v1beta/openai` 打 `openai:embedding` 时生成 `.../embeddings`，不得生成 `.../openai/v1/embeddings`
|
||||
- Vertex OpenAI root `.../endpoints/openapi` 打 `openai:chat` / `openai:embedding` 时直接挂对应 OpenAI path
|
||||
- 自定义 Vertex OpenAI-compatible service account endpoint 必须进入 Vertex auth refresh 上下文；普通 `aiplatform.googleapis.com` + `openai:*` 不得被误认成 Vertex OpenAI-compatible
|
||||
10. Admin write validation:
|
||||
- Vertex API key key formats 允许 `gemini:generate_content` 与 `gemini:embedding`
|
||||
- Vertex service account key formats 允许 `claude:messages`、`gemini:generate_content` 与 `gemini:embedding`
|
||||
|
||||
测试断言必须检查具体 URL、具体 action、具体 unsupported 结果，不能只检查 `Some(url)` 或状态码。
|
||||
|
||||
@@ -318,6 +360,7 @@ http://aether-app:8084/v1
|
||||
3. 不为了让 HTTP 200 看起来成功而接受空 candidate / MAX_TOKENS 无 visible content。
|
||||
4. 不改前端视觉定制、字体、品牌名、landing page 设计。
|
||||
5. 不用旧 provider endpoint 继续承担新主链。
|
||||
6. 不把 Google OpenAI-compatible endpoint 当成 native Gemini endpoint 的隐藏 fallback；它只能通过显式 `openai:*` endpoint 进入。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user