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

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

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

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

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

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

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

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

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

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

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

כדי להשתמש ב-grounding עם Search API:

  1. מוודאים ש-Agent Platform API מופעל בפרויקט ב- Google Cloud.
  2. אם אתם מתכוונים לפעול לפי המדריך המפורט ליצירת נקודת קצה חדשה ל-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.

שימוש ב-Grounding with Google 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 Functions יכולה לפעול כמתווכת שמקבלת שאילתות מ-Gemini, שולחת שאילתות מתאימות לתשתית החיפוש הקיימת (למשל מסד נתונים, מנוע חיפוש פנימי או חיפוש וקטורי) ואז מעצבת את התוצאות בסכימה ש-Gemini מבין.

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

הגדרה לדוגמה של פונקציה של Cloud Functions ‏ (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.

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

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

    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) נבחרה. כדי לבצע ביסוס, המפתח צריך גישה לשירות ה-API הספציפי שלכם שמתארח ב-API Gateway.

    8. לוחצים על Save. נקודת הקצה של 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 או ב-Search API. אם ה-API מחזיר שגיאות או חורג מהזמן הקצוב לעיתים קרובות, זה פוגע ביכולת של Gemini ליצור תשובות מבוססות-קרקע.

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