このページは Cloud Translation API によって翻訳されました。

Search API によるグラウンディング

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 が指定されています。
重要: デプロイ後のトリガー URL の形式は https://....run.app です。次の手順で、この形式を API Gateway 構成に使用します。

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 キーを作成して制限する手順は次のとおりです。
1. Google Cloud コンソールで、[API Gateway / API を有効にする] ページに移動します。
  [API Gateway API / API を有効にする] に移動
2. API Gateway API が有効になっていない場合は、[起動] をクリックし、[有効にする] をクリックします。
3. [認証情報] を選択します。
4. [認証情報を作成] をクリックし、[API キー] を選択します。
5. [キーを表示] をクリックし、生成された API キーをコピーします。鍵を安全な場所に保管してください。このキーは Gemini で使用されます。
6. [API キーを編集] をクリックするか、キー名をクリックします。
7. [API の制限] セクションで、次の操作を行います。
  1. [キーを制限] オプションを選択します。
  2. API Gateway マネージドサービスを選択します。API の名前（Custom Search API for Gemini Grounding API など）にする必要があります。
  3. キーが含まれていない場合、またはこのキーを使用して API でゲートウェイを管理する場合は、API Gateway API（apigateway.googleapis.com）が選択されていることを確認します。グラウンディングの場合、キーは API Gateway でホストされている特定の API サービスにアクセスする必要があります。
  注: 通常、管理には別のキーまたはサービスアカウントが使用されます。
8. [保存] をクリックします。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 がグラウンディングされたレスポンスを生成する能力に悪影響を及ぼします。

次のステップ

検索によるグラウンディング。