合作伙伴和库集成

本指南概述了基于 Gemini API 构建库、平台和网关的架构策略。其中详细介绍了使用官方 GenAI SDK、Direct API (REST/gRPC) 和 OpenAI 兼容层之间的技术权衡。

如果您正在为其他开发者构建工具（例如开源框架、企业网关或 SaaS 聚合器），并且需要针对依赖项卫生、软件包大小或功能对等性进行优化，请使用本指南。

什么是合作伙伴集成？

合作伙伴是指在 Gemini API 与最终用户开发者之间构建集成方案的任何人。我们将合作伙伴分为四种原型。了解自己最符合哪种情况，有助于您选择合适的集成途径。

生态系统框架

• 您的身份：开源框架（例如 LangChain、LlamaIndex、Spring AI）或特定于语言的客户端。
• 您的目标：广泛的兼容性。您希望库在用户选择的任何环境中都能正常运行，而不会强制发生冲突。

运行时和边缘平台

• 您是：SaaS 平台、AI 网关或云基础设施提供商（例如，Vercel、Cloudflare、Zapier），这些平台会在受限环境中执行代码。
• 您的目标：效果。您需要低延迟、最小的软件包大小和快速的冷启动。

聚合服务商

• 您是：平台、代理或内部“模型花园”，可将许多不同的 LLM 提供商（例如 OpenAI、Anthropic、Google）的访问权限标准化为单个接口。
• 您的目标：可移植性和一致性。

企业网关

• 您是：大型公司的内部平台工程设计团队，负责为数百名内部开发者构建“黄金路径”。
• 您的目标：标准化、治理和统一身份验证。

对比一览表

全球最佳实践：无论选择哪种路径，所有合作伙伴都必须发送 x-goog-api-client 标头。

Google GenAI SDK 集成

对于框架，实现 Google GenAI SDK 通常是最简单的途径，因为在支持的语言中，该 SDK 的代码行数最少。

对于内部平台团队，您的主要交付成果通常是“黄金路径”，可让产品工程师在遵守安全政策的同时快速行动。

优点：

• 用于 Vertex AI 迁移的统一接口：内部开发者通常使用 API 密钥 (Gemini API) 进行原型设计，并部署到 Vertex AI (IAM) 以符合生产要求。SDK 会抽象化这些身份验证差异。同样，对于框架，您可以实现一个代码路径，并支持两组用户。
• 客户端辅助程序：SDK 包含惯用实用程序，可减少复杂任务的样板代码。
  • 示例：直接在提示中支持 PIL 图片对象、自动函数调用和全面的类型。
• 零日功能访问：新的 API 功能在发布时通过 SDK 提供。
• 改进了代码生成支持：本地 SDK 安装会将类型定义和文档字符串公开给编码助理（例如，Cursor、Copilot）。 与生成原始 REST 请求相比，此上下文可提高代码生成准确率。

权衡：

• 依赖项权重和复杂性：SDK 有自己的依赖项，这可能会增加软件包大小，并可能带来供应链风险。
• 版本控制：新的 API 功能通常与最低 SDK 版本相关联。您可能需要向用户推送更新，以便他们使用新功能或模型，而在某些情况下，这可能需要更改影响用户的传递依赖项。
• 协议限制：SDK 仅支持将 HTTPS 用于主 API，并将 WebSockets (WSS) 用于 Live API。使用高级 SDK 客户端时不支持 gRPC。
• 语言支持：SDK 支持当前语言版本。如果您需要支持 EOL 版本（例如 Python 3.9），您需要维护一个分支。

最佳实践：

• 锁定版本：在内部基础映像中固定 SDK 版本，以确保各个团队之间的稳定性。

直接 API 集成

如果您要将库分发给数千名开发者，在受限的环境中运行，或者构建需要 Gemini 抢先版功能的聚合器，则可能需要使用 REST 或 gRPC 直接与 API 集成。

优点：

• 完整的功能访问权限：与 OpenAI 兼容层不同，直接使用 API 可启用 Gemini 特有的功能，例如上传到 File API、创建内容缓存以及使用双向 Live API。
• 依赖项最少：在因大小或审核成本而对依赖项敏感的环境中。通过 fetch 等标准库或 httpx 等封装容器直接使用 API 可确保您的库保持轻量级。
• 与语言无关：这是 SDK 未涵盖的语言（例如 Rust、PHP 和 Ruby）的唯一途径，因为没有语言限制。
• 性能：Direct API 的初始化开销为零，可最大限度地减少无服务器函数中的冷启动。

权衡：

• 手动实现 Vertex AI：与 SDK 不同，直接使用 API 不会自动处理 AI Studio（API 密钥）和 Vertex AI (IAM) 之间的身份验证差异。如果您想同时支持这两个环境，则必须实现单独的身份验证处理程序。
• 没有原生类型或辅助程序：除非您自行实现，否则您无法获得请求对象的代码补全或编译时检查。没有客户端“辅助程序”（例如，函数到架构转换器），因此您必须自行手动编写此逻辑。

最佳实践

我们提供了一种机器可读的规范，您可以使用该规范为库生成类型定义，从而无需手动编写这些定义。在 build 流程中下载规范，生成类型，并交付编译后的代码。

• 端点： https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

OpenAI SDK 集成

如果您是优先考虑统一架构 (OpenAI Chat Completions) 而非特定于模型的功能的平台，那么这是最快的途径。

优点：

• 低摩擦：您通常可以通过更改 baseURL 和 apiKey 来添加 Gemini 支持。这是一种快速集成“自带密钥”实现的方式，无需编写新代码即可添加 Gemini 支持。
• 限制：如果您只能使用 OpenAI SDK，并且不需要高级 Gemini 功能（例如 File API），或者不需要手动添加对“依托 Google 搜索进行接地”等工具的支持，则建议采用此途径。

权衡：

• 功能限制：兼容性层对核心 Gemini 功能施加了限制。不同平台提供的服务器端工具各不相同，可能需要手动处理才能与 Gemini API 工具搭配使用。
• 翻译开销：由于 OpenAI 架构与 Gemini 的架构并非一一对应，因此依赖兼容性层会引入一些复杂性，需要额外的实现工作才能解决，例如将用户“搜索”工具映射到正确的平台工具。如果您需要大量特殊情况处理，那么为每个平台使用专用 SDK 或 API 可能更有价值。

最佳实践

尽可能直接与 Gemini API 集成。不过，为了获得最大兼容性，请考虑使用可识别不同提供商并能为您处理工具和消息映射的库。

适用于所有合作伙伴的最佳实践：客户身份识别

以平台或库的形式调用 Gemini API 时，您必须使用 x-goog-api-client 标头标识您的客户端。

这样一来，Google 就可以识别您的特定流量细分，并且如果您的库出现特定的错误模式，我们可以主动联系您，帮助您进行调试。

请使用格式 company-product/version（例如，acme-framework/1.2.0）。

实现示例

from google import genai

client = genai.Client(
    api_key="...",
    http_options={
        "headers": {
            "x-goog-api-client": "acme-framework/1.2.0",
        }
    }
)

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -H 'x-goog-api-client: acme-framework/1.2.0' \
    -d '{...}'

from openai import OpenAI

client = OpenAI(
    api_key="...",
    base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
    default_headers={
        "x-goog-api-client": "acme-framework-oai/1.2.0",
    }
)

后续步骤

• 访问库概览，了解 GenAI SDK
• 浏览 API 参考文档
• 阅读 OpenAI 兼容性指南