Grounding con la Ricerca Google

La funzionalità di 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 la soglia di conoscenza.

La messa a terra ti aiuta a creare applicazioni che possono:

  • Aumenta l'accuratezza fattuale: riduci le allucinazioni del modello basando le risposte su informazioni reali.
  • Accedi alle informazioni in tempo reale:rispondi a domande su eventi e argomenti recenti.
  • Fornisci citazioni:conquista la fiducia degli utenti mostrando le fonti delle affermazioni del modello.

Python

from google import genai
from google.genai import types

# Configure the client
client = genai.Client()

# Define the grounding tool
grounding_tool = types.Tool(
    google_search=types.GoogleSearch()
)

# Configure generation settings
config = types.GenerateContentConfig(
    tools=[grounding_tool]
)

# Make the request
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Who won the euro 2024?",
    config=config,
)

# Print the grounded response
print(response.text)

JavaScript

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

// Configure the client
const ai = new GoogleGenAI();

// Define the grounding tool
const groundingTool = {
  googleSearch: {},
};

// Configure generation settings
const config = {
  tools: [groundingTool],
};

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

// Print the grounded response
console.log(response.text);

REST

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

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

Come funziona la messa a terra 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.

grounding-overview

  1. Richiesta utente:l'applicazione invia una richiesta 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 su Google può migliorare la risposta.
  3. Ricerca Google:se necessario, il modello genera automaticamente una o più query di ricerca ed esegue.
  4. Elaborazione dei risultati di ricerca:il modello elabora i risultati di ricerca, sintetizza le informazioni e formula una risposta.
  5. Risposta basata su dati:l'API restituisce una risposta finale facile da usare 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 messa a terra

Quando una risposta viene basata 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. Questo è utile per il debug e la comprensione del processo di ragionamento del modello.
  • searchEntryPoint : contiene il codice HTML e CSS per visualizzare i suggerimenti di ricerca richiesti. I requisiti di utilizzo completi sono descritti nei Termini di servizio.
  • groundingChunks : array di oggetti contenenti le origini web (uri e title).
  • groundingSupports : array di chunk per collegare la risposta del modello text alle origini in groundingChunks. Ogni chunk collega un testo segment (definito da startIndex e endIndex) a uno o più groundingChunkIndices. Questo è il segreto per creare citazioni in linea.

La verifica della fondatezza con la Ricerca Google può essere utilizzata anche in combinazione con lo strumento 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 sulle citazioni strutturate, dandoti il controllo completo sulla modalità di visualizzazione delle fonti nell'interfaccia utente. Puoi utilizzare i campi groundingSupports e groundingChunks per collegare le istruzioni del modello direttamente alle relative origini. Ecco un pattern comune per l'elaborazione dei metadati al fine di creare una risposta con citazioni in linea cliccabili.

Python

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)

JavaScript

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 Grounding con la Ricerca Google, il tuo progetto viene fatturato in base alla richiesta API che include lo strumento google_search. Se il modello decide di eseguire più query di ricerca per rispondere a un singolo prompt (ad esempio, la ricerca di "UEFA Euro 2024 winner" e "Spain vs England Euro 2024 final score" all'interno della stessa chiamata API), viene conteggiato un singolo utilizzo fatturabile dello strumento per quella richiesta.

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

Modelli supportati

I modelli sperimentali e di anteprima non sono inclusi. Puoi trovare le relative funzionalità nella pagina Panoramica del modello.

Modello Grounding con la Ricerca Google
Gemini 2.5 Pro ✔️
Gemini 2.5 Flash ✔️
Gemini 2.0 Flash ✔️
Gemini 1.5 Pro ✔️
Gemini 1.5 Flash ✔️

Messa a terra con i modelli Gemini 1.5 (legacy)

Sebbene lo strumento google_search sia consigliato per Gemini 2.0 e versioni successive, Gemini 1.5 supporta uno strumento precedente denominato google_search_retrieval. Questo strumento fornisce una modalità dynamic che consente al modello di decidere se eseguire una ricerca in base alla sua certezza che il prompt richieda informazioni aggiornate. Se l'affidabilità del modello è superiore a un valore dynamic_threshold impostato (un valore compreso tra 0,0 e 1,0), verrà eseguita una ricerca.

Python

# Note: This is a legacy approach for Gemini 1.5 models.
# The 'google_search' tool is recommended for all new development.
import os
from google import genai
from google.genai import types

client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

retrieval_tool = types.Tool(
    google_search_retrieval=types.GoogleSearchRetrieval(
        dynamic_retrieval_config=types.DynamicRetrievalConfig(
            mode=types.DynamicRetrievalConfigMode.MODE_DYNAMIC,
            dynamic_threshold=0.7 # Only search if confidence > 70%
        )
    )
)

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

response = client.models.generate_content(
    model='gemini-1.5-flash',
    contents="Who won the euro 2024?",
    config=config,
)
print(response.text)
if not response.candidates[0].grounding_metadata:
  print("\nModel answered from its own knowledge.")

JavaScript

// Note: This is a legacy approach for Gemini 1.5 models.
// The 'googleSearch' tool is recommended for all new development.
import { GoogleGenAI, DynamicRetrievalConfigMode } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const retrievalTool = {
  googleSearchRetrieval: {
    dynamicRetrievalConfig: {
      mode: DynamicRetrievalConfigMode.MODE_DYNAMIC,
      dynamicThreshold: 0.7, // Only search if confidence > 70%
    },
  },
};

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

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

console.log(response.text);
if (!response.candidates?.[0]?.groundingMetadata) {
  console.log("\nModel answered from its own knowledge.");
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "contents": [
      {"parts": [{"text": "Who won the euro 2024?"}]}
    ],
    "tools": [{
      "google_search_retrieval": {
        "dynamic_retrieval_config": {
          "mode": "MODE_DYNAMIC",
          "dynamic_threshold": 0.7
        }
      }
    }]
  }'

Passaggi successivi