# 合作伙伴与库集成

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

如果您正在为其他开发人员构建工具（例如开源框架、企业网关或 SaaS 聚合器），并且需要优化依赖性卫生、捆绑包大小或功能奇偶校验，请使用本指南。

## 什么是合作伙伴整合？  {% #overview %}

注意：如果您正在构建最终用户应用程序（例如，客户支持机器人、旅行计划程序），请跳过本指南并使用 [Gemini API 入门指南](/docs/get-started)。的 [GenAI SDK](/docs/libraries) 是您的推荐选择。

合作伙伴是在 Gemini API 和最终用户开发人员之间构建集成的任何人。我们将合作伙伴分为四种原型。确定您最匹配的哪一个将帮助您选择正确的集成路径。

#### 生态系统框架  {% #ecosystem-framework %}

* **你是谁：** 开源框架（例如 LangChain、LlamaIndex、Spring AI）或特定语言客户端的维护者。

* **您的目标：** 广泛的兼容性。您希望您的库可以在用户选择的任何环境中工作，而不会造成冲突。

#### 运行时和边缘平台  {% #runtime-and-edge-platform %}

* **你是谁：** 代码执行发生在受限环境中的 SaaS 平台、AI 网关或云基础设施提供商（例如 Vercel、Cloudflare、Zapier）。

* **您的目标：** 性能。您需要低延迟、最小的捆绑包大小和快速冷启动。

#### 聚合器  {% #aggregator %}

* **你是谁：** 平台、代理或内部“模型花园”将许多不同的 LLM 提供商（例如 OpenAI、Anthropic、Google）的访问标准化为单个界面。

* **您的目标：** 可移植性和统一性。

#### 企业网关  {% #enterprise-gateway %}

* **你是谁：** 大公司的内部平台工程团队为数百名内部开发人员构建“黄金路径”。

* **您的目标：** 标准化、治理和统一认证。

## 比较一目了然  {% #comparison %}

**全球最佳实践：** 所有合作伙伴必须发送 [`x-goog-api-client`
标头](/docs/partner-integration#client-id) 无论选择的路径如何。

{% doc-table %}
{% doc-row header="true" %}
{% doc-cell %}
如果你是...
{% /doc-cell %}

{% doc-cell %}
推荐路径
{% /doc-cell %}

{% doc-cell %}
主要优点
{% /doc-cell %}

{% doc-cell %}
关键权衡
{% /doc-cell %}

{% doc-cell %}
最佳实践
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**企业网关、生态系统框架**
{% /doc-cell %}

{% doc-cell %}
**[Google GenAI SDK](/docs/partner-integration#genai-sdk)**
{% /doc-cell %}

{% doc-cell %}
**Gemini Enterprise Agent Platform 奇偶校验和速度。** 对类型、身份验证和复杂功能（例如文件上传）的内置处理。无缝迁移到 Google Cloud。
{% /doc-cell %}

{% doc-cell %}
**依赖性权重。** 传递依赖关系可能很复杂并且超出您的控制范围。仅限于支持的语言（Python/Node/Go/Java）。
{% /doc-cell %}

{% doc-cell %}
**锁定版本。** 将 SDK 版本固定在内部基础映像中，以确保跨团队的稳定性。
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**生态系统框架、边缘平台和聚合器**
{% /doc-cell %}

{% doc-cell %}
**[直接 API](/docs/partner-integration#rest)**

*（休息/gRPC）*
{% /doc-cell %}

{% doc-cell %}
**零依赖。** 您可以控制 HTTP 客户端和确切的包大小。完全访问所有 API 和模型功能。
{% /doc-cell %}

{% doc-cell %}
**开发人员开销高。** JSON 结构可以深度嵌套，并且需要严格的手动验证和类型检查。
{% /doc-cell %}

{% doc-cell %}
**使用 OpenAPI 规范。** 使用我们的官方规范自动生成类型，而不是手动编写。
{% /doc-cell %}
{% /doc-row %}

{% doc-row header="false" %}
{% doc-cell %}
**使用仅需要基于文本的工作流程的 OpenAI SDK 的聚合器**

*（针对旧版可移植性进行优化）*
{% /doc-cell %}

{% doc-cell %}
**[OpenAI 兼容性](/docs/partner-integration#openai)**
{% /doc-cell %}

{% doc-cell %}
**即时便携。** 重用现有的 OpenAI 兼容代码或库。
{% /doc-cell %}

{% doc-cell %}
**特色天花板。** 特定于型号的功能（本机视频、缓存）可能不可用。
{% /doc-cell %}

{% doc-cell %}
**迁移计划。** 使用它进行快速验证，但计划升级到 Direct API 以获得完整的 API 功能。
{% /doc-cell %}
{% /doc-row %}
{% /doc-table %}

## Google GenAI SDK 集成  {% #genai-sdk %}

对于框架，实施 [Google GenAI SDK](/docs/libraries)
考虑到支持语言中的代码行数最少，通常是最简单的路径。

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

**好处：**

* **Gemini Enterprise Agent Platform迁移的统一接口：** 内部开发人员通常使用 API 密钥 (Gemini API) 进行原型设计并部署到 Gemini Enterprise Agent Platform (IAM) 以实现生产合规性。 SDK 抽象了这些身份验证差异。同样，对于框架，您可以实现一个代码路径并支持两组用户。

* **客户端助手：** SDK 包含惯用的实用程序，可减少复杂任务的样板文件。

* *示例：* 配套 `PIL` 直接在提示中显示图像对象，自动函数调用，以及综合类型。

* **零日功能访问：** 新的 API 功能可在发布时通过 SDK 获得。

* **改进的代码生成支持：** 本地 SDK 安装向编码助手（例如 Cursor、Copilot）公开类型定义和文档字符串。与生成原始 REST 请求相比，此上下文提高了代码生成的准确性。

**权衡：**

* **依赖权重和复杂性：** SDK 具有自己的依赖项，这可能会增加捆绑包的大小并增加潜在的供应链风险。

* **版本控制：** 新的 API 功能通常固定在最低 SDK 版本上。您可能需要向用户推送更新以访问新功能或模型，在某些情况下可能需要更改影响用户的传递依赖项。

* **协议限制：** SDK 仅支持主 API 的 HTTPS 和 Live API 的 WebSocket (WSS)。使用高级 SDK 客户端不支持 gRPC。

* **语言支持：** SDK 支持 *当前* 语言版本。如果您需要支持 EOL 版本（例如 Python 3.9），则需要维护一个分支。

**最佳实践：**

* **锁定版本：** 将 SDK 版本固定在内部基础映像中，以确保跨团队的稳定性。

## 直接 API 集成  {% #rest %}

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

**好处：**

* **全功能访问：** 与 OpenAI 兼容层不同，使用 API 直接启用 Gemini 特定功能，例如上传到文件 API、创建内容缓存和使用双向 Live API。

* **最小依赖性：** 在依赖关系因大小或审核成本而敏感的环境中。直接通过标准库使用 API `fetch` 或者通过像这样的包装 `httpx` 确保您的库保持轻量级。

* **语言不可知论：** 这是 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 %}

如果您的平台优先考虑统一架构（OpenAI 聊天完成）而不是特定于模型的功能，那么这是您最快的路线。

**好处：**

* **低摩擦：** 您通常可以通过更改来添加 Gemini 支持 `baseURL`
  和 `apiKey`。这是集成“自带密钥”实现的快速方法，无需编写新代码即可添加 Gemini 支持。

* **限制条件：** 仅当您仅限于 OpenAI SDK 并且不需要高级 Gemini 功能（例如文件 API），或者使用 Google 搜索手动添加对事实依据等工具的支持时，才建议使用此路径。

**权衡：**

* **功能限制：** 兼容层对核心 Gemini 功能提供了限制。可用的服务器端工具因平台而异，可能需要手动处理才能与 Gemini API 工具配合使用。

* **翻译开销：** 由于 OpenAI 架构未将 1:1 映射到 Gemini 的架构，因此依赖兼容性层会带来一些复杂性，需要额外的实现工作来解决，例如将用户“搜索”工具映射到正确的平台工具。如果您需要大量特殊外壳，那么为每个平台使用专用的 SDK 或 API 可能更有价值。

**最佳实践**

如果可能，直接与 Gemini API 集成。但是，为了获得最大兼容性，请考虑使用一个能够识别不同提供程序并可以为您处理工具和消息映射的库。

## 所有合作伙伴的最佳实践：客户识别  {% #client-id %}

当调用 Gemini API 作为平台或库时，您必须使用 `x-goog-api-client` 标头。

这使得 Google 能够识别您的特定流量段，如果您的库产生特定的错误模式，我们可以帮助您进行调试。

使用格式 `company-product/version` (e.g., `acme-framework/1.2.0`).

### 实施示例  {% #client-examples %}

{% tabs %}
{% tab label="GenAI SDK" %}
通过提供 API 客户端，SDK 会自动将您的自定义标头附加到其内部标头。

```py
from google import genai

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

{% tab label="直接 API（休息）" %}
```posix-terminal
  curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
      -H 'Content-Type: application/json' \
      -H "x-goog-api-key: $GEMINI_API_KEY" \
      -H 'x-goog-api-client: acme-framework/1.2.0' \
      -d '{...}'
```
{% /tab %}

{% tab label="OpenAI SDK" %}
```py
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",
    }
)
```
{% /tab %}
{% /tabs %}

## 后续步骤  {% #next %}

* 参观 [库概述](/docs/libraries) 了解 GenAI SDK

* 浏览 [API参考](/api-reference)

* 阅读 [OpenAI 兼容性指南](/docs/openai)
