Grounding con l'API di ricerca

Puoi connettere Gemini alle tue origini dati esterne eseguendo il grounding con l'API di ricerca. In questo modo puoi utilizzare qualsiasi servizio di ricerca come fonte di grounding per Gemini, contribuendo a garantire che le risposte si basino sulle informazioni più recenti e pertinenti dei tuoi sistemi. Questo è particolarmente utile per i dati specifici dell'azienda che non sono disponibili pubblicamente.

Questa pagina spiega come configurare e utilizzare il grounding utilizzando qualsiasi API di ricerca con Gemini.

Come funziona il grounding con l'API di ricerca

Quando esegui il grounding con l'API di ricerca, Gemini può eseguire query su un endpoint API esterno che fornisci. In questo modo, Gemini può utilizzare la tua funzionalità di ricerca personalizzata come strumento per migliorare le sue risposte. Consente interazioni più dinamiche e sensibili al contesto, poiché il modello può cercare informazioni dalle origini dati specificate quando necessario.

Durante una richiesta di generazione, Gemini può effettuare una chiamata all'endpoint API esterno con una query di ricerca. L'API dovrebbe quindi restituire snippet di dati pertinenti. Gemini utilizza questi snippet come fonte di verità per generare una risposta più accurata e fondata.

Puoi combinare il grounding utilizzando l'API di ricerca con altre fonti di grounding, come la Ricerca Google. Una richiesta di generazione supporta fino a 10 fonti di grounding e query multi-strumento in cui Gemini può sfruttare diverse fonti di informazioni per generare la migliore risposta possibile.

Modelli supportati

Questa sezione elenca i modelli che supportano il grounding con l'API di ricerca.

Fai clic per espandere i modelli supportati

Prima di iniziare

Per utilizzare il grounding con l'API di ricerca, segui questi passaggi:

  1. Assicurati che l'API Agent Platform sia abilitata nel tuo progetto Google Cloud.
  2. Se prevedi di seguire la guida dettagliata alla configurazione per creare un nuovo endpoint API di ricerca, assicurati di aver installato e inizializzato Google Cloud CLI.

Requisiti dell'API Search

Per utilizzare l'infrastruttura di ricerca esistente con Gemini, l'endpoint API deve soddisfare i seguenti requisiti:

schema dell'API

  • Metodo HTTP: POST

  • Corpo della richiesta (da Gemini alla tua API):

    {
  "query": "the user's search query string"
}

  • Corpo della risposta (dalla tua API a Gemini): un array di oggetti JSON. Ogni oggetto rappresenta un risultato di ricerca e deve contenere i campi snippet e 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"
  }
]

Se non vengono trovati risultati, l'endpoint API deve restituire un array vuoto.

Autenticazione

Il grounding con l'API di ricerca supporta l'utilizzo della chiave API, che protegge l'endpoint API. Gemini invia questa chiave API come parametro di query denominato key.

Utilizza il grounding con l'API di ricerca con un endpoint compatibile

Se hai già un endpoint API che soddisfa i requisiti di schema e autenticazione, puoi configurarlo direttamente nelle chiamate API Gemini.

Configura lo strumento externalApi

Quando effettui una richiesta all'API Gemini, includi il parametro tools con uno strumento di recupero configurato per externalApi. I campi chiave includono:

  • api_spec: "SIMPLE_SEARCH": indica a Gemini di utilizzare lo schema di input e output predefinito.
  • endpoint: l'URL completo dell'endpoint API Gateway, ad esempio https://YOUR_GATEWAY_HOSTNAME/v0/search.
  • apiAuth.apiKeyConfig.apiKeyString: la chiave API che Gemini utilizza per l'autenticazione con la tua API. Gemini aggiunge questa chiave come ?key=<YOUR_API_KEY> all'URL dell'endpoint.

Python

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Google Gen AI con 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

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • LOCATION: la regione in cui elaborare la richiesta. Per utilizzare l'endpoint globale, escludi la località dal nome dell'endpoint e configura la località della risorsa su global.
  • PROJECT_ID: l'ID progetto Google Cloud .
  • MODEL_ID: l'ID modello di un modello Gemini compatibile, ad esempio gemini-2.5-flash.
  • PROMPT: le istruzioni di testo da includere nel prompt.
  • EXTERNAL_API_ENDPOINT: l'URL completo dell'endpoint API Gateway protetto chiamato da Gemini, ad esempio https://YOUR_GATEWAY_HOSTNAME/v0/search. Questo endpoint deve rispettare lo schema dell'API specificato.

  • EXTERNAL_API_KEY: la chiave API che hai generato e configurato per il tuo API Gateway. Gemini utilizza questa chiave per autenticarsi con il tuo endpoint.

    Metodo HTTP e URL:

    POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

    Corpo JSON della richiesta:

      {
  "contents": [{
      "role": "user",
      "parts": [{
          "text": "PROMPT"
      }]
  }],
  "tools": [{
      "retrieval": {
        "externalApi": {
          "api_spec": "SIMPLE_SEARCH",
          "endpoint": "EXTERNAL_API_ENDPOINT",
          "apiAuth": {
            "apiKeyConfig": {
              "apiKeyString": "EXTERNAL_API_KEY"
            }
          }
        }
      }
  }]
}

    Per inviare la richiesta, utilizza una di queste opzioni:

    curl

    Il comando seguente presuppone che tu abbia eseguito l'accesso a gcloud CLI con il tuo account utente eseguendo gcloud CLI init o gcloud CLI auth login oppure utilizzando Cloud Shell, che esegue automaticamente l'accesso a gcloud CLI. Puoi controllare l'account attivo eseguendo gcloud CLI auth list.

    Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

    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

    Il comando seguente presuppone che tu abbia eseguito l'accesso a gcloud CLI con il tuo account utente eseguendo gcloud CLI init o gcloud CLI auth login. Puoi controllare l'account attivo eseguendo gcloud CLI auth list.

    Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

    $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

    Dovresti ricevere una risposta JSON simile alla seguente:

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

Configura un endpoint API di ricerca

Se non hai un endpoint API esistente che soddisfi i requisiti, questa sezione ti guiderà nella configurazione di uno utilizzando Cloud Functions e API Gateway.

Crea il wrapper dell'API esterna con Cloud Functions

Una Cloud Function può fungere da intermediario che riceve le query da Gemini, invia le query appropriate alla tua infrastruttura di ricerca esistente, ad esempio un database, un motore di ricerca interno o Vector Search, e poi formatta i risultati nello schema compreso da Gemini.

Per saperne di più, consulta la documentazione di Cloud Run Functions.

Esempio di configurazione di una funzione Cloud Functions (Python)

Questo esempio utilizza un elenco di prodotti impostato come hardcoded a scopo dimostrativo. Dovrai sostituire la logica di recupero dei dati con chiamate al tuo sistema di ricerca effettivo.

  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. Deployment: vai alla directory contenente main.py e requirements.txt ed esegui:

    gcloud functions deploy custom_search_wrapper \
  --runtime python311 \
  --trigger-http \
  --entry-point custom_search_wrapper \
  --region YOUR_REGION \
  --allow-unauthenticated \
  --gen2
    • Sostituisci YOUR_REGION con la regione Google Cloud scelta, ad esempio us-central1.
    • --allow-unauthenticated è specificato perché API Gateway gestisce l'autenticazione.

Proteggi Cloud Functions con API Gateway e una chiave API

API Gateway fornisce un punto di ingresso sicuro e gestito per le tue funzioni Cloud Functions e ti consente di applicare l'autenticazione con chiave API.

Per saperne di più, consulta la documentazione di API Gateway.

  1. Crea una specifica OpenAPI (openapi-spec.yaml): questo file definisce il modo in cui API Gateway espone le tue funzioni Cloud Functions. Specifica che il gateway prevede una richiesta POST al percorso /v0/search e richiede una chiave API inviata come parametro di query denominato 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. Esegui il deployment di API Gateway: dopo aver sostituito le seguenti variabili, esegui i comandi gcloud CLI:

    • YOUR_PROJECT_ID: l'ID progetto Google Cloud .
    • YOUR_REGION: la regione Google Cloud che hai utilizzato per Cloud Functions, ad esempio 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

    Dopo il deployment, il nome host (URL del gateway) ha il seguente formato:

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

    Puoi utilizzare il nome host per creare l'URL completo dell'endpoint per Gemini. Ad esempio:

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

  3. Crea e limita una chiave API: devi creare una chiave API che Gemini utilizza per accedere all'endpoint API Gateway. Per saperne di più, consulta Gestisci le chiavi API.

    Per creare e limitare una chiave API, segui questi passaggi:

    1. Nella console Google Cloud , vai alla pagina API Gateway / Abilita API.

      Vai ad API Gateway API / Abilita API

    2. Se l'API API Gateway non è abilitata, fai clic su Avvia, quindi su Abilita.

    3. Seleziona Credenziali.

    4. Fai clic su Crea credenziali e seleziona Chiave API.

    5. Fai clic su Mostra chiave e copia la chiave API generata. Conserva la chiave in un luogo sicuro. Questa chiave viene utilizzata da Gemini.

    6. Fai clic su Modifica chiave API o sul nome della chiave.

    7. Nella sezione Restrizioni delle API, segui questi passaggi:

      1. Seleziona l'opzione Limita chiave.

      2. Seleziona il servizio gestito di API Gateway. Deve avere il nome della tua API, ad esempio Custom Search API for Gemini Grounding API.

      3. Se la chiave non è inclusa o se intendi gestire il gateway con l'API utilizzando questa chiave, assicurati che sia selezionata l'API API Gateway (apigateway.googleapis.com). Per il grounding, la chiave deve avere accesso al servizio API specifico ospitato da API Gateway.

    8. Fai clic su Salva. L'endpoint API Gateway è protetto e, quando lo utilizzi, devi passare la chiave API come parametro di query. Ad esempio:

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

Considerazioni per l'API di ricerca

Esamina le seguenti considerazioni per scegliere l'API di ricerca:

  • Qualità dello snippet: il testo dello snippet restituito dall'API è fondamentale. Deve essere conciso, ma abbastanza informativo da consentire a Gemini di utilizzarlo come base oggettiva per la sua risposta.
  • Latenza: l'API di ricerca deve rispondere rapidamente. Una latenza elevata nell'API aumenta il tempo di risposta complessivo di Gemini.
  • Gestione degli errori: implementa una gestione degli errori efficace in Cloud Functions o nell'API di ricerca. Se l'API genera spesso errori o timeout, la capacità di Gemini di generare risposte fondate ne risente negativamente.

Passaggi successivi