Gemini OpenAI SDK Google AI Chat Completions 兼容 API

用 OpenAI SDK 通过兼容端点调用 Gemini

通过 Google 的 OpenAI 兼容 base URL 或多供应商网关，使用 OpenAI Python 或 TypeScript SDK 调用 Gemini，并采用当前模型别名。

AveMujica API 2026年7月15日 2 分钟阅读

你可以通过官方 OpenAI SDK 调用 Gemini：将 base_url 设为 Google 的 OpenAI 兼容端点（或前置 Gemini 的 AI 网关），使用 Gemini API Key 或网关密钥鉴权，并在普通 chat.completions 请求中选择 Gemini 模型 ID。Google 在 Gemini OpenAI 兼容指南中说明了该路径。已经把客户端形态标准化为 OpenAI 的团队，可以在不重写全部集成的情况下评估 Gemini。

Google 也指出，如果你尚未使用 OpenAI 库，直接调用 Gemini API 才是获取完整功能的推荐默认路径。兼容层是迁移和评估的桥梁，并不意味着 Gemini 拥有每一个 OpenAI 接口。

为什么 OpenAI 兼容能加速 Gemini 试用

许多代码库已经依赖 openai 包、LangChain/OpenAI 聊天模型，或手写 /v1/chat/completions 客户端。若每次实验都强制切到原生 Gemini SDK，会成倍增加鉴权辅助、流式解析与错误处理。兼容层让你可以：

保留同一套请求构造与响应解析
在 OpenAI 形态流量上对 Gemini 做 A/B
把凭证放到网关后，客户端仍然简单
在早期评估中复用同一套 agent 工具 schema

兼容仍是翻译层。Google 将 OpenAI 库支持描述为持续扩展，并且部分接口仍处于测试阶段。在设计评审中承诺功能对等前，请先阅读当前限制章节。

最小客户端配置

直连 Google OpenAI 兼容端点

Google 文档中的 Python 模式使用 Generative Language 的 OpenAI 兼容 base 路径。官方示例当前使用 gemini-3.5-flash：

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["GEMINI_API_KEY"],
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[
        {"role": "system", "content": "Answer with concrete engineering guidance."},
        {
            "role": "user",
            "content": "When should a team try Gemini through an OpenAI client?",
        },
    ],
)

print(response.choices[0].message.content)

TypeScript：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.GEMINI_API_KEY,
  baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});

const response = await client.chat.completions.create({
  model: "gemini-3.5-flash",
  messages: [
    { role: "system", content: "Answer with concrete engineering guidance." },
    {
      role: "user",
      content: "When should a team try Gemini through an OpenAI client?",
    },
  ],
});

console.log(response.choices[0]?.message?.content);

模型 ID 会变化。生产配置应优先参考 Google 的模型列表，不要写死旧版 Flash 或 Pro 快照字符串。

多供应商产品走网关路径

当 Gemini 只是多个通道之一时，把同一 SDK 指向网关：

client = OpenAI(
    api_key="GATEWAY_API_KEY",
    base_url="https://your-gateway.example.com/v1",
)

response = client.chat.completions.create(
    model="gemini-flash",  # stable alias mapped to gemini-3.5-flash (or successor)
    messages=[{"role": "user", "content": "Draft a checklist for model A/B tests."}],
)

把上游 Gemini 凭证作为通道注册一次，在模型目录中发布别名，并让应用只持有网关密钥。这与兼容 OpenAI 的 API 网关所描述的运维模型相同。

稳定别名与原始上游 ID

应用配置应依赖由运维控制的别名：

发布 gemini-flash、gemini-pro 等名称，或产品专用标签。
把这些别名映射到当前上游 ID（gemini-3.5-flash、Pro 类 ID 等）。
Google 发布替代模型时，只修改映射。
每次映射变化后运行一套短回归测试。

这样能减少客户端 PR，并让回滚只需修改配置。将别名纪律与延迟和成本的模型路由结合，使 Flash 和 Pro 的放置始终是明确的产品决策。

团队通常先验证的功能

普通聊天与多轮历史

从非流式聊天与固定评估集开始，确认：

系统指令被遵守
多轮上下文被保留
max_tokens 的截断行为符合产品预期
UI 能处理拒答与空响应

流式

多数聊天产品已消费 OpenAI SDK 流。为 Gemini 开启流式时：

把首 token 时延与总时长分开测量
决定流以错误块结束时 UI 展示什么
避免在已渲染 token 后静默故障转移

早流与中流失败的可靠性规则应写入 LLM API 故障转移策略，而不是客户端临时重试。

工具与函数调用

Gemini 的 OpenAI 兼容接口支持许多智能体工作流所需的工具：

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_docs",
            "description": "Search internal engineering docs",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "limit": {"type": "integer"},
                },
                "required": ["query"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="gemini-3.5-flash",
    messages=[{"role": "user", "content": "Find runbooks for gateway failover."}],
    tools=tools,
    tool_choice="auto",
)

在执行任何副作用前，请用白名单验证工具名称，并用 JSON Schema 或 Pydantic 校验参数。可移植性细节和不兼容矩阵位于跨供应商的可移植工具调用。

思考 / 推理 effort 映射

Gemini 模型可以通过 OpenAI 兼容字段暴露推理配置。不同 Gemini 模型对 reasoning effort 的映射不同；调整模型“思考强度”时，请检查 Google 当前映射表。对于只能设置模型字符串的客户端，网关也可以接受模型别名上的 effort 后缀。应把它们视为运维便利，并记录每个别名对应的 effort。

Embeddings 与相邻端点

Embeddings 和媒体工作流通常需要逐个检查端点。Google 的 OpenAI 兼容页面首先覆盖聊天类示例；部分批处理流程中的文件上传和下载兼容性仍可能要求原生 Google 客户端。不要因为“整个 OpenAI SDK 都能用”的表述，就跳过每个相邻接口各自的 curl 验证。

需要预留预算的限制与错配

请为产品维护明确的不匹配清单，而不是只写一句模糊的“全部测试”：

不支持或被静默丢弃的 OpenAI 参数
多模态部分的编码差异，尤其是图像和音频
工具调用边界情况，例如并行调用、空参数对象和枚举漂移
与 OpenAI 返回不同拒答形态的安全过滤器
Google 当前限制中仍列出的测试阶段缺口
限流和错误 header 的差异

如果一个请求在 OpenAI 成功、在 Gemini 返回 400，请逐个移除仅 OpenAI 支持的字段，并记录原始错误体。不要通过捕获所有异常、再在流中切换到另一个供应商来“修复”失败。

避免虚假信心的评估计划

固定一套 20–50 条提示词的评估集，并在适用时写明预期工具调用名称。
在当前默认模型与 gemini-3.5-flash（或你的 Pro 别名）上运行该套件。
把 schema 合法率和必需工具调用成功率与文本质量分开评分。
测量 p50/p95 延迟和每个成功任务的成本。
完成这些步骤后再修改路由策略。如果 Gemini 在延迟上获胜、但 schema 合法率较低，只路由能容忍更自由文本的工作流。

改应用代码前的 curl 检查

curl https://your-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-flash",
    "messages": [
      {"role": "user", "content": "Reply with the single word ready."}
    ]
  }'

直连 Google 测试时，把主机换成 https://generativelanguage.googleapis.com/v1beta/openai/ 并使用 Gemini API Key。共享环境优先网关路径，避免密钥复制到每台笔记本。

把 Gemini 作为通道运营

在多供应商舰队中，Gemini 应像其它通道一样：

凭证保存在服务端
Google 更名或下线 ID 时复核模型别名
按团队或产品划分限流与预算
健康与错误率与其它供应商并列可见
默认路由变化时复核价格上下文

这就是多供应商 LLM 网关保持可运维的方式：Gemini 是路由目标，不是第二套应用架构。

安全与密钥卫生

永远不要把 Gemini 密钥嵌入浏览器或移动应用。
优先为每个服务使用最小权限的网关作用域密钥。
谨慎记录工具参数；agent 可能把敏感用户数据送入函数调用。
当 agent 能自动调用外部工具时，参考 OWASP LLM 指引；过度代理是产品风险，不只是模型风险。

迁移顺序

启用 Gemini 通道，并用 curl 验证 /v1/chat/completions。
把一个非关键服务指向 Gemini 模型别名。
运行评估套件，比较 schema/工具成功率。
加入流式客户端。
加入带服务端参数校验的工具调用 agent。
在路由策略中决定固定、金丝雀或故障转移位置。
扩大流量前记录回滚模型别名。

官方来源

最近核对：2026-07-15。锁定生产路由前请确认 Google 文档中的模型 ID、端点路径与限制表。

常见问题

Gemini 的 OpenAI 兼容端点是完整的 OpenAI 克隆吗？

不是。它是面向常见 OpenAI 客户端工作流的兼容层，部分端点、参数和行为仍有差异。请针对依赖的功能阅读 Google 限制章节。如果你尚未投入使用 OpenAI 库，Google 仍建议直接使用原生 Gemini API。

应该通过 Google 的 base URL 还是网关使用 Gemini？

本地快速实验可用 Google base URL。涉及多服务、多团队、多供应商、预算或审计时用网关。

应该从哪个 Gemini 模型开始？

对于延迟敏感的评估，从 Google 文档中的当前 Flash 类 ID 开始（本文撰写时，示例使用 gemini-3.5-flash）；更困难的推理或工具工作流使用 Pro 类模型。把它们映射为稳定的网关别名，不要在应用配置中到处写原始 ID。

能否沿用我在 OpenAI 上使用的同一套工具 schema？

初期移植常常可以，但要逐个校验。并行工具调用、严格 JSON 与边界参数编码需要在 Gemini 上显式测试。

首次 Gemini 金丝雀

创建或选择 Gemini 通道，让 OpenAI SDK 通过网关调用 /v1/chat/completions，并运行固定的 20 条提示词评估，其中至少包含一次工具调用。将 schema 成功率和延迟与当前默认模型比较，然后决定 Gemini 在该工作流中应作为默认、金丝雀还是故障转移模型。