Grounding con Parallel Web Search

Parallel Web Systems offre un'API di ricerca che fornisce l'accesso ai dati web disponibili pubblicamente ottimizzati per l'utilizzo da parte di modelli linguistici di grandi dimensioni per il grounding. Questa pagina spiega come eseguire il grounding delle risposte di Gemini utilizzando Parallel.

Il grounding con Parallel 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 da Parallel Web Systems' search API. Questo servizio fornisce a Gemini l'accesso a informazioni in tempo reale da miliardi di pagine web per garantire risposte più aggiornate e basate sui fatti.

Casi d'uso

Il grounding con Parallel è adatto a casi d'uso come i seguenti:

  • Utilizzo dei dati web per scopi di completamento o arricchimento delle informazioni.
  • Agenti multi-hop che richiedono ricerche web più approfondite per domande più complesse.
  • Creazione di un'API che integra i dati di ricerca web.
  • Assistenti rivolti ai dipendenti che consentono agli utenti finali di porre domande e creare report complessi utilizzando le informazioni web più recenti.
  • Applicazioni rivolte ai consumatori, come quelle di vendita al dettaglio e di viaggi, che consentono all'utente di prendere decisioni di acquisto informate.
  • Agenti automatici che vengono eseguiti autonomamente per svolgere attività automatizzate, come l'analisi delle notizie e i controlli KYC.
  • Agenti verticali (agenti di vendita, agenti di codifica, agenti finanziari) che ottengono il contesto più aggiornato dal web.

Esempio

Chi ha vinto il Gran Premio di F1 di Las Vegas 2025?

Senza grounding Con grounding
Il Gran Premio di Las Vegas 2025 non si è ancora svolto. La gara è in programma per il fine settimana del 20-22 novembre 2025. Pertanto, il vincitore è sconosciuto. Il vincitore del Gran Premio di F1 di Las Vegas 2025 è stato Max Verstappen della Red Bull Racing. La gara si è svolta il 22 novembre 2025. Fonti: domain1.com, domain2.com, ...

Modelli supportati

Il grounding con la ricerca web di Parallel è supportato 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 il grounding con la ricerca web di Parallel, devi configurare l'accesso. Hai due opzioni:

  • Abbonati direttamente al grounding con la ricerca web di Parallel su Google Cloud Marketplace (anteprima) per un' integrazione semplificata nel tuo ambiente cloud esistente. È disponibile anche un'offerta di conservazione Zero Data Retention dei dati per i carichi di lavoro sensibili. Per utilizzare la conservazione zero dei dati, devi essere abbonato all'offerta di conservazione zero dei dati e impostare il flag enable_zero_data_retention corrispondente nelle richieste API.

  • Utilizza una chiave API Parallel esistente.

Abbonarsi su Google Cloud Marketplace (consigliato)

L'integrazione tramite Google Cloud Marketplace ti consente di gestire il servizio di grounding con la ricerca web di Parallel direttamente all'interno di Google Cloud. Per iniziare, abbonati al servizio di grounding con la ricerca web di Parallel su Google Cloud Marketplace, accetta i Termini di servizio e consulta i prezzi.

Utilizzare la propria chiave API

Se preferisci gestire separatamente la fatturazione e l'accesso all'API di Parallel, puoi fornire la tua chiave API. Per utilizzare questo metodo, devi ottenere una chiave API da Parallel developer platform. Questa chiave API viene utilizzata direttamente nelle richieste API REST a Gemini.

Eseguire il grounding delle risposte di Gemini con Parallel

Richiedi risposte con grounding da Gemini utilizzando Agent Studio nella Google Cloud console, l'SDK Google Gen AI o l'API REST. Per prestazioni ottimali, ti consigliamo di utilizzare le impostazioni predefinite per i parametri facoltativi, a meno che non siano strettamente necessari valori non predefiniti.

Se ti sei abbonato al grounding con la ricerca web di Parallel su Google Cloud Marketplace (anteprima), verifica che l'account di fatturazione utilizzato per l'abbonamento sia attivo nel tuo Google Cloud progetto.

Prima di eseguire gli esempi, completa i prerequisiti, incluso l'abbonamento su Google Cloud Marketplace o la fornitura di una chiave API Parallel.

Ogni esempio di SDK legge il progetto e la località dalle variabili di ambiente mostrate nella scheda. Nel codice campione, sostituisci MODEL_ID con un ID modello supportato, ad esempio gemini-2.5-flash.

Console

Per eseguire il grounding delle risposte di Gemini con la ricerca web di Parallel utilizzando Agent Studio su Gemini Enterprise Agent Platform:

  1. Nella Google Cloud console, vai alla pagina Agent Studio.

    Vai ad Agent Studio

  2. Nel riquadro laterale, in Impostazioni modello, nella sezione Grounding, attiva il pulsante Partner (Risultati di ricerca dei partner di grounding).

  3. Seleziona Ricerca web di Parallel come partner di grounding e fai clic su Applica. Per utilizzare la ricerca web di Parallel, devi prima abbonarti su Google Cloud Marketplace.

  4. Inserisci il prompt nella casella di testo e invialo.

Le risposte ai prompt ora utilizzano il grounding con la ricerca web di Parallel.

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

client = genai.Client()

response = client.models.generate_content(
    model="MODEL_ID",
    contents="Who won the 2025 Las Vegas F1 Grand Prix?",
    config=types.GenerateContentConfig(
        tools=[
            types.Tool(
                parallel_ai_search=types.ToolParallelAiSearch(
                    # Optional. Omit api_key if you subscribed to Grounding with
                    # Parallel Web Search on Google Cloud Marketplace. Otherwise,
                    # provide your Parallel API key.
                    # api_key="API_KEY",
                    # Optional. Customize the search. See the REST tab for the
                    # full list of supported parameters. Keys inside custom_configs
                    # are Parallel.ai Search API params (snake_case).
                    custom_configs={
                        "mode": "basic",
                        "max_results": 10,
                        "source_policy": {"include_domains": ["wikipedia.org"]},
                    },
                )
            )
        ],
    ),
)

print(response.text)
# Example response:
# Max Verstappen won the 2025 Las Vegas F1 Grand Prix ...

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

Per personalizzare la ricerca, imposta il campo custom_configs di ToolParallelAiSearch. Questo campo accetta gli stessi parametri facoltativi descritti nella scheda REST , ad esempio source_policy, excerpts, max_results e mode.

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
 

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.ToolParallelAiSearch;
import java.util.List;
import java.util.Map;

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

      GenerateContentConfig config =
          GenerateContentConfig.builder()
              .tools(
                  // Omit apiKey if you subscribed to Grounding with Parallel Web
                  // Search on Google Cloud Marketplace. Otherwise, set apiKey to
                  // your Parallel API key.
                  Tool.builder()
                      .parallelAiSearch(
                          ToolParallelAiSearch.builder()
                              // Optional. Customize the search. See the REST tab
                              // for the full list of supported parameters. Keys
                              // inside customConfigs are Parallel.ai Search API
                              // params (snake_case).
                              .customConfigs(
                                  Map.of(
                                      "mode", "basic",
                                      "max_results", 10,
                                      "source_policy",
                                      Map.of(
                                          "include_domains",
                                          List.of("wikipedia.org"))))
                              .build())
                      .build())
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              "MODEL_ID", "Who won the 2025 Las Vegas F1 Grand Prix?", config);

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

Per personalizzare la ricerca, imposta il campo customConfigs di ToolParallelAiSearch. Questo campo accetta gli stessi parametri facoltativi descritti nella scheda REST , ad esempio source_policy, excerpts, max_results e mode.

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
 

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

const ai = new GoogleGenAI({});

const response = await ai.models.generateContent({
  model: 'MODEL_ID',
  contents: 'Who won the 2025 Las Vegas F1 Grand Prix?',
  config: {
    tools: [
      // Omit apiKey if you subscribed to Grounding with Parallel Web Search on
      // Google Cloud Marketplace. Otherwise, set apiKey to your Parallel API key.
      {
        parallelAiSearch: {
          // Optional. Customize the search. See the REST tab for the full
          // list of supported parameters. Keys inside customConfigs are
          // Parallel.ai Search API params (snake_case).
          customConfigs: {
            mode: 'basic',
            max_results: 10,
            source_policy: {include_domains: ['wikipedia.org']},
          },
        },
      },
    ],
  },
});

console.log(response.text);

Per personalizzare la ricerca, imposta il campo customConfigs dello strumento parallelAiSearch. Questo campo accetta gli stessi parametri facoltativi descritti nella scheda REST , ad esempio source_policy, excerpts, max_results e mode.

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 del modello da utilizzare.
  • TEXT: il prompt testuale da inviare al modello.
  • API_KEY: la tua chiave API per la ricerca web di Parallel. Se specifichi una chiave API e hai anche sottoscritto un abbonamento al grounding con la ricerca web di Parallel su Google Cloud Marketplace (anteprima), la chiave API ha la precedenza.
  • ENABLE_ZERO_DATA_RETENTION: (facoltativo) passa alla versione di conservazione zero dei dati della ricerca web di Parallel per attivare la conservazione zero dei dati sui carichi di lavoro sensibili. Imposta su true per utilizzare l'offerta di conservazione zero dei dati per la richiesta. Per il successo di queste richieste, devi aver sottoscritto l'offerta specifica di conservazione zero dei dati. Se non specificato, il valore predefinito è la versione standard. La versione di conservazione zero dei dati è disponibile solo tramite Google Cloud Marketplace.
  • EXCLUDE_DOMAINS: (facoltativo) elenco di domini da escludere dalle origini di grounding. Se specificato, le origini di questi domini vengono escluse. I valori accettabili sono domini (www.example.com) o estensioni di dominio che iniziano con un punto ( .gov, .edu, .co.uk). Puoi specificare fino a 200 domini.
  • INCLUDE_DOMAINS: (facoltativo) elenco di domini da includere nelle origini di grounding. Se specificato, le origini di questi domini vengono incluse. I valori accettabili sono domini (www.example.com) o estensioni di dominio che iniziano con un punto ( .gov, .edu, .co.uk). Puoi specificare fino a 200 domini.
  • MAX_CHARS_PER_RESULT: (facoltativo) il numero massimo di caratteri da includere in ogni estratto dei risultati di ricerca. Se non specificato, il valore predefinito è 30000. L'intervallo consentito è [1000, 100000].
  • MAX_CHARS_TOTAL: (facoltativo) il numero massimo totale di caratteri di tutti gli estratti dei risultati di ricerca. Se non specificato, il valore predefinito è 100000. L'intervallo consentito è [1000, 1000000].
  • MAX_RESULTS: (facoltativo) il numero massimo di risultati di ricerca da utilizzare per il grounding. Se non specificato, il valore predefinito è 10. L'intervallo consentito è [1, 20].
  • MODE: (facoltativo) la modalità da utilizzare per la richiesta, basic o advanced. Il valore predefinito è basic. Valuta la modalità advanced se vuoi risultati di ricerca più approfonditi a scapito di una latenza maggiore.
  • SEARCH_LOCATION: (facoltativo) codice paese ISO 3166-1 alpha-2 per i risultati di ricerca con targeting geografico. Esempio: "us".

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": [{
    "parallelAiSearch": {
        "api_key": "API_KEY",
        "enable_zero_data_retention": ENABLE_ZERO_DATA_RETENTION,
        "customConfigs": {
            "mode": "MODE",
            "location": "SEARCH_LOCATION",
            "max_results": MAX_RESULTS,
            "source_policy": {
                "exclude_domains": ["EXCLUDE_DOMAINS"],
                "include_domains": ["INCLUDE_DOMAINS"]
            },
            "excerpts": {
                "max_chars_per_result": MAX_CHARS_PER_RESULT,
                "max_chars_total": MAX_CHARS_TOTAL
            }
        }
    }
}],
  "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. Per richiedere un aumento dei limiti di frequenza, fornisci il caso d'uso e i requisiti al contatto appropriato:

  • Se hai sottoscritto un abbonamento al grounding con la ricerca web di Parallel su Google Cloud Marketplace (anteprima): contatta il team dell'account Google.

  • Se fornisci la tua chiave API: Contatta support@parallel.ai e il team dell'account Google.

Fatturazione

L'utilizzo del grounding con la ricerca web di Parallel comporta i seguenti addebiti:

  • Consumo di token Gemini: puoi ricevere addebiti per:

    • Token di prompt
    • Token di ragionamento
    • Token di output

    Per saperne di più, consulta i prezzi.

  • Grounding di Gemini con i tuoi dati: per saperne di più, consulta i prezzi.

  • Prezzi per l'utilizzo dell'API di ricerca web di Parallel:

    • Se hai sottoscritto un abbonamento al grounding con la ricerca web di Parallel su Google Cloud Marketplace (anteprima), consulta la sezione dei prezzi di Parallel su Google Cloud Marketplace per saperne di più.

    • Se fornisci la tua chiave API, consulta il sito web di Parallel per saperne di più.