Grounding con la ricerca web Exa

Exa fornisce un'API di ricerca che consente di accedere a dati web disponibili pubblicamente ottimizzati per basare le risposte dei modelli linguistici di grandi dimensioni. Questa pagina spiega come basare le risposte di Gemini utilizzando Exa.

Il grounding con la ricerca web Exa su Gemini Enterprise Agent Platform è un'offerta separata (come definita nel tuo Google Cloud Contratto) che collega i modelli Gemini ai dati web pubblici forniti dall'API di ricerca di Exa.

Casi d'uso

La base con Exa migliora l'accuratezza e riduce le allucinazioni dando ai modelli l'accesso a dati web aggiornati e pertinenti. I casi d'uso comuni includono:

  • Agenti e chatbot generici: recupera informazioni aggiornate per produrre risposte più affidabili.
  • Agenti di ricerca: conduci ricerche approfondite sul deep web su più fonti.
  • Agenti di programmazione: recupera gli ultimi snippet di codice, documenti e riferimenti tecnici.
  • Agenti vocali: recupero web per supportare le interazioni vocali in tempo reale a bassa latenza.
  • Agenti specifici per verticale: recupera informazioni aggiornate e specifiche per il dominio, personalizzate per un settore o un verticale di conoscenza particolare.
  • Arricchimento dei dati: arricchisci i set di dati interni con il contesto web e i metadati attuali.
  • Workflow automatizzati: raccogli periodicamente notizie, persone, aziende o altri dati aggiornati di frequente per i workflow interni o di produzione.

Esempio

Chi ha vinto il Super Bowl 2026?

Senza grounding Con messa a terra
Non posso dirti chi ha vinto il Super Bowl 2026 perché l'evento non si è ancora svolto. I Seattle Seahawks hanno vinto il Super Bowl LX l'8 febbraio 2026, battendo i New England Patriots con un punteggio finale di 29-13. Fonti: domain1.com, domain2.com, …

Modelli supportati

La funzionalità di grounding con Exa è supportata dai seguenti modelli:

  • Gemini 2.5 Flash (gemini-2.5-flash)
  • Gemini 2.5 Flash Lite (gemini-2.5-flash-lite)
  • Gemini 2.5 Pro (gemini-2.5-pro)
  • Gemini 3.1 Pro (gemini-3.1-pro-preview)
  • Gemini 3.1 Flash Lite (gemini-3.1-flash-lite)
  • Gemini 3.5 Flash (gemini-3.5-flash)

Prima di iniziare

Per utilizzare Grounding con Exa, devi ottenere una chiave API dal sito web di Exa. Questa chiave API viene utilizzata nella tua richiesta a Gemini.

Grounding delle risposte di Gemini con Exa

Richiedi risposte con grounding da Gemini utilizzando l'SDK Google Gen AI o l'API REST. Per ottenere il massimo rendimento, ti consigliamo di utilizzare le impostazioni predefinite per i parametri facoltativi, a meno che tu non abbia bisogno di valori non predefiniti.

Prima di eseguire gli esempi, completa i prerequisiti, inclusa l'ottenimento di una chiave API Exa.

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

Prima di eseguire l'esempio, esegui le seguenti sostituzioni:

  • MODEL_ID: l'ID di un modello supportato da utilizzare, ad esempio gemini-2.5-flash.
  • TEXT: il prompt testuale da inviare al modello.
  • API_KEY: la tua chiave API per la ricerca web Exa.
  • SEARCH_TYPE: (Facoltativo) il tipo di ricerca Exa da eseguire. I valori supportati sono fast e instant. Il valore predefinito è fast, che fornisce risultati completi con latenza ridotta ed è adatto per la ricerca rivolta agli utenti e i flussi di lavoro interattivi. Utilizza instant per esperienze che richiedono la latenza più bassa, come chat, agenti vocali e completamento automatico; riduce al minimo il tempo di risposta dando la priorità alla velocità rispetto alla profondità della ricerca.
  • EXCLUDE_DOMAINS: (facoltativo) elenco dei domini da escludere dai risultati di ricerca. Se specificati, non vengono restituiti risultati da questi domini. Per escludere più di un dominio, aggiungi ogni dominio come stringa tra virgolette separata nell'elenco (ad esempio, ["example.com", "example.net"]). Puoi specificare fino a 1200 domini.
  • INCLUDE_DOMAINS: (facoltativo) elenco dei domini da includere nella ricerca. Se specificato, i risultati provengono solo da questi domini. Per includere più di un dominio, aggiungi ogni dominio come stringa tra virgolette separata nell'elenco (ad esempio, ["example.com", "example.net"]). Puoi specificare fino a 1200 domini.
  • MAX_CHARACTERS: (facoltativo) il numero massimo di caratteri da restituire per i momenti salienti. Controlla la lunghezza totale del testo evidenziato restituito per URL.
  • NUM_RESULTS: (facoltativo) Il numero massimo di risultati di ricerca da utilizzare per la base. Se non specificato, il valore predefinito è 5.

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="MODEL_ID",
    contents="TEXT",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                exa_ai_search=types.ToolExaAiSearch(
                    # Required. Your API key for Exa web search.
                    api_key="API_KEY",
                    # Optional. Customize the search. Click a placeholder to
                    # enter a value, or remove the line to accept the default.
                    custom_configs={
                        "type": "SEARCH_TYPE",
                        "excludeDomains": ["EXCLUDE_DOMAINS"],
                        "includeDomains": ["INCLUDE_DOMAINS"],
                        "contents": {
                            "highlights": {
                                "maxCharacters": MAX_CHARACTERS,
                            },
                        },
                        "numResults": NUM_RESULTS,
                    },
                )
            )
        ],
    ),
)

print(response.text)

# The grounding metadata contains the web sources used to ground the response.
print(response.candidates[0].grounding_metadata.grounding_chunks)

Java

Scopri come installare o aggiornare Java.

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

Imposta le variabili di ambiente per utilizzare 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

Prima di eseguire l'esempio, esegui le seguenti sostituzioni:

  • MODEL_ID: l'ID di un modello supportato da utilizzare, ad esempio gemini-2.5-flash.
  • TEXT: il prompt testuale da inviare al modello.
  • API_KEY: la tua chiave API per la ricerca web Exa.
  • SEARCH_TYPE: (Facoltativo) il tipo di ricerca Exa da eseguire. I valori supportati sono fast e instant. Il valore predefinito è fast, che fornisce risultati completi con latenza ridotta ed è adatto per la ricerca rivolta agli utenti e i flussi di lavoro interattivi. Utilizza instant per esperienze che richiedono la latenza più bassa, come chat, agenti vocali e completamento automatico; riduce al minimo il tempo di risposta dando la priorità alla velocità rispetto alla profondità della ricerca.
  • EXCLUDE_DOMAINS: (facoltativo) elenco dei domini da escludere dai risultati di ricerca. Se specificati, non vengono restituiti risultati da questi domini. Per escludere più di un dominio, aggiungi ogni dominio come stringa tra virgolette separata nell'elenco (ad esempio, ["example.com", "example.net"]). Puoi specificare fino a 1200 domini.
  • INCLUDE_DOMAINS: (facoltativo) elenco dei domini da includere nella ricerca. Se specificato, i risultati provengono solo da questi domini. Per includere più di un dominio, aggiungi ogni dominio come stringa tra virgolette separata nell'elenco (ad esempio, ["example.com", "example.net"]). Puoi specificare fino a 1200 domini.
  • MAX_CHARACTERS: (facoltativo) il numero massimo di caratteri da restituire per i momenti salienti. Controlla la lunghezza totale del testo evidenziato restituito per URL.
  • NUM_RESULTS: (facoltativo) Il numero massimo di risultati di ricerca da utilizzare per la base. Se non specificato, il valore predefinito è 5.

import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.Tool;
import com.google.genai.types.ToolExaAiSearch;
import java.util.List;
import java.util.Map;

public class ExaGroundingSample {
  public static void main(String[] args) {
    try (Client client = Client.builder().build()) {

      GenerateContentConfig config =
          GenerateContentConfig.builder()
              .tools(
                  Tool.builder()
                      .exaAiSearch(
                          ToolExaAiSearch.builder()
                              // Required. Your API key for Exa web search.
                              .apiKey("API_KEY")
                              // Optional. Customize the search. Click a
                              // placeholder to enter a value, or remove the
                              // entry to accept the default.
                              .customConfigs(
                                  Map.of(
                                      "type", "SEARCH_TYPE",
                                      "excludeDomains",
                                      List.of("EXCLUDE_DOMAINS"),
                                      "includeDomains",
                                      List.of("INCLUDE_DOMAINS"),
                                      "contents",
                                      Map.of(
                                          "highlights",
                                          Map.of(
                                              "maxCharacters",
                                              MAX_CHARACTERS)),
                                      "numResults", NUM_RESULTS))
                              .build())
                      .build())
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              "MODEL_ID", "TEXT", config);

      System.out.println(response.text());

      // The grounding metadata contains the web sources used to ground the response.
      System.out.println(
          response.candidates().get().get(0).groundingMetadata().get().groundingChunks().get());
    }
  }
}

Node.js

Installa

npm install @google/genai

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

Imposta le variabili di ambiente per utilizzare 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

Prima di eseguire l'esempio, esegui le seguenti sostituzioni:

  • MODEL_ID: l'ID di un modello supportato da utilizzare, ad esempio gemini-2.5-flash.
  • TEXT: il prompt testuale da inviare al modello.
  • API_KEY: la tua chiave API per la ricerca web Exa.
  • SEARCH_TYPE: (Facoltativo) il tipo di ricerca Exa da eseguire. I valori supportati sono fast e instant. Il valore predefinito è fast, che fornisce risultati completi con latenza ridotta ed è adatto per la ricerca rivolta agli utenti e i flussi di lavoro interattivi. Utilizza instant per esperienze che richiedono la latenza più bassa, come chat, agenti vocali e completamento automatico; riduce al minimo il tempo di risposta dando la priorità alla velocità rispetto alla profondità della ricerca.
  • EXCLUDE_DOMAINS: (facoltativo) elenco dei domini da escludere dai risultati di ricerca. Se specificati, non vengono restituiti risultati da questi domini. Per escludere più di un dominio, aggiungi ogni dominio come stringa tra virgolette separata nell'elenco (ad esempio, ["example.com", "example.net"]). Puoi specificare fino a 1200 domini.
  • INCLUDE_DOMAINS: (facoltativo) elenco dei domini da includere nella ricerca. Se specificato, i risultati provengono solo da questi domini. Per includere più di un dominio, aggiungi ogni dominio come stringa tra virgolette separata nell'elenco (ad esempio, ["example.com", "example.net"]). Puoi specificare fino a 1200 domini.
  • MAX_CHARACTERS: (facoltativo) il numero massimo di caratteri da restituire per i momenti salienti. Controlla la lunghezza totale del testo evidenziato restituito per URL.
  • NUM_RESULTS: (facoltativo) Il numero massimo di risultati di ricerca da utilizzare per la base. Se non specificato, il valore predefinito è 5.

import {GoogleGenAI} from '@google/genai';

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: 'MODEL_ID',
  contents: 'TEXT',
  config: {
    tools: [
      {
        exaAiSearch: {
          // Required. Your API key for Exa web search.
          apiKey: 'API_KEY',
          // Optional. Customize the search. Click a placeholder to enter a
          // value, or remove the line to accept the default.
          customConfigs: {
            type: 'SEARCH_TYPE',
            excludeDomains: ['EXCLUDE_DOMAINS'],
            includeDomains: ['INCLUDE_DOMAINS'],
            contents: {
              highlights: {
                maxCharacters: MAX_CHARACTERS,
              },
            },
            numResults: NUM_RESULTS,
          },
        },
      },
    ],
  },
});

console.log(response.text);

// The grounding metadata contains the web sources used to ground the response.
console.log(response.candidates[0].groundingMetadata.groundingChunks);

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 del modello da utilizzare.
  • TEXT: il prompt testuale da inviare al modello.
  • API_KEY: la tua chiave API per la ricerca web Exa.
  • SEARCH_TYPE: (Facoltativo) il tipo di ricerca Exa da eseguire. I valori supportati sono fast e instant. Il valore predefinito è fast, che fornisce risultati completi con latenza ridotta ed è ideale per la ricerca rivolta agli utenti e i flussi di lavoro interattivi. Utilizza instant per esperienze che richiedono la latenza più bassa, come chat, agenti vocali e completamento automatico; riduce al minimo il tempo di risposta dando la priorità alla velocità rispetto alla profondità della ricerca.
  • EXCLUDE_DOMAINS: (facoltativo) elenco dei domini da escludere dai risultati di ricerca. Se specificati, non verranno restituiti risultati da questi domini. Puoi specificare fino a 1200 domini.
  • INCLUDE_DOMAINS: (facoltativo) elenco dei domini da includere nella ricerca. Se specificato, i risultati provengono solo da questi domini. Puoi specificare fino a 1200 domini.
  • MAX_CHARACTERS: (facoltativo) il numero massimo di caratteri da restituire per i punti salienti. Controlla la lunghezza totale del testo evidenziato restituito per URL.
  • NUM_RESULTS: (facoltativo) Il numero massimo di risultati di ricerca da utilizzare per la base. Se non specificato, il valore predefinito è 5.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "TEXT"
    }]
  }],
  "tools": [{
    "exaAiSearch": {
        "api_key": "API_KEY",
        "customConfigs": {
            "type": "SEARCH_TYPE",
            "excludeDomains": ["EXCLUDE_DOMAINS"],
            "includeDomains": ["INCLUDE_DOMAINS"],
            "contents": {
                "highlights": {
                    "maxCharacters": MAX_CHARACTERS
                }
            },
            "numResults": NUM_RESULTS
        }
    }
}],
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente.

Quota

La quota predefinita è di 200 prompt al minuto. Se hai bisogno di aumentare i limiti di frequenza, contatta support@exa.ai e il tuo team dell'account Google indicando il tuo caso d'uso e i tuoi requisiti.

Fatturazione

L'utilizzo di Grounding con Exa comporta i seguenti costi:

  • Consumo di token Gemini: token prompt, token di ragionamento, token output. Per saperne di più, consulta la sezione Prezzi.
  • Grounding di Gemini con i tuoi dati: per saperne di più, consulta Prezzi.
  • Prezzi per l'utilizzo dell'API di ricerca di Exa: per ulteriori informazioni, consulta la pagina dei prezzi di Exa.