Grounding con la Ricerca Google

Il grounding con la Ricerca Google collega il modello Gemini ai contenuti web in tempo reale e funziona con tutte le lingue disponibili. In questo modo, Gemini può fornire risposte più accurate e citare fonti verificabili oltre il suo limite di conoscenza.

Il grounding ti aiuta a creare applicazioni in grado di:

• Aumentare l'accuratezza fattuale: ridurre le allucinazioni del modello basando le risposte su informazioni del mondo reale.
• Accedere a informazioni in tempo reale: rispondere a domande su eventi e argomenti recenti.

• Fornire citazioni: creare fiducia negli utenti mostrando le fonti delle affermazioni del modello.

from google import genai
from google.genai import types

client = genai.Client()

grounding_tool = types.Tool(
    google_search=types.GoogleSearch()
)

config = types.GenerateContentConfig(
    tools=[grounding_tool]
)

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Who won the euro 2024?",
    config=config,
)

print(response.text)

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

const ai = new GoogleGenAI({});

const groundingTool = {
  googleSearch: {},
};

const config = {
  tools: [groundingTool],
};

const response = await ai.models.generateContent({
  model: "gemini-3-flash-preview",
  contents: "Who won the euro 2024?",
  config,
});

console.log(response.text);

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "Who won the euro 2024?"}
        ]
      }
    ],
    "tools": [
      {
        "google_search": {}
      }
    ]
  }'

Per saperne di più, prova il notebook dello strumento di ricerca.

Come funziona il grounding con la Ricerca Google

Quando attivi lo strumento google_search, il modello gestisce automaticamente l'intero flusso di lavoro di ricerca, elaborazione e citazione delle informazioni.

1. Prompt dell'utente: la tua applicazione invia un prompt dell'utente all'API Gemini con lo strumento google_search abilitato.
2. Analisi del prompt: il modello analizza il prompt e determina se una Ricerca Google può migliorare la risposta.
3. Ricerca Google: se necessario, il modello genera ed esegue automaticamente una o più query di ricerca.
4. Elaborazione dei risultati di ricerca: il modello elabora i risultati di ricerca, sintetizza le informazioni e formula una risposta.
5. Risposta fondata: l'API restituisce una risposta finale e di facile utilizzo basata sui risultati di ricerca. Questa risposta include la risposta di testo del modello e groundingMetadata con le query di ricerca, i risultati web e le citazioni.

Informazioni sulla risposta di grounding

Quando una risposta viene fondata correttamente, include un campo groundingMetadata. Questi dati strutturati sono essenziali per verificare le affermazioni e creare un'esperienza di citazione completa nella tua applicazione.

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title."
          }
        ],
        "role": "model"
      },
      "groundingMetadata": {
        "webSearchQueries": [
          "UEFA Euro 2024 winner",
          "who won euro 2024"
        ],
        "searchEntryPoint": {
          "renderedContent": "<!-- HTML and CSS for the search widget -->"
        },
        "groundingChunks": [
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "aljazeera.com"}},
          {"web": {"uri": "https://vertexaisearch.cloud.google.com.....", "title": "uefa.com"}}
        ],
        "groundingSupports": [
          {
            "segment": {"startIndex": 0, "endIndex": 85, "text": "Spain won Euro 2024, defeatin..."},
            "groundingChunkIndices": [0]
          },
          {
            "segment": {"startIndex": 86, "endIndex": 210, "text": "This victory marks Spain's..."},
            "groundingChunkIndices": [0, 1]
          }
        ]
      }
    }
  ]
}

L'API Gemini restituisce le seguenti informazioni con groundingMetadata:

• webSearchQueries : array delle query di ricerca utilizzate. È utile per il debug e per comprendere il processo di ragionamento del modello.
• searchEntryPoint : contiene il codice HTML e CSS per eseguire il rendering dei suggerimenti di ricerca richiesti. I requisiti di utilizzo completi sono descritti nei Termini di servizio.
• groundingChunks : array di oggetti contenenti le fonti web (uri e title).
• groundingSupports : array di blocchi per collegare il text della risposta del modello alle fonti in groundingChunks. Ogni blocco collega un segment di testo (definito da startIndex e endIndex) a uno o più groundingChunkIndices. Questa è la chiave per creare citazioni in linea.

Il grounding con la Ricerca Google può essere utilizzato anche in combinazione con lo strumento di contesto URL per basare le risposte sia sui dati web pubblici sia sugli URL specifici che fornisci.

Attribuzione delle fonti con citazioni in linea

L'API restituisce dati di citazione strutturati, offrendoti il controllo completo sulla modalità di visualizzazione delle fonti nell'interfaccia utente. Puoi utilizzare i campi groundingSupports e groundingChunks per collegare direttamente le affermazioni del modello alle relative fonti. Di seguito è riportato un pattern comune per l'elaborazione dei metadati al fine di creare una risposta con citazioni in linea su cui è possibile fare clic.

def add_citations(response):
    text = response.text
    supports = response.candidates[0].grounding_metadata.grounding_supports
    chunks = response.candidates[0].grounding_metadata.grounding_chunks

    # Sort supports by end_index in descending order to avoid shifting issues when inserting.
    sorted_supports = sorted(supports, key=lambda s: s.segment.end_index, reverse=True)

    for support in sorted_supports:
        end_index = support.segment.end_index
        if support.grounding_chunk_indices:
            # Create citation string like [1](link1)[2](link2)
            citation_links = []
            for i in support.grounding_chunk_indices:
                if i < len(chunks):
                    uri = chunks[i].web.uri
                    citation_links.append(f"[{i + 1}]({uri})")

            citation_string = ", ".join(citation_links)
            text = text[:end_index] + citation_string + text[end_index:]

    return text

# Assuming response with grounding metadata
text_with_citations = add_citations(response)
print(text_with_citations)

function addCitations(response) {
    let text = response.text;
    const supports = response.candidates[0]?.groundingMetadata?.groundingSupports;
    const chunks = response.candidates[0]?.groundingMetadata?.groundingChunks;

    // Sort supports by end_index in descending order to avoid shifting issues when inserting.
    const sortedSupports = [...supports].sort(
        (a, b) => (b.segment?.endIndex ?? 0) - (a.segment?.endIndex ?? 0),
    );

    for (const support of sortedSupports) {
        const endIndex = support.segment?.endIndex;
        if (endIndex === undefined || !support.groundingChunkIndices?.length) {
        continue;
        }

        const citationLinks = support.groundingChunkIndices
        .map(i => {
            const uri = chunks[i]?.web?.uri;
            if (uri) {
            return `[${i + 1}](${uri})`;
            }
            return null;
        })
        .filter(Boolean);

        if (citationLinks.length > 0) {
        const citationString = citationLinks.join(", ");
        text = text.slice(0, endIndex) + citationString + text.slice(endIndex);
        }
    }

    return text;
}

const textWithCitations = addCitations(response);
console.log(textWithCitations);

La nuova risposta con citazioni in linea sarà simile alla seguente:

Spain won Euro 2024, defeating England 2-1 in the final.[1](https:/...), [2](https:/...), [4](https:/...), [5](https:/...) This victory marks Spain's record-breaking fourth European Championship title.[5]((https:/...), [2](https:/...), [3](https:/...), [4](https:/...)

Prezzi

Quando utilizzi il grounding con la Ricerca Google con Gemini 3, al tuo progetto vengono addebitati i costi per ogni query di ricerca che il modello decide di eseguire. Se il modello decide di eseguire più query di ricerca per rispondere a un singolo prompt (ad esempio, cercando "UEFA Euro 2024 winner" e "Spain vs England Euro 2024 final score" nella stessa chiamata API), questo viene considerato come due utilizzi fatturabili dello strumento per quella richiesta. Ai fini della fatturazione, ignoriamo le query di ricerca web vuote quando contiamo le query univoche. Questo modello di fatturazione si applica solo ai modelli Gemini 3; quando utilizzi il grounding di ricerca con Gemini 2.5 o modelli precedenti, al tuo progetto vengono addebitati i costi per prompt.

Per informazioni dettagliate sui prezzi, consulta la pagina dei prezzi dell'API Gemini.

Modelli supportati

Puoi trovare le funzionalità complete nella pagina di panoramica del modello.

Combinazioni di strumenti supportate

Puoi utilizzare il grounding con la Ricerca Google con altri strumenti come l'esecuzione di codice e il contesto URL per supportare casi d'uso più complessi.

I modelli Gemini 3 supportano la combinazione di strumenti integrati (come il grounding con la Ricerca Google) con strumenti personalizzati (chiamata di funzione). Scopri di più nella pagina delle combinazioni di strumenti.

Passaggi successivi

• Prova il grounding con la Ricerca Google nell'API Gemini Cookbook.
• Scopri di più sugli altri strumenti disponibili, come la chiamata di funzione.
• Scopri come aumentare i prompt con URL specifici utilizzando lo strumento di contesto URL.