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

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

from google import genai

client = genai.Client()

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

# Print the model's text response
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)

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

const client = new GoogleGenAI({});

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

const modelStep = interaction.steps.find(s => s.type === 'model_output');
if (modelStep) {
  for (const contentBlock of modelStep.content) {
    if (contentBlock.type === 'text') console.log(contentBlock.text);
  }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash-preview",
    "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 dell'utente: la tua applicazione invia un prompt dell'utente all'API Gemini con lo strumento google_search attivato.
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 con grounding: l'API restituisce una risposta finale e di facile utilizzo basata sui risultati di ricerca. Questa risposta include la risposta di testo 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 con grounding

Quando una risposta viene basata 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 le queries di ricerca eseguite dal modello.
• google_search_result : contiene search_suggestions, uno snippet HTML per il rendering dei suggerimenti di ricerca nell'interfaccia utente. 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 modo principale 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 annotazioni url_citation in linea nel 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 di 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 il grounding con la Ricerca Google con Gemini 3, al tuo progetto vengono addebitate le 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 uniche. Questo modello di fatturazione si applica solo ai modelli Gemini 3; quando utilizzi il grounding di ricerca con i modelli Gemini 2.5 o precedenti, al tuo progetto viene addebitato un costo 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 funzioni). Scopri di più nella pagina delle combinazioni di strumenti.

Passaggi successivi

• Scopri di più sugli altri strumenti disponibili, come la chiamata di funzioni.
• Scopri come aumentare i prompt con URL specifici utilizzando lo strumento di contesto URL.