Grounding con la ricerca web Exa

Exa fornisce un'API di ricerca che dà accesso ai dati web disponibili pubblicamente ottimizzati per il grounding delle risposte dei modelli linguistici di grandi dimensioni. Questa pagina spiega come eseguire il grounding delle risposte di Gemini utilizzando Exa.

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

Casi d'uso

Il grounding 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 generali: recupera informazioni aggiornate per produrre risposte più affidabili.
  • Agenti di ricerca: conduci ricerche web approfondite su più fonti.
  • Agenti di codifica: recupera gli ultimi snippet di codice, documenti e riferimenti tecnici.
  • Agenti vocali: recupero web per supportare interazioni vocali in tempo reale e a bassa latenza.
  • Agenti specifici per settore: recupera informazioni aggiornate e specifiche per il dominio, adattate a un settore o a un ambito di conoscenza specifico.
  • Arricchimento dei dati: aumenta i set di dati interni con il contesto web e i metadati attuali.
  • Flussi di lavoro automatizzati: raccogli periodicamente notizie, persone, aziende o altri dati aggiornati di frequente per i flussi di lavoro interni o di produzione.

Esempio

Chi ha vinto il Super Bowl 2026?

Senza grounding Con grounding
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

In questa sezione sono elencati i modelli che supportano il grounding con la ricerca web Exa.

Fai clic per espandere i modelli supportati

Prima di iniziare

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

Eseguire il 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 prestazioni ottimali, 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 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

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

  • 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 una latenza ridotta ed è un buon adatto per la ricerca rivolta agli utenti e i flussi di lavoro interattivi. Utilizza instant per le 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) l'elenco dei domini da escludere dai risultati di ricerca. Se specificato, non vengono restituiti risultati da questi domini. Per escludere più di un dominio, aggiungi ogni dominio come stringa tra virgolette separata nell'elenco (per esempio, ["example.com", "example.net"]). Puoi specificare fino a 1200 domini.
  • INCLUDE_DOMAINS: (facoltativo) l'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 le evidenziazioni. Controlla la lunghezza totale del testo di evidenziazione restituito per URL.
  • NUM_RESULTS: (facoltativo) il numero massimo di risultati di ricerca da utilizzare per il grounding. 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 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

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

  • 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 una latenza ridotta ed è un buon adatto per la ricerca rivolta agli utenti e i flussi di lavoro interattivi. Utilizza instant per le 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) l'elenco dei domini da escludere dai risultati di ricerca. Se specificato, non vengono restituiti risultati da questi domini. Per escludere più di un dominio, aggiungi ogni dominio come stringa tra virgolette separata nell'elenco (per esempio, ["example.com", "example.net"]). Puoi specificare fino a 1200 domini.
  • INCLUDE_DOMAINS: (facoltativo) l'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 le evidenziazioni. Controlla la lunghezza totale del testo di evidenziazione restituito per URL.
  • NUM_RESULTS: (facoltativo) il numero massimo di risultati di ricerca da utilizzare per il grounding. 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 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

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

  • 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 una latenza ridotta ed è un buon adatto per la ricerca rivolta agli utenti e i flussi di lavoro interattivi. Utilizza instant per le 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) l'elenco dei domini da escludere dai risultati di ricerca. Se specificato, non vengono restituiti risultati da questi domini. Per escludere più di un dominio, aggiungi ogni dominio come stringa tra virgolette separata nell'elenco (per esempio, ["example.com", "example.net"]). Puoi specificare fino a 1200 domini.
  • INCLUDE_DOMAINS: (facoltativo) l'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 le evidenziazioni. Controlla la lunghezza totale del testo di evidenziazione restituito per URL.
  • NUM_RESULTS: (facoltativo) il numero massimo di risultati di ricerca da utilizzare per il grounding. 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' Cloud de Confiance by S3NS ID progetto.
  • 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 una latenza ridotta ed è adatto per la ricerca rivolta agli utenti e i flussi di lavoro interattivi. Utilizza instant per le 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) l'elenco dei domini da escludere dai risultati di ricerca. Se specificato, non verranno restituiti risultati da questi domini. Puoi specificare fino a 1200 domini.
  • INCLUDE_DOMAINS: (facoltativo) l'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 le evidenziazioni. Controlla la lunghezza totale del testo di evidenziazione restituito per URL.
  • NUM_RESULTS: (facoltativo) il numero massimo di risultati di ricerca da utilizzare per il grounding. 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 devi aumentare i limiti di frequenza, contatta support@exa.ai e il team dell'account Google fornendo il tuo caso d'uso e i tuoi requisiti.

Fatturazione

L'utilizzo del grounding con Exa comporta i seguenti addebiti:

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