Grounding con la Ricerca Google

Questa pagina spiega come basare le risposte di Gemini sui risultati del motore di ricerca di Google, che utilizza dati web disponibili pubblicamente. Inoltre, vengono spiegate le ricerche suggerite, che sono incluse nelle risposte.

Se vuoi connettere il tuo modello alla conoscenza del mondo, a un'ampia gamma possibile di argomenti o a informazioni aggiornate su internet, utilizza il grounding con la Ricerca Google.

Per scoprire di più sul grounding dei modelli in Vertex AI, consulta la Panoramica del grounding.

Modelli supportati

Questa sezione elenca i modelli che supportano il grounding con la Ricerca.

Lingue supportate

Per un elenco delle lingue supportate, consulta la sezione Lingue.

Segui le istruzioni riportate di seguito per basare un modello su dati web disponibili pubblicamente.

Considerazioni

I risultati di ricerca possono essere personalizzati per una posizione geografica specifica dell'utente finale utilizzando le coordinate di latitudine e longitudine. Per saperne di più, consulta l'API Grounding.

Console

Per utilizzare il grounding con la Ricerca Google con Vertex AI Studio, segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Vertex AI Studio.

    Vai a Vertex AI Studio

  2. Fai clic sulla scheda Formato libero.
  3. Nel riquadro laterale, fai clic sul pulsante di attivazione/disattivazione Risposte del modello di base.
  4. Fai clic su Personalizza e imposta Grounding con la Ricerca Google come origine.
  5. Inserisci il prompt nella casella di testo e fai clic su Invia.

Le risposte ai prompt ora utilizzano il grounding con la Ricerca Google.

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 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_VERTEXAI=True
 

from google import genai
from google.genai.types import (
    GenerateContentConfig,
    GoogleSearch,
    HttpOptions,
    Tool,
)

client = genai.Client(http_options=HttpOptions(api_version="v1"))

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="When is the next total solar eclipse in the United States?",
    config=GenerateContentConfig(
        tools=[
            # Use Google Search Tool
            Tool(
                google_search=GoogleSearch(
                    # Optional: Domains to exclude from results
                    exclude_domains=["domain.com", "domain2.com"]
                )
            )
        ],
    ),
)

print(response.text)
# Example response:
# 'The next total solar eclipse in the United States will occur on ...'

Go

Scopri come installare o aggiornare Go.

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

Imposta le variabili di ambiente per utilizzare l'SDK 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_VERTEXAI=True
 

import (
	"context"
	"fmt"
	"io"

	genai "google.golang.org/genai"
)

// generateWithGoogleSearch shows how to generate text using Google Search.
func generateWithGoogleSearch(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := []*genai.Content{
		{Parts: []*genai.Part{
			{Text: "When is the next total solar eclipse in the United States?"},
		},
			Role: genai.RoleUser},
	}
	config := &genai.GenerateContentConfig{
		Tools: []*genai.Tool{
			{GoogleSearch: &genai.GoogleSearch{ExcludeDomains: []string{"example.com", "example.org"}}},
		},
	}

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, config)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// The next total solar eclipse in the United States will occur on March 30, 2033, but it will only ...

	return nil
}

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 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_VERTEXAI=True
 


import com.google.genai.Client;
import com.google.genai.types.GenerateContentConfig;
import com.google.genai.types.GenerateContentResponse;
import com.google.genai.types.GoogleSearch;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.Tool;

public class ToolsGoogleSearchWithText {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String modelId = "gemini-2.5-flash";
    generateContent(modelId);
  }

  // Generates content with Google Search tool
  public static String generateContent(String modelId) {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      // Create a GenerateContentConfig and set Google Search tool
      GenerateContentConfig contentConfig =
          GenerateContentConfig.builder()
              .tools(Tool.builder().googleSearch(GoogleSearch.builder().build()).build())
              .build();

      GenerateContentResponse response =
          client.models.generateContent(
              modelId, "When is the next total solar eclipse in the United States?", contentConfig);

      System.out.print(response.text());
      // Example response:
      // The next total solar eclipse in the United States will occur on...
      return response.text();
    }
  }
}

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 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_VERTEXAI=True
 

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';

async function generateGoogleSearch(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
  });

  const response = await client.models.generateContent({
    model: 'gemini-2.5-flash',
    contents: 'When is the next total solar eclipse in the United States?',
    config: {
      tools: [
        {
          googleSearch: {},
        },
      ],
    },
  });

  console.log(response.text);

  // Example response:
  //    'The next total solar eclipse in United States will occur on ...'

  return 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 globale.
  • PROJECT_ID: il tuo ID progetto
  • MODEL_ID: l'ID modello del modello multimodale.
  • TEXT: le istruzioni di testo da includere nel prompt.
  • EXCLUDE_DOMAINS: (Facoltativo) Elenco dei domini da non utilizzare per la contestualizzazione.
  • LATITUDE: (Facoltativo) La latitudine della posizione dell'utente finale. Ad esempio, una latitudine di 37.7749 rappresenta San Francisco. Puoi ottenere le coordinate di latitudine e longitudine utilizzando servizi come Google Maps o altri strumenti di geocodifica.
  • LONGITUDE: (facoltativo) la longitudine della posizione dell'utente finale. Ad esempio, una longitudine di -122.4194 rappresenta San Francisco.

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": [{
    "googleSearch": {
      "exclude_domains": [ "domain.com", "domain2.com" ]
    }
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      }
    }
  },
  "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:

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": "The weather in Chicago this weekend, will be partly cloudy. The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday. There is a slight chance of rain on both days.\n"
          }
        ]
      },
      "finishReason": "STOP",
      "groundingMetadata": {
        "webSearchQueries": [
          "weather in Chicago this weekend"
        ],
        "searchEntryPoint": {
          "renderedContent": "..."
        },
        "groundingChunks": [
          {
            "web": {
              "uri": "https://www.google.com/search?q=weather+in+Chicago,+IL",
              "title": "Weather information for locality: Chicago, administrative_area: IL",
              "domain": "google.com"
            }
          },
          {
            "web": {
              "uri": "...",
              "title": "weatherbug.com",
              "domain": "weatherbug.com"
            }
          }
        ],
        "groundingSupports": [
          {
            "segment": {
              "startIndex": 85,
              "endIndex": 214,
              "text": "The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday."
            },
            "groundingChunkIndices": [
              0
            ],
            "confidenceScores": [
              0.8662828
            ]
          },
          {
            "segment": {
              "startIndex": 215,
              "endIndex": 261,
              "text": "There is a slight chance of rain on both days."
            },
            "groundingChunkIndices": [
              1,
              0
            ],
            "confidenceScores": [
              0.62836814,
              0.6488607
            ]
          }
        ],
        "retrievalMetadata": {}
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 98,
    "totalTokenCount": 108,
    "trafficType": "ON_DEMAND",
    "promptTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 10
      }
    ],
    "candidatesTokensDetails": [
      {
        "modality": "TEXT",
        "tokenCount": 98
      }
    ]
  },
  "modelVersion": "gemini-2.0-flash",
  "createTime": "2025-05-19T14:42:55.000643Z",
  "responseId": "b0MraIMFoqnf-Q-D66G4BQ"
}

La fondatezza con Google Ricerca immagini consente ai modelli di utilizzare le immagini web recuperate da Google Ricerca immagini come contesto visivo durante la generazione di immagini. La ricerca di immagini di Google è un nuovo tipo di ricerca all'interno dello strumento esistente Grounding with Google Search ed esiste insieme alla Ricerca Google standard. Il grounding con la Ricerca immagini di Google è disponibile in anteprima solo per il modello Gemini 3.1 Flash Image.

Configurazione della richiesta API

Per attivare la ricerca immagini di Google, configura lo strumento googleSearch nella richiesta API e specifica imageSearch all'interno dell'oggetto searchTypes. Puoi utilizzare Google Ricerca immagini in modo indipendente o con la Ricerca Google.

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 globale.
  • PROJECT_ID: .
  • MODEL_ID: l'ID modello del modello multimodale.
  • SEARCH_TERM: Un termine di ricerca per un'immagine.

    • 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": "SEARCH_TERM"
        }
      ]
    }
  ],
  "tools": [
    {
      "googleSearch": {
        "searchTypes": {
          "imageSearch": {},
          "webSearch": {}
        }
      }
    }
  ],
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

    Per inviare la richiesta, scegli una di queste opzioni:

    curl

    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; charset=utf-8" \
         -d @request.json \
         "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

    PowerShell

    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/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

    Dovresti ricevere un codice di stato riuscito (2xx) e una risposta vuota.

Requisiti di visualizzazione

Quando utilizzi la Ricerca immagini Google con Grounding con la Ricerca Google, devi rispettare le seguenti condizioni:

  • Attribuzione della fonte: devi fornire un link alla pagina web che contiene l'immagine di origine (la "pagina contenente", non il file immagine stesso) in modo che l'utente lo riconosca come link.

  • Navigazione diretta: se scegli anche di mostrare le immagini di origine, devi fornire un percorso diretto con un solo clic dalle immagini di origine alla pagina web di origine che le contiene. Non è consentita qualsiasi altra implementazione che ritardi o astragga l'accesso degli utenti finali alle pagine web di origine, inclusi, a titolo esemplificativo ma non esaustivo, qualsiasi percorso a più clic o l'utilizzo di un visualizzatore di immagini intermedio.

Risposta

Per le risposte basate sulla ricerca immagini, l'API fornisce un'attribuzione chiara e metadati per collegare il suo output a fonti verificate. L'oggetto groundingMetadata include i seguenti campi:

  • imageSearchQueries: la query specifica utilizzata dal modello per il contesto visivo (nota anche come "ricerca immagini").

  • groundingChunks: contiene le informazioni sull'origine dei risultati recuperati. Per le origini immagini, questi vengono restituiti come URL di reindirizzamento utilizzando un nuovo tipo di blocco di immagini. Il blocco include quanto segue:

    • url: l'URL della pagina web per l'attribuzione (noto anche come "pagina di destinazione").
    • image_url: l'URL diretto dell'immagine.

  • groundingSupports: fornisce mappature specifiche che collegano i contenuti generati alla fonte di citazione pertinente nei chunk.

  • searchEntryPoint: include il chip di ricerca che contiene HTML e CSS conformi per il rendering dei suggerimenti di ricerca.

Comprendere la risposta

Se il prompt del modello utilizza correttamente Grounding con la Ricerca Google da Vertex AI Studio o dall'API, le risposte includono metadati con link alle fonti (URL web). Tuttavia, esistono diversi motivi per cui questi metadati potrebbero non essere forniti e la risposta del prompt non sarà basata su dati reali. Questi motivi includono una bassa pertinenza delle fonti o informazioni incomplete nella risposta del modello.

Citazioni in linea

Le citazioni in linea utilizzano il grounding_metadata strutturato restituito dall'API per collegare segmenti specifici di testo generato a fonti verificabili.

Questa funzionalità supporta tutti i metodi di fondatezza, tra cui Ricerca, Google Maps e Vertex AI Search, fornendo i dettagli precisi della fonte necessari per visualizzare citazioni accurate e interattive all'interno dell'applicazione.

response = client.models.generate_content(
   model="gemini-3.1-pro-preview",
   contents="Where will the next FIFA World Cup be held?",
   config=types.GenerateContentConfig(
       tools=[types.Tool(google_search=types.GoogleSearch())],
   ),
)

display(Markdown(response.text))
print(response.candidates[0].grounding_metadata.grounding_chunks)
display(HTML(response.candidates[0].grounding_metadata.search_entry_point.rendered_content))

Output di esempio:

…

Citations:
Wikipedia. "2026 FIFA World Cup." Retrieved February 11, 2026. (https://en.wikipedia.org/wiki/2026_FIFA_World_Cup)
US Soccer Players. "2026 FIFA World Cup FAQ — Dates, Hosts, Tickets, Teams & More." (https://ussoccerplayers.com/2026-fifa-world-cup-faq)
Holafly. "2026 World Cup host cities and countries: Full list of stadiums." (https://travel.holafly.com/esims/2026-world-cup-host-cities/)
…

Supporto per il grounding

La visualizzazione del supporto per la base è obbligatoria, perché ti aiuta a convalidare le risposte degli editori e aggiunge modi per approfondire l'apprendimento.

Il supporto della contestualizzazione per le risposte provenienti da fonti web deve essere mostrato sia in linea che in forma aggregata. Ad esempio, guarda l'immagine che segue per un suggerimento su come farlo.

Esempi di supporto della fondatezza

Utilizzo di opzioni alternative per i motori di ricerca

Quando utilizzi il Grounding con la Ricerca Google, un'Applicazione del Cliente può:

  • Offrire opzioni di motori di ricerca alternativi,
  • Impostare altri motori di ricerca come opzione predefinita.
  • Mostrare i propri suggerimenti di ricerca o risultati di ricerca o quelli di terze parti, a condizione che: tutti i risultati non Google vengano visualizzati separatamente dai risultati fondati e dai suggerimenti di ricerca di Google e mostrati in modo da non confondere gli utenti o suggerire che provengano da Google.

Vantaggi

I seguenti prompt e flussi di lavoro complessi che richiedono pianificazione, ragionamento e pensiero possono essere eseguiti quando utilizzi Grounding con la Ricerca Google come strumento:

  • Puoi basarti su informazioni aggiornate e accurate per assicurarti che le risposte siano pertinenti.
  • Puoi recuperare artefatti dal web per eseguire l'analisi.
  • Puoi trovare immagini, video o altri contenuti multimediali pertinenti per aiutarti nel ragionamento multimodale o nella generazione di attività.
  • Puoi eseguire attività di programmazione, risoluzione dei problemi tecnici e altre attività specializzate.
  • Puoi trovare informazioni specifiche per regione o contribuire a tradurre i contenuti in modo accurato.
  • Puoi trovare siti web pertinenti da sfogliare.

Utilizzare i suggerimenti della Ricerca Google

Quando utilizzi Grounding con la Ricerca Google e ricevi suggerimenti di ricerca nella risposta, devi visualizzarli in produzione e nelle tue applicazioni.

In particolare, devi mostrare le query di ricerca incluse nei metadati della risposta basata su dati reali. La risposta include:

  • "content": risposta generata tramite LLM.
  • "webSearchQueries": le query da utilizzare per i suggerimenti di ricerca.

Ad esempio, nel seguente snippet di codice, Gemini risponde a un prompt basato sulla Ricerca, che chiede informazioni su un tipo di pianta tropicale.

"predictions": [
  {
    "content": "Monstera is a type of vine that thrives in bright indirect light…",
    "groundingMetadata": {
      "webSearchQueries": ["What's a monstera?"],
    }
  }
]

Puoi prendere questo output e visualizzarlo utilizzando i suggerimenti di ricerca.

Requisiti per i suggerimenti di ricerca

Per i suggerimenti di ricerca sono necessari i seguenti requisiti:

Requisito Descrizione
Azioni consigliate
  • Nel rispetto dei requisiti di visualizzazione, il suggerimento di ricerca viene visualizzato esattamente come fornito, senza alcuna modifica.
  • Quando interagisci con il suggerimento di ricerca, viene visualizzata direttamente la pagina dei risultati di ricerca.
Cosa non fare
  • Includi eventuali schermate o passaggi aggiuntivi tra il tocco dell'utente e la visualizzazione della pagina dei risultati di ricerca.
  • Visualizza altri risultati di ricerca o suggerimenti accanto al Suggerimento di ricerca o alla risposta LLM fondata associata.

Requisiti di visualizzazione

Di seguito sono riportati i requisiti di visualizzazione:

  • Visualizza il suggerimento di ricerca esattamente come fornito e non apportare modifiche a colori, caratteri o aspetto. Assicurati che il suggerimento di ricerca venga visualizzato come specificato nei seguenti mockup, ad esempio in modalità Buio e Luce:

  • Ogni volta che viene mostrata una risposta basata su fonti, il relativo suggerimento di ricerca deve rimanere visibile.
  • Per il branding, devi seguire rigorosamente le linee guida di Google per l'utilizzo da parte di terzi degli elementi distintivi del brand Google, disponibili nel Centro risorse per il brand.
  • Quando utilizzi il grounding con la Ricerca, vengono visualizzati i chip dei suggerimenti di ricerca. Il campo che contiene i chip dei suggerimenti per la ricerca deve avere la stessa larghezza della risposta fondata dell'LLM.

Comportamento con un tocco

Quando un utente tocca il chip, viene indirizzato direttamente a una pagina dei risultati di ricerca per il termine di ricerca visualizzato nel chip. La pagina dei risultati di ricerca può aprirsi nel browser in-app o in un'applicazione browser separata. È importante non ridurre a icona, rimuovere o ostacolare in alcun modo la visualizzazione della pagina dei risultati di ricerca. Il seguente mockup animato illustra l'interazione tocca e vai alla pagina dei risultati di ricerca.

app/desktop example

Codice per implementare un suggerimento di ricerca

Quando utilizzi l'API per basare una risposta sulla ricerca, la risposta del modello fornisce uno stile HTML e CSS conforme nel campo renderedContent, che implementi per visualizzare i suggerimenti di ricerca nella tua applicazione.

Inoltre, i suggerimenti di ricerca erano precedentemente denominati Punti di inserimento per la ricerca. Anche se in alcuni campi dell'API potresti trovare riferimenti ai punti di ingresso della ricerca, entrambi i termini si riferiscono ai suggerimenti di ricerca attuali che ricevi nella risposta dell'API.

Modifiche alla fatturazione con Gemini 3

Quando utilizzi il Grounding con la Ricerca Google sui modelli Gemini 3, la fatturazione avviene per ogni query di ricerca generata da Gemini e inviata alla Ricerca. Un singolo prompt può generare una o più query di ricerca.

Esempio

Questo esempio mostra un prompt utente e query di ricerca di esempio che potrebbero essere soggetti a costi.

  • Prompt dell'utente: Raccontami la vita di Albert Einstein.
  • Gemini potrebbe generare queste query di ricerca:
    • Nascita e istruzione della prima infanzia di Albert Einstein
    • Teoria della relatività di Albert Einstein
    • La vita di Albert Einstein negli Stati Uniti

In questo esempio, queste tre query di ricerca vengono addebitate.

Passaggi successivi