以搜尋 API 建立基準

您可以使用搜尋 API 建立基準，將 Gemini 連結至外部資料來源。這樣一來，您就能使用任何搜尋服務做為 Gemini 的基準來源，確保回覆內容是根據系統中最新、最相關的資訊。這項功能特別適合用於非公開的企業專屬資料。

本頁面說明如何設定及使用任何搜尋 API，搭配 Gemini 建立基準。

如何使用 Search API 建立基準

使用搜尋 API 建立基準時，Gemini 可以查詢您提供的外部 API 端點。這樣 Gemini 就能使用自訂搜尋功能，提供更優質的回覆。模型可視需要從指定資料來源中尋找資訊，因此能提供更動態且符合情境的互動。

在生成要求期間，Gemini 可以使用搜尋查詢呼叫外部 API 端點。API 應傳回相關資料片段。Gemini 會將這些摘要做為可靠的資訊來源，生成更準確且有依據的回覆。

您可以使用搜尋 API 建立基準，並與 Google 搜尋等其他基準來源結合。生成要求最多支援 10 個基準來源和多工具查詢，Gemini 可利用不同的資訊來源生成最佳答案。

支援的模型

本節列出支援使用 Search API 建立基準的模型。

按一下即可展開支援的模型

事前準備

如要搭配使用基準建立功能和 Search API，請按照下列步驟操作：

  1. 確認 Google Cloud專案已啟用 Agent Platform API。
  2. 如果您打算按照詳細設定指南建立新的搜尋 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。

使用 Search API 建立基準，並搭配相容的端點

如果您已有符合結構定義和驗證需求的 API 端點，可以直接在 Gemini API 呼叫中設定。

設定 externalApi 工具

向 Gemini API 發出要求時，請加入 tools 參數，並為 externalApi 設定檢索工具。重要欄位包括：

  • api_spec: "SIMPLE_SEARCH"：指示 Gemini 使用預先定義的輸入和輸出結構定義。
  • endpoint：API Gateway 端點的完整網址，例如 https://YOUR_GATEWAY_HOSTNAME/v0/search。
  • apiAuth.apiKeyConfig.apiKeyString：Gemini 用來向 API 驗證的 API 金鑰。Gemini 會將這個金鑰附加為端點網址的 ?key=<YOUR_API_KEY>。

Python

安裝

pip install --upgrade google-genai

詳情請參閱 SDK 參考文件。

設定環境變數，以便透過 Vertex AI 使用 Google 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_ENTERPRISE=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.5-flash。
  • PROMPT：提示中要包含的文字指令。
  • EXTERNAL_API_ENDPOINT：Gemini 呼叫的安全 API Gateway 端點完整網址，例如 https://YOUR_GATEWAY_HOSTNAME/v0/search。這個端點必須遵循指定的 API 架構。

  • EXTERNAL_API_KEY：您為 API Gateway 產生及設定的 API 金鑰。Gemini 會使用這組金鑰向端點進行驗證。

    HTTP 方法和網址：

    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": {
    "..."
  }
}

設定搜尋 API 端點

如果沒有符合需求的現有 API 端點，本節將引導您使用 Cloud Functions 和 API Gateway 設定端點。

使用 Cloud Functions 建立外部 API 包裝函式

Cloud 函式可做為中介，接收 Gemini 的查詢，向現有搜尋基礎架構 (例如資料庫、內部搜尋引擎或向量搜尋) 發出適當查詢，然後將結果格式化為 Gemini 可理解的結構定義。

詳情請參閱 Cloud Run functions 說明文件。

Cloud 函式設定範例 (Python)

這個範例使用硬式編碼產品清單進行示範。您需要將資料擷取邏輯替換為對實際搜尋系統的呼叫。

  1. 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)

  2. requirements.py

    functions-framework>=3.0.0
Flask>=2.0.0

  3. 部署：前往包含 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。
    • 指定 --allow-unauthenticated 是因為 API Gateway 會處理驗證。

使用 API Gateway 和 API 金鑰保護 Cloud Functions

API Gateway 為 Cloud Functions 提供安全、受控管的進入點，並可強制執行 API 金鑰驗證。

詳情請參閱 API Gateway 說明文件。

  1. 建立 OpenAPI 規格 (openapi-spec.yaml)：這個檔案定義 API Gateway 公開 Cloud Functions 的方式。這會指定閘道預期 POST 要求傳送至 /v0/search 路徑，並要求以名為 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

  2. 部署 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

    部署後，主機名稱 (閘道網址) 的格式如下：

    https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev

    您可以使用主機名稱，建構 Gemini 的完整端點網址。例如：

    https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search

  3. 建立並限制 API 金鑰：您必須建立 API 金鑰，Gemini 才能存取 API Gateway 端點。詳情請參閱「管理 API 金鑰」。

    如要建立及限制 API 金鑰，請按照下列步驟操作：

    1. 在 Google Cloud 控制台，前往「API Gateway / Enable APIs」(API Gateway/啟用 API) 頁面。

      前往 API Gateway API / Enable APIs

    2. 如果 API Gateway API 尚未啟用，請依序點選「Launch」(啟動) 和「Enable」(啟用)。

    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 金鑰做為查詢參數傳遞。例如：

      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 生成有依據回覆的能力造成負面影響。

後續步驟