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 knowledge cutoff.

La base di riferimento ti aiuta a creare applicazioni che possono:

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

• Fornisci citazioni:crea fiducia negli utenti mostrando le fonti delle affermazioni del modello.

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Who won the euro 2024?",
    tools=[{"type": "google_search"}]
)

print(interaction.output_text)

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

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3.5-flash",
    input: "Who won the euro 2024?",
    tools: [{ type: "google_search" }]
});

console.log(interaction.output_text);

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.5-flash",
    "input": "Who won the euro 2024?",
    "tools": [{"type": "google_search"}]
  }'

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 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 automaticamente una o più query di ricerca e le esegue.
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 testuale del modello con annotations in linea contenenti le citazioni, nonché i passaggi google_search_call e google_search_result con le query di ricerca e i suggerimenti di ricerca.

Informazioni sulla risposta di grounding

Quando una risposta viene fondata correttamente, l'output di testo del modello include annotations in linea direttamente nel blocco di contenuti di testo. Queste annotazioni forniscono informazioni sulle citazioni che collegano parti della risposta alle relative fonti.

{
  "steps": [
    {
      "type": "thought",
      "summary": [
        {
          "type": "text",
          "text": "The user is asking for the winner of Euro 2024. I need to search for the result of the Euro 2024 final."
        }
      ],
      "signature": "CoMDAXLI2nynRYojJIy6B1Jh9os2crpWLfB0..."
    },
    {
      "type": "google_search_call",
      "arguments": {
        "queries": ["UEFA Euro 2024 winner"]
      }
    },
    {
      "type": "google_search_result",
      "call_id": "search_001",
      "result": [
        {
          "search_suggestions": "<!-- HTML and CSS for the search widget -->"
        }
      ]
    },
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.aljazeera.com/sports/euro-2024-final",
              "title": "aljazeera.com",
              "start_index": 0,
              "end_index": 56
            },
            {
              "type": "url_citation",
              "url": "https://www.uefa.com/euro2024/news/spain-wins-euro-2024",
              "title": "uefa.com",
              "start_index": 57,
              "end_index": 124
            }
          ]
        }
      ]
    }
  ]
}

I campi chiave nella risposta:

• google_search_call : contiene la ricerca queries eseguita dal modello.
• google_search_result : contiene search_suggestions, uno snippet HTML per il rendering dei suggerimenti di ricerca nella tua UI. I requisiti di utilizzo completi sono descritti nei Termini di servizio.
• text con annotations : la risposta sintetizzata del modello con citazioni in linea. Ogni annotazione url_citation collega un segmento di testo (definito da start_index e end_index) a un URL di origine. Questo è il segreto per creare citazioni in linea.

L'ancoraggio con la Ricerca Google può essere utilizzato anche in combinazione con lo strumento di contesto URL per ancorare le risposte sia ai dati web pubblici sia agli URL specifici che fornisci.

Attribuire le fonti con le citazioni in linea

L'API restituisce annotazioni url_citation in linea sul blocco di contenuti di testo, offrendoti il controllo completo sulla modalità di visualizzazione delle fonti nell'interfaccia utente. Ogni annotazione include start_index e end_index per identificare la parte del testo che cita. Ecco come estrarli e visualizzarli.

for step in interaction.steps:
    if step.type == "model_output":
        for content_block in step.content:
            if content_block.type == "text":
                print(content_block.text)
                if content_block.annotations:
                    print("\nCitations:")
                    for annotation in content_block.annotations:
                        if annotation.type == "url_citation":
                            cited_text = content_block.text[annotation.start_index:annotation.end_index]
                            print(f"  [{annotation.title}]({annotation.url})")
                            print(f"    Cited text: \"{cited_text}\"")

for (const step of interaction.steps) {
  if (step.type === 'model_output') {
    for (const contentBlock of step.content) {
      if (contentBlock.type === 'text') {
        console.log(contentBlock.text);
        if (contentBlock.annotations) {
          console.log("\nCitations:");
          for (const annotation of contentBlock.annotations) {
            if (annotation.type === 'url_citation') {
              const citedText = contentBlock.text.slice(annotation.startIndex, annotation.endIndex);
              console.log(`  [${annotation.title}](${annotation.url})`);
              console.log(`    Cited text: "${citedText}"`);
            }
          }
        }
      }
    }
  }
}

L'output mostrerà il testo seguito dalle relative citazioni:

Spain won Euro 2024, defeating England 2-1 in the final. This victory marks Spain's record fourth European Championship title.

Citations:
  [aljazeera.com](https://www.aljazeera.com/sports/euro-2024-final)
    Cited text: "Spain won Euro 2024, defeating England 2-1 in the final."
  [uefa.com](https://www.uefa.com/euro2024/news/spain-wins-euro-2024)
    Cited text: "This victory marks Spain's record fourth European Championship title."

Prezzi

Quando utilizzi Grounding con la Ricerca Google con Gemini 3, il tuo progetto viene fatturato 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 conteggiato come due utilizzi fatturabili dello strumento per quella richiesta. Ai fini della fatturazione, ignoriamo le query di ricerca web vuote quando conteggiamo le query uniche. Questo modello di fatturazione si applica solo ai modelli Gemini 3. Quando utilizzi la ricerca basata su grounding con Gemini 2.5 o modelli precedenti, il tuo progetto viene fatturato per prompt.

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

Modelli supportati

Puoi trovare le funzionalità complete nella pagina Panoramica modello.

Combinazioni di strumenti supportate

Puoi utilizzare 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 Grounding con la Ricerca Google) con strumenti personalizzati (chiamata di funzioni). Scopri di più nella pagina Combinazioni di strumenti.

Passaggi successivi

• Scopri altri strumenti disponibili, come la chiamata di funzione.
• Scopri come arricchire i prompt con URL specifici utilizzando lo strumento Contesto URL.