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

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

検索 API を使用してグラウンディングすることで、Gemini を外部データソースに接続できます。これにより、任意の検索サービスを Gemini のグラウンディングソースとして使用できます。これにより、回答がシステムの最新かつ最も関連性の高い情報に基づいていることを確認できます。これは、一般公開されていない企業固有のデータに特に役立ちます。

このページでは、Gemini で任意の検索 API を使用してグラウンディングを構成して使用する方法について説明します。

検索 API を使用したグラウンディングの仕組み

検索 API を使用してグラウンディングすると、Gemini はユーザーが指定した外部 API エンドポイントにクエリを実行できます。これにより、Gemini はカスタム検索機能をツールとして使用して、回答を強化できます。モデルは必要に応じて指定されたデータソースから情報を検索できるため、より動的でコンテキストを認識したやり取りが可能になります。

生成リクエスト中に、Gemini は検索クエリを使用して外部 API エンドポイントを呼び出すことができます。API は、関連するデータスニペットを返す必要があります。Gemini は、これらのスニペットを信頼できる情報源として使用し、より正確でグラウンディングされた回答を生成します。

検索 API を使用したグラウンディングを、Google 検索などの他のグラウンディングソースと組み合わせることができます。生成リクエストは、最大 10 個のグラウンディングソースとマルチツールクエリをサポートしています。Gemini は、さまざまな情報ソースを活用して、可能な限り最適な回答を生成できます。

サポートされているモデル

次のモデルは、API でグラウンディングをサポートしています。

詳細については、Gemini モデルをご覧ください。

始める前に

検索 API でグラウンディングを使用する手順は次のとおりです。

Google Cloudプロジェクトで Vertex AI API が有効になっていることを確認します。
新しい検索 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 エンドポイントは空の配列を返す必要があります。

認証

検索 API を使用したグラウンディングでは、API キーの使用がサポートされています。これにより、API エンドポイントが保護されます。Gemini は、この API キーを key という名前のクエリパラメータとして送信します。

互換性のあるエンドポイントで検索 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 に追加します。

REST

リクエストのデータを使用する前に、次のように置き換えます。

LOCATION: リクエストを処理するリージョン（us-central1 など）。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。
MODEL_ID: 互換性のある Gemini モデルのモデル ID（gemini-2.0-flash-001 など）。
USER_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/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

リクエストの本文（JSON）:

  {
  "contents": [{
      "role": "user",
      "parts": [{
          "text": "USER_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 にログインしているか、自動的に gcloud CLI にログインする Cloud Shell を使用していることを前提としています。アクティブなアカウントを確認するには、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": {
    "..."
  }
}

検索 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 / Enable APIs] ページに移動します。
  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

検索 API に関する考慮事項

検索 API を選択する際は、次の考慮事項を確認してください。

スニペットの品質: API から返されるスニペットテキストは非常に重要です。Gemini が回答の事実に基づく根拠として使用できるほど、簡潔かつ有益なものにする必要があります。
レイテンシ: 検索 API は迅速に応答する必要があります。API のレイテンシが高いと、Gemini からの全体的な応答時間が長くなります。
エラー処理: Cloud Functions または検索 API で堅牢なエラー処理を実装します。API でエラーやタイムアウトが頻繁に発生すると、Gemini がグラウンディングされたレスポンスを生成する能力に悪影響を及ぼします。

次のステップ

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