合作伙伴和库集成

本指南概述了基于 Gemini API 构建库、平台和网关的架构策略。它详细介绍了使用官方 GenAI SDK、直接 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 通常是最简单的路径，因为受支持的 语言中的代码行数最少。

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

福利：

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

权衡因素：

• 依赖项权重和复杂性 ：SDK 有自己的依赖项，这可能会增加软件包大小并可能带来供应链风险。
• 版本控制 ：新的 API 功能通常固定到最低 SDK 版本。 您可能需要向用户推送更新才能访问新功能或模型，这在某些情况下可能需要更改影响用户的传递依赖项。
• 协议限制 ：SDK 仅支持主 API 的 HTTPS 和 Live API 的 WebSocket (WSS)。使用高级 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 的初始化开销为零，可最大限度地减少无服务器函数中的冷启动。

权衡因素：

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

最佳实践

我们公开了一个机器可读的规范，您可以使用该规范为您的库生成类型定义，从而避免手动编写。在构建流程中下载规范，生成类型，然后发布编译后的代码。

• 端点 ：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 的架构并非 1:1 映射，因此依赖兼容性层会引入一些复杂性，需要额外的实现工作才能解决，例如将用户“搜索”工具映射到正确的平台工具。 如果您需要大量特殊情况处理，那么为每个平台使用专用 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-3.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 兼容性指南