עיגון באמצעות ה-API של החיפוש

אתם יכולים לחבר את Gemini למקורות נתונים חיצוניים באמצעות עיגון עם ה-API של החיפוש. כך תוכלו להשתמש בכל שירות חיפוש כמקור לעיגון התשובות של Gemini, כדי לוודא שהתשובות מבוססות על המידע העדכני והרלוונטי ביותר מהמערכות שלכם. האפשרות הזו שימושית במיוחד לנתונים ספציפיים לארגון שלא זמינים לציבור.

בדף הזה מוסבר איך להגדיר ולהשתמש בהארקה באמצעות כל API של חיפוש עם Gemini.

איך עיגון בנתונים באמצעות Search API פועל

כשמבצעים Grounding באמצעות חיפוש API, ‏ Gemini יכול לשלוח שאילתה לנקודת קצה ל-API חיצונית שאתם מספקים. כך Gemini יכול להשתמש בפונקציונליות של החיפוש המותאם אישית ככלי לשיפור התשובות שלו. הוא מאפשר אינטראקציות דינמיות יותר שמודעות להקשר, כי המודל יכול לחפש מידע ממקורות הנתונים שציינתם כשצריך.

במהלך בקשה ליצירה, Gemini יכול לבצע קריאה לנקודת קצה ל-API החיצוני עם שאילתת חיפוש. ה-API צריך להחזיר קטעי נתונים רלוונטיים. ‫Gemini משתמש בקטעי המידע האלה כמקור אמת כדי ליצור תשובה מדויקת ומבוססת יותר.

אפשר לשלב עיגון בנתונים באמצעות ה-API של החיפוש עם מקורות עיגון אחרים, כמו חיפוש Google. בקשת יצירה תומכת בעד 10 מקורות להארקה ובשאילתות מרובות כלים שבהן Gemini יכול להשתמש במקורות מידע שונים כדי ליצור את התשובה הכי טובה שאפשר.

מודלים נתמכים

בקטע הזה מפורטים המודלים שתומכים בהארקה באמצעות Search API.

כדי להרחיב את רשימת המודלים הנתמכים, לוחצים כאן

לפני שמתחילים

כדי להשתמש בהארקה עם ה-API של החיפוש:

  1. מוודאים ש-Agent Platform API מופעל בפרויקט Google Cloud.
  2. אם אתם מתכוונים לפעול לפי מדריך ההגדרה המפורט ליצירת נקודת קצה ל-API של Search, ודאו שGoogle Cloud CLI מותקן ומופעל.

דרישות לשימוש ב-Search API

כדי להשתמש בתשתית החיפוש הקיימת שלכם עם Gemini, נקודת קצה ל-API צריכה לעמוד בדרישות הבאות:

סכימת API

  • HTTP method: ‏ 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: כתובת ה-URL המלאה של נקודת הקצה של API Gateway, לדוגמה https://YOUR_GATEWAY_HOSTNAME/v0/search.
  • ‫apiAuth.apiKeyConfig.apiKeyString: מפתח ה-API שבו Gemini משתמש כדי לבצע אימות מול ה-API שלכם. ‫Gemini מוסיף את המפתח הזה כ-?key=<YOUR_API_KEY> לכתובת ה-URL של נקודת הקצה.

Python

התקנה

pip install --upgrade google-genai

מידע נוסף מופיע ב מאמרי העזרה בנושא SDK.

מגדירים משתני סביבה כדי להשתמש ב-Google Gen AI SDK עם Vertex AI: 

# 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 .
  • ‫MODEL_ID: מזהה המודל של מודל Gemini תואם, כמו gemini-2.5-flash.
  • ‫PROMPT: הוראות הטקסט שרוצים לכלול בהנחיה.
  • ‫EXTERNAL_API_ENDPOINT: כתובת ה-URL המלאה של נקודת הקצה המאובטחת של API Gateway שאליה Gemini שולח קריאות, לדוגמה: https://YOUR_GATEWAY_HOSTNAME/v0/search. נקודת הקצה הזו צריכה לפעול לפי סכימת ה-API שצוינה.

  • ‫EXTERNAL_API_KEY: מפתח ה-API שיצרתם והגדרתם עבור API Gateway. ‫Gemini משתמש במפתח הזה כדי לבצע אימות עם נקודת הקצה שלכם.

    ה-method של ה-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

    הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-ה-CLI של gcloud באמצעות חשבון המשתמש שלכם , על ידי הרצת gcloud CLI init או gcloud CLI auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-ה-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, מריצים את הפקודה 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

    הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud CLI init או gcloud CLI auth login. כדי לבדוק איזה חשבון פעיל, מריצים את הפקודה 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.

יצירת wrapper ל-API חיצוני באמצעות Cloud Functions

פונקציית Cloud יכולה לשמש כמתווך שמקבל שאילתות מ-Gemini, מנפיק שאילתות מתאימות לתשתית החיפוש הקיימת שלכם, כמו מסד נתונים, מנוע חיפוש פנימי או חיפוש וקטורי, ואז מעצב את התוצאות בסכימה ש-Gemini מבין.

מידע נוסף זמין במאמרי העזרה בנושא פונקציות של Cloud Run.

דוגמה להגדרה של Cloud Function‏ (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 מטפל באימות.

אבטחת Cloud Functions באמצעות API Gateway ומפתח API

‫API Gateway מספק נקודת כניסה מאובטחת ומנוהלת ל-Cloud Functions, ומאפשר לאכוף אימות של מפתחות API.

מידע נוסף זמין במאמרי העזרה של API Gateway.

  1. יצירת מפרט OpenAPI‏ (openapi-spec.yaml): בקובץ הזה מוגדר איך API Gateway חושף את Cloud Functions. הוא מציין ששער הכניסה מצפה לבקשת POST בנתיב /v0/search ודורש מפתח API שנשלח כפרמטר שאילתה בשם key.

    ‫
    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: אחרי שמחליפים את המשתנים הבאים, מריצים את הפקודות ב-CLI של gcloud:

    • ‫YOUR_PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
    • ‫YOUR_REGION: האזור Google Cloud שבו השתמשתם ב-Cloud Functions, כמו 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

    אפשר להשתמש בשם המארח כדי ליצור את כתובת ה-URL המלאה של נקודת הקצה של 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 / Enable APIs

    2. אם API Gateway API לא מופעל, לוחצים על Launch ואז על Enable.

    3. לוחצים על Credentials (פרטי כניסה).

    4. לוחצים על Create credentials ובוחרים באפשרות API key.

    5. לוחצים על Show key ומעתיקים את מפתח ה-API שנוצר. מאחסנים את המפתח במקום בטוח. המפתח הזה משמש את Gemini.

    6. לוחצים על עריכת מפתח API או על שם המפתח.

    7. בקטע API restrictions, מבצעים את הפעולות הבאות:

      1. בוחרים באפשרות Restrict key (הגבלת המפתח).

      2. בוחרים את השירות המנוהל של API Gateway. השם שלו צריך להיות השם של ה-API, למשל Custom Search API for Gemini Grounding API.

      3. אם המפתח לא נכלל או שאתם מתכוונים לנהל את השער באמצעות ה-API באמצעות המפתח הזה, ודאו שAPI Gateway API (apigateway.googleapis.com) נבחר. כדי להשתמש ב-grounding, למפתח צריך להיות גישה לשירות ה-API הספציפי שלכם שמארח API Gateway.

    8. לוחצים על Save. נקודת הקצה של API Gateway מאובטחת, וכשמשתמשים בה צריך להעביר את מפתח ה-API כפרמטר של שאילתה. לדוגמה:

      https://custom-search-gateway-UNIQUE_ID.nw.gateway.dev/v0/search?key=YOUR_GENERATED_API_KEY

שיקולים לשימוש ב-Search API

כדי לבחור את ה-API המתאים לחיפוש, כדאי לעיין בשיקולים הבאים:

  • איכות קטע המידע: הטקסט של קטע המידע שמוחזר על ידי ה-API הוא קריטי. הוא צריך להיות תמציתי אבל מספיק אינפורמטיבי כדי ש-Gemini יוכל להשתמש בו כבסיס עובדתי לתשובה שלו.
  • זמן אחזור: ה-API של החיפוש צריך להגיב במהירות. חביון גבוה ב-API מאריך את זמן התגובה הכולל מ-Gemini.
  • טיפול בשגיאות: מטמיעים טיפול בשגיאות ב-Cloud Functions או ב-Search API. אם ה-API שלכם מחזיר שגיאות לעיתים קרובות או שזמן האחזור שלו ארוך מדי, הדבר פוגע ביכולת של Gemini ליצור תשובות מבוססות-קרקע.

המאמרים הבאים