Search API を使用してグラウンディングすることで、Gemini を外部データソースに接続できます。これにより、任意の検索サービスを Gemini のグラウンディング ソースとして使用できます。これにより、レスポンスがシステムの最新かつ最も関連性の高い情報に基づいていることを確認できます。これは、一般公開されていない企業固有のデータに特に役立ちます。
このページでは、Gemini で任意の Search API を使用してグラウンディングを構成して使用する方法について説明します。
Search API を使用したグラウンディングの仕組み
Search API を使用してグラウンディングすると、Gemini はユーザーが指定した外部 API エンドポイントにクエリを実行できます。これにより、Gemini はカスタム検索機能をツールとして使用して、レスポンスを強化できます。モデルが必要に応じて指定されたデータソースから情報を検索できるため、より動的でコンテキスト アウェアなインタラクションが可能になります。
生成リクエスト中に、Gemini は検索クエリを使用して外部 API エンドポイントを呼び出すことが可能です。API は、関連するデータ スニペットを返す必要があります。Gemini は、これらのスニペットを信頼できる情報源として使用し、より正確なグラウンディングされたレスポンスを生成します。
Search API を使用したグラウンディングを、Google 検索などの他のグラウンディング ソースと組み合わせることが可能です。生成リクエストは、最大 10 個のグラウンディング ソースとマルチツール クエリをサポートしています。Gemini は、さまざまな情報ソースを活用して、可能な限り最適なレスポンスを生成できます。
サポートされているモデル
このセクションでは、検索 API によるグラウンディングをサポートするモデルを示します。
- Gemini 2.5 Flash (プレビュー)
- Gemini 2.5 Flash-Lite (プレビュー)
- Gemini 2.5 Flash-Lite
- Live API ネイティブ音声を使用した Gemini 2.5 Flash (プレビュー)
- Live API を使用した Gemini 2.0 Flash (プレビュー)
- Gemini 2.5 Pro
- Gemini 2.5 Flash
- Gemini 2.0 Flash
始める前に
Search API でグラウンディングを使用する手順は次のとおりです。
- Google Cloudプロジェクトで Vertex AI API が有効になっていることを確認します。
- 新しい Search API エンドポイントを作成するための詳細な設定ガイドに沿って作業する場合は、Google Cloud CLI がインストールされ、初期化されていることを確認してください。
Search API の要件
既存の検索インフラストラクチャを Gemini で使用するには、API エンドポイントが次の要件を満たしている必要があります。
API スキーマ
- HTTP メソッド:
POST
リクエスト本文(Gemini から API へ):
{ "query": "the user's search query string" }
レスポンス本文(API から Gemini へ): オブジェクトの JSON 配列。各オブジェクトは検索結果を表し、snippet フィールドと uri フィールドを含める必要があります。
[ { "snippet": "A text snippet containing the answer or relevant information.", "uri": "A URI/URL linking to the source of the information, or a relevant identifier." }, { "snippet": "Another piece of information.", "uri": "https://example.com/another-source" } ]
結果が見つからない場合、API エンドポイントは空の配列を返すはずです。
認証
Search API を使用したグラウンディングでは、API キーの使用がサポートされています。これにより、API エンドポイントが保護されます。Gemini は、この API キーを key
という名前のクエリ パラメータとして送信します。
互換性のあるエンドポイントで Search API を使用してグラウンディングを使用する
スキーマと認証の要件を満たす API エンドポイントがすでにある場合は、Gemini API 呼び出しで直接構成できます。
externalApi
ツールを構成する
Gemini API へのリクエストを行う場合は、externalApi
用に構成された取得ツールで tools パラメータを指定します。主なフィールドは次のとおりです。
api_spec: "SIMPLE_SEARCH"
: 事前定義済みの入力スキーマと出力スキーマを使用するように Gemini に指示します。endpoint
: API Gateway エンドポイントへの完全な URL(https://YOUR_GATEWAY_HOSTNAME/v0/search
など)。apiAuth.apiKeyConfig.apiKeyString
: Gemini が API との認証に使用する API キー。Gemini は、このキーを?key=<YOUR_API_KEY>
としてエンドポイント URL に追加します。
Python
インストール
pip install --upgrade google-genai
詳しくは、SDK リファレンス ドキュメントをご覧ください。
Vertex AI で Gen AI SDK を使用するための環境変数を設定します。
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
from google import genai
from google.genai.types import (
GenerateContentConfig,
ExternalApi,
Retrieval,
Tool,
HttpOptions,
)
client = genai.Client(http_options=HttpOptions(api_version="v1"))
# Replace with your API details
EXTERNAL_API_ENDPOINT = "YOUR_EXTERNAL_API_ENDPOINT" # e.g., https://YOUR_GATEWAY_HOSTNAME/v0/search
EXTERNAL_API_KEY = "YOUR_EXTERNAL_API_KEY"
tool = Tool(
retrieval=Retrieval(
external_api=ExternalApi(
api_spec="SIMPLE_SEARCH",
endpoint=EXTERNAL_API_ENDPOINT,
api_auth={
"apiKeyConfig": {
"apiKeyString": EXTERNAL_API_KEY
}
}
)
)
)
response = client.models.generate_content(
model="gemini-2.5-flash", # Or another supported model
contents="What can you tell me about product Y based on my API?", # Your query
config=GenerateContentConfig(
tools=[tool],
),
)
print(response.text)
REST
リクエストのデータを使用する前に、次のように置き換えます。
- LOCATION: リクエストを処理するリージョン。グローバル エンドポイントを使用するには、エンドポイント名からロケーションを除外し、リソースのロケーションを
global
に構成します。 - PROJECT_ID: 実際の Google Cloud プロジェクト ID。
- MODEL_ID: 互換性のある Gemini モデルのモデル ID(
gemini-2.0-flash-001
など)。 - PROMPT: プロンプトに含める指示のテキスト。
- EXTERNAL_API_ENDPOINT: Gemini が呼び出す保護された API Gateway エンドポイントの完全な URL(
https://YOUR_GATEWAY_HOSTNAME/v0/search
など)。このエンドポイントは、指定された API スキーマに準拠している必要があります。 EXTERNAL_API_KEY: API Gateway 用に生成して構成した API キー。Gemini はこのキーを使用してエンドポイントに対する認証を行います。
HTTP メソッドと URL:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
リクエストの本文(JSON):
{ "contents": [{ "role": "user", "parts": [{ "text": "PROMPT" }] }], "tools": [{ "retrieval": { "externalApi": { "api_spec": "SIMPLE_SEARCH", "endpoint": "EXTERNAL_API_ENDPOINT", "apiAuth": { "apiKeyConfig": { "apiKeyString": "EXTERNAL_API_KEY" } } } } }] }
リクエストを送信するには、次のいずれかのオプションを使用します。
curl
次のコマンドでは、gcloud CLI init または gcloud CLI auth login を実行するか、自動的に gcloud CLI にログインする Cloud Shell を使用して、ユーザー アカウントで gcloud CLI にログインしていることを前提とします。アクティブなアカウントを確認するには、gcloud CLI auth list を実行します。
リクエスト本文を
request.json
という名前のファイルに保存して、次のコマンドを実行します。curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d @request.json \ "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"
Powershell
次のコマンドは、gcloud CLI init または gcloud CLI auth login を実行して、ユーザー アカウントで gcloud CLI にログインしていることを前提としています。アクティブなアカウントを確認するには、gcloud CLI auth list を実行します。
リクエスト本文を
request.json
という名前のファイルに保存して、次のコマンドを実行します。$cred = gcloud auth print-access-token $headers = @{ "Authorization" = "Bearer $cred" } Invoke-WebRequest ` -Method POST ` -Headers $headers ` -ContentType: "application/json; charset=utf-8" ` -InFile request.json ` -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
{ "candidates": [ { "content": { "role": "model", "parts": [ { "text": "You can make an appointment on the website https://dmv.gov/" } ] }, "finishReason": "STOP", "safetyRatings": [ "..." ], "groundingMetadata": { "retrievalQueries": [ "How to make appointment to renew driving license?" ], "groundingChunks": [ { "retrievedContext": { "uri": "https://...", "snippet": "Snippet text about driving license renewal" } } ], "groundingSupport": [ { "segment": { "startIndex": 25, "endIndex": 147 }, "segment_text": "ipsum lorem ...", "supportChunkIndices": [1, 2], "confidenceScore": [0.9541752, 0.97726375] }, { "segment": { "startIndex": 294, "endIndex": 439 }, "segment_text": "ipsum lorem ...", "supportChunkIndices": [1], "confidenceScore": [0.9541752, 0.9325467] } ] } } ], "usageMetadata": { "..." } }
Search API エンドポイントを設定する
要件を満たす既存の API エンドポイントがない場合は、このセクションで Cloud Functions と API Gateway を使用してエンドポイントを設定する方法について説明します。
Cloud Functions を使用して外部 API ラッパーを作成する
Cloud Functions は、Gemini からクエリを受け取り、データベース、内部検索エンジン、ベクトル検索などの既存の検索インフラストラクチャに適切なクエリを発行し、Gemini が理解できるスキーマで結果をフォーマットする仲介役として機能します。
詳細については、Cloud Run functions のドキュメントをご覧ください。
Cloud Functions の設定例(Python)
この例では、デモ用にハードコードされた商品リストを使用しています。データ取得ロジックを、実際の検索システムへの呼び出しに置き換える必要があります。
main.py
import functions_framework import json from flask import jsonify @functions_framework.http def custom_search_wrapper(request): """ HTTP Cloud Function to provide a minimal, fixed response for Gemini grounding. """ if request.method != 'POST': return 'Only POST requests are accepted', 405 request_json = request.get_json(silent=True) if not request_json or 'query' not in request_json: return jsonify({"error": "Invalid request. JSON body with 'query' field is required."}), 400 user_query = request_json['query'] print(f"Received query: '{user_query}'. Responding with fixed data.") # --- FIXED RESPONSE --- # This is a hardcoded response. In a real scenario, you would # use the 'user_query' to fetch relevant data. fixed_results = [ { "snippet": "This is a fixed snippet from your custom Search API. The original query was: " + user_query, "uri": "https://example.com/docs/fixed-test-data" }, { "snippet": "Another piece of fixed information to demonstrate the list format.", "uri": "https://example.com/another-fixed-source" } ] # --- END OF FIXED RESPONSE --- return jsonify(fixed_results)
requirements.py
functions-framework>=3.0.0 Flask>=2.0.0
デプロイ:
main.py
とrequirements.txt
を含むディレクトリに移動して、次のコマンドを実行します。gcloud functions deploy custom_search_wrapper \ --runtime python311 \ --trigger-http \ --entry-point custom_search_wrapper \ --region YOUR_REGION \ --allow-unauthenticated \ --gen2
- YOUR_REGION は、選択した Google Cloud リージョン(
us-central1
など)に置き換えます。 - API Gateway が認証を処理するため、
--allow-unauthenticated
が指定されています。
- YOUR_REGION は、選択した Google Cloud リージョン(
API Gateway と API キーを使用して Cloud Functions を保護する
API Gateway は、Cloud Functions への安全なマネージド エントリ ポイントを提供し、API キー認証を適用できます。
詳細については、API Gateway のドキュメントをご覧ください。
OpenAPI 仕様を作成する(
openapi-spec.yaml
): このファイルは、API Gateway が Cloud Functions を公開する方法を定義します。これは、ゲートウェイが/v0/search
パスへのPOST
リクエストを想定しており、key
という名前のクエリ パラメータとして送信される API キーを必要とすることを指定します。swagger: '2.0' info: title: Custom Search API for Gemini Grounding description: Wraps an internal search function, secured by API Key for Gemini. version: 1.0.0 schemes: - https produces: - application/json consumes: - application/json paths: /v0/search: # TODO: This will be part of API endpoint URL change if necessary post: summary: Custom search endpoint for Gemini operationId: customSearchForGemini # TODO: Change if needed x-google-backend: address: YOUR_CLOUD_FUNCTION_TRIGGER_URL # TODO: Replace with your Cloud Function trigger URL parameters: - name: body in: body required: true schema: type: object properties: query: type: string security: - api_key_query: [] responses: '200': description: Search results schema: type: array items: type: object properties: snippet: type: string uri: type: string '400': description: Invalid request '401': description: Unauthorized (Missing or invalid API key) '500': description: Internal server error securityDefinitions: api_key_query: type: apiKey name: key # Gemini will send its API key using this query parameter name in: query
API Gateway をデプロイする: 次の変数を置き換えてから、gcloud CLI コマンドを実行します。
- YOUR_PROJECT_ID: Google Cloud プロジェクト ID。
- YOUR_REGION: Cloud Functions で使用した Google Cloud リージョン(
us-central1
など)。
# 1. Create an API gcloud api-gateway apis create custom-search-gemini-api --project=YOUR_PROJECT_ID # 2. Create an API Config from your OpenAPI spec gcloud api-gateway api-configs create v1 \ --api=custom-search-gemini-api \ --openapi-spec=openapi-spec.yaml \ --project=YOUR_PROJECT_ID \ --display-name="Version 1" # 3. Create a Gateway gcloud api-gateway gateways create custom-search-gateway \ --api=custom-search-gemini-api \ --api-config=v1 \ --location=YOUR_REGION \ --project=YOUR_PROJECT_ID
デプロイ後、ホスト名(ゲートウェイ URL)の形式は次のようになります。
https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev
ホスト名を使用して、Gemini の完全なエンドポイント URL を構築できます。例:
https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search
API キーを作成して制限する: Gemini が API Gateway エンドポイントにアクセスするために使用する API キーを作成する必要があります。詳細については、API キーを管理するをご覧ください。
API キーを作成して制限する手順は次のとおりです。
Google Cloud コンソールで、[API Gateway / API を有効にする] ページに移動します。
API Gateway API が有効になっていない場合は、[起動] をクリックし、[有効にする] をクリックします。
[認証情報] を選択します。
[認証情報を作成] をクリックし、[API キー] を選択します。
[キーを表示] をクリックし、生成された API キーをコピーします。鍵を安全な場所に保管してください。このキーは Gemini で使用されます。
[API キーを編集] をクリックするか、キー名をクリックします。
[API の制限] セクションで、次の操作を行います。
[キーを制限] オプションを選択します。
API Gateway マネージド サービスを選択します。API の名前(
Custom Search API for Gemini Grounding API
など)にする必要があります。キーが含まれていない場合、またはこのキーを使用して API でゲートウェイを管理する場合は、API Gateway API(
apigateway.googleapis.com
)が選択されていることを確認します。グラウンディングの場合、キーは API Gateway でホストされている特定の API サービスにアクセスする必要があります。
[保存] をクリックします。API Gateway エンドポイントは保護されています。API Gateway エンドポイントを使用する場合は、API キーをクエリ パラメータとして渡す必要があります。例:
https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY
Search API に関する考慮事項
Search API を選択する際は、次の考慮事項を確認してください。
- スニペットの品質: API から返されるスニペット テキストは非常に重要です。Gemini がレスポンスに対して事実に基づく根拠として使用できるほど、簡潔かつ有益なものにする必要があります。
- レイテンシ: Search API は迅速に応答する必要があります。API のレイテンシが高いと、Gemini からの全体的なレスポンス時間が長くなります。
- エラー処理: Cloud Functions または Search API で堅牢なエラー処理を実装します。API でエラーやタイムアウトが頻繁に発生すると、Gemini がグラウンディングされたレスポンスを生成する能力に悪影響を及ぼします。