パートナーとライブラリの統合

このガイドでは、Gemini API の上にライブラリ、プラットフォーム、ゲートウェイを構築するためのアーキテクチャ戦略の概要について説明します。公式の GenAI SDK、Direct API（REST/gRPC）、OpenAI 互換レイヤを使用する場合の技術的なトレードオフについて詳しく説明します。

このガイドは、オープンソース フレームワーク、エンタープライズ ゲートウェイ、SaaS アグリゲータなど、他のデベロッパー向けのツールを構築しており、依存関係の衛生状態、バンドルサイズ、機能のパリティを最適化する必要がある場合に役立ちます。

パートナー統合とは

パートナーとは、Gemini API とエンドユーザー デベロッパー間の統合を構築するすべてのユーザーを指します。パートナーは 4 つのアーキタイプに分類されます。どのタイプに最も近いかを特定することで、適切な統合パスを選択できます。

エコシステム フレームワーク

  • 対象者: オープンソース フレームワーク（LangChain、LlamaIndex、Spring AI）または言語固有のクライアント。
  • 目標: 幅広い互換性。ライブラリは、ユーザーが選択した環境で競合を強制することなく動作するようにします。

ランタイムとエッジ プラットフォーム

  • 対象: SaaS プラットフォーム、AI Gateway、クラウド インフラストラクチャ プロバイダ（Vercel、Cloudflare、Zapier など）で、コード実行が制限された環境で行われます。
  • 目標: パフォーマンス。低レイテンシ、最小バンドルサイズ、迅速なコールド スタートが必要な場合。

情報集約サイト

  • 対象者: 多くの異なる LLM プロバイダ（OpenAI、Anthropic、Google など）のアクセスを単一のインターフェースに正規化するプラットフォーム、プロキシ、または内部の「モデル ガーデン」。
  • 目標: 移植性と均一性。

エンタープライズ ゲートウェイ

  • 対象者: 大企業の内部プラットフォーム エンジニアリング チームで、数百人の内部開発者向けに「ゴールデンパス」を構築している方。
  • 目標: 標準化、ガバナンス、統合認証。

主な相違点

グローバル ベスト プラクティス: 選択したパスに関係なく、すべてのパートナーは x-goog-api-client ヘッダーを送信する必要があります。

ユーザーの種類に応じて、以下のようになります。 推奨されるパス 主なメリット 重要なトレードオフ ベスト プラクティス
エンタープライズ ゲートウェイ、エコシステム フレームワーク Google GenAI SDK Vertex のパリティと速度。型、認証、複雑な機能（ファイルのアップロードなど）の組み込み処理。Google Cloud へのシームレスな移行。 依存関係の重み。推移的依存関係は複雑で、制御の範囲外になる可能性があります。サポートされている言語（Python/Node/Go/Java）に限定されます。 バージョンをロックします。内部ベースイメージで SDK バージョンを固定して、チーム間の安定性を確保します。
エコシステム フレームワーク、エッジ プラットフォーム、アグリゲータ Direct API

（REST / gRPC）		 依存関係なし。HTTP クライアントと正確なバンドル サイズを制御します。すべての API とモデル機能に対する完全アクセス権。 デベロッパーのオーバーヘッドが大きい。JSON 構造は深くネストされることがあり、厳密な手動検証と型チェックが必要です。 OpenAPI 仕様を使用します。公式仕様を使用して型生成を自動化し、手動で記述しないようにします。
テキストベースのワークフローのみを必要とする OpenAI SDK を使用するアグリゲータ

（以前の移植性を最適化）		 OpenAI の互換性 即時の移植性。既存の OpenAI 互換コードまたはライブラリを再利用する。 機能の上限。モデル固有の機能（ネイティブ動画、キャッシュ保存）は利用できない場合があります。 Migration plan。迅速な検証にはこれを使用しますが、完全な API 機能を利用するには Direct API にアップグレードすることを計画してください。

Google GenAI SDK の統合

フレームワークの場合、サポートされている言語のコード行数が最も少ないため、Google GenAI SDK を実装するのが最も簡単な方法です。

内部プラットフォーム チームの場合、主な成果物は、プロダクト エンジニアがセキュリティ ポリシーに準拠しながら迅速に作業できる「ゴールデン パス」であることがよくあります。

メリット:

  • Vertex AI 移行用の統合インターフェース: 内部のデベロッパーは、API キー（Gemini API）を使用してプロトタイプを作成し、本番環境のコンプライアンスのために Vertex AI（IAM）にデプロイすることがよくあります。SDK は、これらの認証の違いを抽象化します。フレームワークについても同様に、1 つのコードパスを実装して 2 つのユーザーセットをサポートできます。
  • クライアントサイド ヘルパー: SDK には、複雑なタスクのボイラープレートを削減する慣用的なユーティリティが含まれています。
    • 例: プロンプト、自動関数呼び出し、包括的なタイプで PIL 画像オブジェクトを直接サポートします。
  • リリース当日の機能へのアクセス: 新しい API 機能は、リリース時に SDK を通じて利用できます。
  • コード生成サポートの改善: ローカル SDK のインストールにより、型定義と docstring がコーディング アシスタント（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 を直接使用すると、File API へのアップロード、コンテンツ キャッシュの作成、双方向 Live API の使用など、Gemini 固有の機能を利用できます。
  • 最小限の依存関係: サイズや監査費用が原因で依存関係が重要になる環境。fetch などの標準ライブラリや httpx などのラッパーを介して API を直接使用すると、ライブラリを軽量に保つことができます。
  • 言語に依存しない: 言語制限がないため、Rust、PHP、Ruby など、SDK でカバーされていない言語では、このパスのみが使用されます。
  • パフォーマンス: Direct API には初期化のオーバーヘッドがないため、サーバーレス関数のコールド スタートを最小限に抑えることができます。

トレードオフ:

  • Vertex AI の手動実装: SDK とは異なり、API を直接使用する場合、AI Studio（API キー）と Vertex AI（IAM）の認証の違いは自動的に処理されません。両方の環境をサポートする場合は、個別の認証ハンドラを実装する必要があります。
  • ネイティブ型またはヘルパーがない: リクエスト オブジェクトのコード補完やコンパイル時チェックは、自分で実装しない限り取得できません。クライアントの「ヘルパー」（関数からスキーマへのコンバータなど）がないため、このロジックを手動で記述する必要があります。

ベスト プラクティス

Google は、ライブラリの型定義を生成するために使用できる機械可読仕様を公開しています。これにより、型定義を手動で記述する必要がなくなります。ビルドプロセス中に仕様をダウンロードし、型を生成して、コンパイルされたコードを配布します。

  • エンドポイント: https://generativelanguage.googleapis.com/$discovery/OPENAPI3_0

OpenAI SDK の統合

モデル固有の機能よりも統一されたスキーマ（OpenAI Chat Completions）を優先するプラットフォームの場合は、これが最も迅速な方法です。

メリット:

  • 摩擦が少ない: baseURL と apiKey を変更するだけで、Gemini のサポートを追加できることがよくあります。これは、「Bring Your Own Key」の実装を統合し、新しいコードを記述せずに Gemini のサポートを追加する迅速な方法です。
  • 制約: このパスは、OpenAI SDK に制限されており、File API などの高度な Gemini 機能や、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）。

実装の例

GenAI SDK

API クライアントを提供すると、SDK はカスタム ヘッダーを内部ヘッダーに自動的に追加します。

from google import genai

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

Direct API（REST）

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

OpenAI SDK

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",
    }
)

次のステップ