Grounding con l'API di ricerca

Puoi collegare Gemini alle tue origini dati esterne tramite il grounding con la tua API di ricerca. In questo modo, puoi utilizzare qualsiasi servizio di ricerca come fonte di base per Gemini, il che contribuisce 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 la base utilizzando qualsiasi API di ricerca con Gemini.

Come funziona il grounding con l'API Search

Quando utilizzi 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 funzionalità di ricerca personalizzata come strumento per migliorare le sue risposte. Consente interazioni più dinamiche e sensibili al contesto, in quanto 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 attendibile 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

I seguenti modelli supportano la grounding con la tua API:

• Vertex AI Model Optimizer
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

Per saperne di più, consulta Modelli Gemini.

Prima di iniziare

Per utilizzare il grounding con l'API Search:

1. Assicurati che l'API Vertex AI sia abilitata nel tuo progetto Google Cloud.
2. Se prevedi di seguire la guida dettagliata alla configurazione per creare un nuovo endpoint APII Search, 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 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 JSON di oggetti. 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

La fondatezza 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.

Utilizzare il grounding con l'API Search con un endpoint compatibile

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

Configurare lo strumento externalApi

Quando invii 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. L'app Gemini aggiunge questa chiave come ?key=<YOUR_API_KEY> all'URL dell'endpoint.

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

  {
  "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 -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"

$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

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

Configurare un endpoint API di ricerca

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

Crea il wrapper API esterno con Cloud Functions

Una Cloud Function può fungere da intermediario che riceve query da Gemini, invia query appropriate alla tua infrastruttura di ricerca esistente, ad esempio un database, un motore di ricerca interno o una ricerca vettoriale, 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 Cloud Functions (Python)

Questo esempio utilizza un elenco di prodotti hardcoded a scopo dimostrativo. Devi 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_minimal(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 che hai scelto, ad esempio us-central1.
   • --allow-unauthenticated è specificato perché API Gateway gestisce l'autenticazione.

Proteggere Cloud Functions con API Gateway e una chiave API

API Gateway fornisce un punto di ingresso sicuro e gestito alle tue 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 in che modo API Gateway espone le tue 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: il tuo 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 dell'endpoint completo 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 Gestire le chiavi API.

   Per creare e limitare una chiave API:

   1. Nella Google Cloud console, vai alla pagina API Gateway/Enable APIs (API Gateway/Abilita API).

      Vai ad API API Gateway / Abilita API

   2. Se l'API Gateway non è abilitata, fai clic su Avvia e poi 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 API Gateway. Deve essere denominato come la 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 l'API API Gateway (apigateway.googleapis.com) sia selezionata. Per la base, la chiave deve accedere al tuo 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 Search

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

• Qualità dello snippet: il testo dello snippet restituito dall'API è fondamentale. Deve essere conciso ma sufficientemente informativo da consentire a Gemini di utilizzarlo come base fattuale per la sua risposta.
• Latenza: l'API Search deve rispondere rapidamente. L'elevata latenza dell'API aumenta il tempo di risposta complessivo di Gemini.
• Gestione degli errori: implementa una gestione degli errori efficace nelle tue API Cloud Functions o Search. Se la tua API genera spesso errori o scade, influisce negativamente sulla capacità di Gemini di generare risposte basate su dati reali.

Passaggi successivi

• Grounding con la Ricerca.