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 sua data limite di conoscenza.
La base di riferimento ti aiuta a creare applicazioni che possono:
- Aumenta l'accuratezza fattuale: riduci le allucinazioni del modello basando le risposte su informazioni del mondo reale.
- Accedere a informazioni in tempo reale: rispondi a domande su eventi e argomenti recenti.
Fornisci citazioni:crea fiducia negli utenti mostrando le fonti delle affermazioni del modello.
Python
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-2.5-flash",
contents="Who won the euro 2024?",
config=config,
)
print(response.text)
JavaScript
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({});
const groundingTool = {
googleSearch: {},
};
const config = {
tools: [groundingTool],
};
const response = await ai.models.generateContent({
model: "gemini-2.5-flash",
contents: "Who won the euro 2024?",
config,
});
console.log(response.text);
REST
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash: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 Search tool.
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.

- Prompt utente:la tua applicazione invia il prompt di un utente all'API Gemini
con lo strumento
google_searchabilitato. - Analisi del prompt:il modello analizza il prompt e determina se una ricerca Google può migliorare la risposta.
- Ricerca Google:se necessario, il modello genera automaticamente una o più query di ricerca e le esegue.
- Elaborazione dei risultati di ricerca: il modello elabora i risultati di ricerca, sintetizza le informazioni e formula una risposta.
- Risposta fondata:l'API restituisce una risposta finale e di facile utilizzo
basata sui risultati di ricerca. Questa risposta include il testo della risposta del modello e
groundingMetadatacon 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 avanzata 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 l'HTML e il CSS per il rendering dei suggerimenti di ricerca richiesti. I requisiti di utilizzo completi sono descritti in dettaglio nei Termini di servizio.groundingChunks: array di oggetti contenenti le origini web (urietitle).groundingSupports: array di segmenti per collegare la risposta del modellotextalle fonti ingroundingChunks. Ogni blocco collega un testosegment(definito dastartIndexeendIndex) 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.
Attribuire le fonti con le citazioni in linea
L'API restituisce dati di citazione strutturati, offrendoti il controllo completo su come
visualizzare le fonti nell'interfaccia utente. Puoi utilizzare i campi groundingSupports e groundingChunks per collegare le affermazioni del modello direttamente alle relative fonti. Di seguito è riportato un pattern comune per l'elaborazione dei metadati per creare una
risposta con citazioni in linea e 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 per ogni 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), questo viene conteggiato come un singolo utilizzo fatturabile dello strumento per quella richiesta.
Per informazioni più 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 loro funzionalità nella pagina Panoramica modelli.
| Modello | Grounding con la Ricerca Google |
|---|---|
| Gemini 2.5 Pro | ✔️ |
| Gemini 2.5 Flash | ✔️ |
| Gemini 2.5 Flash-Lite | ✔️ |
| Gemini 2.0 Flash | ✔️ |
| Gemini 1.5 Pro | ✔️ |
| Gemini 1.5 Flash | ✔️ |
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.
Grounding 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 legacy 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 che hai 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()
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({});
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" \
-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_retrieval": {
"dynamic_retrieval_config": {
"mode": "MODE_DYNAMIC",
"dynamic_threshold": 0.7
}
}
}]
}'
Passaggi successivi
- Prova la sezione Grounding con la Ricerca Google nel cookbook dell'API Gemini.
- Scopri altri strumenti disponibili, come la chiamata di funzione.
- Scopri come arricchire i prompt con URL specifici utilizzando lo strumento Contesto URL.