Gemini 兼容接入
遵循 Gemini 规范的第三方上游接入——以 gemini-compatible 协议类型登记、generateContent 形态映射、角色与字段对齐及路由配置示例
Gemini 兼容接入用于纳管遵循 Gemini 规范的第三方上游。这类上游以 generateContent 形态对接，其消息结构与角色命名与 OpenAI 形态差异较大，平台在统一入口与上游之间做相应的格式与角色转换。本页只写 Gemini 兼容接入相对通用接入规则的差异。
接入要点
登记时 source 取 third_party、type 取 gemini-compatible。平台据此把统一入口请求翻译为 Gemini 规范形态，再把上游响应对齐回统一响应。
curl https://your-platform/api/v1/providers \
-H "Content-Type: application/json" \
-H "Cookie: <控制台会话凭证>" \
-d '{
"name": "Gemini 兼容上游",
"source": "third_party",
"type": "gemini-compatible",
"models": ["<模型中性名>"],
"group": "default",
"priority": 3,
"weight": 1
}'| 字段 | Gemini 兼容取值 | 说明 |
|---|---|---|
source | third_party | 第三方兼容接入 |
type | gemini-compatible | 平台按 Gemini 规范做请求/响应格式转换 |
models | 中性名数组 | 上游实际模型名映射为对外中性名 |
请求与响应映射
Gemini 规范的消息结构与角色命名与 OpenAI 形态差异较大，转换要点如下；客户应用始终只面对统一入口的 OpenAI 形态，转换对其透明：
| 平台统一入口（OpenAI 形态） | Gemini 兼容上游 | 映射 |
|---|---|---|
model（中性名） | model（上游实际模型名） | 按 models 登记解析 |
messages（role: user/assistant） | contents（role: user/model） | 平台把 assistant 角色对齐为 model，逐条消息转为 parts |
messages 中的 system 角色 | 独立的系统指令字段 | 平台把 system 消息抽出为系统指令 |
max_tokens | 生成配置中的最大输出限制 | 映射到 Gemini 的生成配置 |
stream | 流式 generateContent | 透传，流式逐 chunk 经护栏中间件处理 |
响应方向，平台把上游的候选结果对齐回统一的 chat.completion 结构，并在 usage 上补全 6 档计量信息：
{
"object": "chat.completion",
"model": "<实际路由的上游模型中性名>",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "<生成内容>" },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 0,
"completion_tokens": 0,
"total_tokens": 0,
"cached_input_tokens": 0,
"price_tier": "<适用单价档（6 档之一）>",
"thinking": false
}
}角色对齐是 Gemini 兼容接入的关键差异。 OpenAI 形态的
assistant在 Gemini 规范中为model，system为独立指令；平台在转换层完成这些对齐，客户应用无需改动既有请求结构。其余字段（计量扩展、护栏处置）与其它上游类型一致。
路由与备份
Gemini 兼容上游同样进入模型池准入判定，与自有供应及其它规范的第三方上游按分组、优先级、权重协同。可在「模型接入」页做接入探测确认连通：
curl https://your-platform/api/v1/providers/<上游标识>/probe \
-X POST \
-H "Cookie: <控制台会话凭证>"Gemini 兼容上游常作为模型池的扩展供给层，与 OpenAI / Anthropic 兼容上游共同保证同一中性名的多源可用。路由的降级与故障转移轨迹可在「请求监控」页（
GET /api/v1/monitor/route-trail）查看。
其它第三方规范见 OpenAI 兼容接入、Anthropic 兼容接入；端点契约见 API 参考。