Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Grounding con l'API di ricerca

Puoi collegare Gemini alle tue origini dati esterne eseguendo il grounding con la tua API Search. In questo modo, puoi utilizzare qualsiasi servizio di ricerca come origine di grounding 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 il grounding utilizzando qualsiasi API Search con Gemini.

Come funziona il grounding con l'API Search

Quando esegui il grounding con l'API Search, 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 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. La tua API dovrebbe quindi restituire snippet di dati pertinenti. Gemini utilizza questi snippet come fonte di verità per generare una risposta più accurata e basata sui dati.

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

Modelli supportati

In questa sezione sono elencati i modelli che supportano il grounding con l'API Search.

Fai clic per espandere i modelli supportati

Prima di iniziare

Per utilizzare il grounding con l'API Search:

Assicurati che l'API Agent Platform sia abilitata nel tuo Google Cloud progetto.
Se prevedi di seguire la guida di configurazione dettagliata per la creazione di un nuovo endpoint API 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

Il grounding con l'API Search 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 API Gemini.

Configurare 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' Google Cloud ID progetto.
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 che Gemini chiama, ad esempio https://YOUR_GATEWAY_HOSTNAME/v0/search. Questo endpoint deve rispettare lo schema API specificato.

EXTERNAL_API_KEY: la chiave API che hai generato e configurato per il tuo API Gateway. Gemini utilizza questa chiave per l'autenticazione con l'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, scegli 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 consente di accedere automaticamente 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": {
    "..."
  }
}

Configurare un endpoint API Search

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.

Creare il wrapper API esterno con Cloud Functions

Una Cloud Function può fungere da intermediario che riceve le query da Gemini, invia le query appropriate all'infrastruttura di ricerca esistente, ad esempio un database, un motore di ricerca interno o una ricerca di vettori, 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. Dovrai sostituire la logica di recupero dei dati con chiamate al tuo sistema di ricerca effettivo.

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)

requirements.py

functions-framework>=3.0.0
Flask>=2.0.0

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 scelta Google Cloud , ad esempio us-central1.
- Viene specificato --allow-unauthenticated perché API Gateway gestisce l'autenticazione.
Importante: L'URL del trigger dopo il deployment ha il formato https://....run.app. Utilizza questo formato per la configurazione di API Gateway nel passaggio successivo.

Proteggere Cloud Functions con API Gateway e una chiave API

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

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

Crea una specifica OpenAPI (openapi-spec.yaml): questo file definisce il modo in cui API Gateway espone 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

Esegui il deployment di API Gateway: dopo aver sostituito le seguenti variabili, esegui i comandi gcloud CLI:

YOUR_PROJECT_ID: l'ID Google Cloud progetto.
YOUR_REGION: la Google Cloud regione utilizzata 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

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 / Abilita API.
  Vai a API Gateway API / Abilita API
2. Se l'API API Gateway non è abilitata, fai clic su Avvia e poi su 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. Archivia 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 avere il nome dell'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.
  Nota: in genere viene utilizzata una chiave o account di servizio separato per la gestione.
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

Leggi le seguenti considerazioni per scegliere l'API Search:

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 risposta.
Latenza: l'API Search 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 Search. Se l'API genera spesso errori o scade, la capacità di Gemini di generare risposte basate sui dati ne risente negativamente.

Passaggi successivi

Grounding con la Ricerca.