Grounding z użyciem wyszukiwarki Google łączy model Gemini z treściami internetowymi aktualizowanymi w czasie rzeczywistym i działa we wszystkich dostępnych językach. Dzięki temu Gemini może udzielać dokładniejszych odpowiedzi i cytować wiarygodne źródła wykraczające poza datę odcięcia wiedzy.
Uziemienie pomaga tworzyć aplikacje, które mogą:
- Zwiększanie dokładności: zmniejsz halucynacje modelu, opierając odpowiedzi na informacjach ze świata rzeczywistego.
- Dostęp do informacji w czasie rzeczywistym: odpowiadaj na pytania dotyczące ostatnich wydarzeń i tematów.
Podawaj cytaty: buduj zaufanie użytkowników, podając źródła twierdzeń modelu.
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": {}
}
]
}'
Więcej informacji znajdziesz w notatniku narzędzia wyszukiwania.
Jak działa powiązanie ze źródłem informacji przy użyciu wyszukiwarki Google
Gdy włączysz to google_search narzędzie, model automatycznie obsłuży cały proces wyszukiwania, przetwarzania i cytowania informacji.

- Prompt użytkownika: Twoja aplikacja wysyła prompt użytkownika do interfejsu Gemini API z włączonym narzędziem
google_search. - Analiza promptu: model analizuje prompt i określa, czy wyszukiwarka Google może poprawić odpowiedź.
- Wyszukiwarka Google: w razie potrzeby model automatycznie generuje i wykonuje jedno lub kilka zapytań.
- Przetwarzanie wyników wyszukiwania: model przetwarza wyniki wyszukiwania, syntetyzuje informacje i formułuje odpowiedź.
- Odpowiedź oparta na wynikach wyszukiwania: interfejs API zwraca ostateczną, przyjazną dla użytkownika odpowiedź, która jest oparta na wynikach wyszukiwania. Odpowiedź zawiera tekst wygenerowany przez model
oraz
groundingMetadataz wyszukiwanymi hasłami, wynikami wyszukiwania w internecie i cytatami.
Informacje o odpowiedzi dotyczącej podstaw
Gdy odpowiedź zostanie prawidłowo uzasadniona, będzie zawierać pole groundingMetadata. Te dane strukturalne są niezbędne do weryfikowania roszczeń i tworzenia w aplikacji rozbudowanych cytatów.
{
"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]
}
]
}
}
]
}
Interfejs Gemini API zwraca te informacje z symbolem groundingMetadata:
webSearchQueries: tablica użytych zapytań. Jest to przydatne do debugowania i zrozumienia procesu wnioskowania modelu.searchEntryPoint: Zawiera kod HTML i CSS do renderowania wymaganych sugestii wyszukiwania. Pełne wymagania dotyczące korzystania z usługi są opisane w Warunkach korzystania z usługi.groundingChunks: tablica obiektów zawierających źródła internetowe (uriititle).groundingSupports: tablica fragmentów do połączenia odpowiedzi modelutextze źródłami wgroundingChunks. Każdy fragment łączy tekstsegment(zdefiniowany przezstartIndexiendIndex) z co najmniej 1groundingChunkIndices. To klucz do tworzenia cytatów w tekście.
Uziemianie za pomocą wyszukiwarki Google można też stosować w połączeniu z narzędziem do kontekstu adresu URL, aby uziemiać odpowiedzi zarówno na podstawie publicznych danych internetowych, jak i określonych adresów URL.
Podawanie źródeł za pomocą cytatów w tekście
Interfejs API zwraca uporządkowane dane cytowania, dzięki czemu masz pełną kontrolę nad sposobem wyświetlania źródeł w interfejsie użytkownika. Możesz użyć pól groundingSupports i groundingChunks, aby połączyć wypowiedzi modelu bezpośrednio z ich źródłami. Oto typowy wzorzec przetwarzania metadanych w celu utworzenia odpowiedzi z klikalnymi cytatami w tekście.
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);
Nowa odpowiedź z cytatami w tekście będzie wyglądać tak:
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:/...)
Ceny
Gdy używasz funkcji Grounding przy użyciu wyszukiwarki Google w Gemini 3, za każde zapytanie wyszukiwania, które model zdecyduje się wykonać, Twój projekt jest obciążany opłatą. Jeśli model zdecyduje się wykonać kilka zapytań, aby odpowiedzieć na jeden prompt (np. wyszukać "UEFA Euro 2024 winner" i "Spain vs England Euro 2024 final
score" w ramach jednego wywołania interfejsu API), będzie to liczone jako 2 płatne użycia narzędzia w przypadku tego żądania. Dotyczy to tylko modeli Gemini 3. Jeśli używasz groundingu w wyszukiwarce z modelami Gemini 2.5 lub starszymi, za projekt naliczana jest opłata za prompt.
Szczegółowe informacje o cenach znajdziesz na stronie z cennikiem Gemini API.
Obsługiwane modele
Nie obejmuje to modeli eksperymentalnych i wersji podglądowych. Ich możliwości znajdziesz na stronie informacji o modelu.
| Model | Powiązanie ze źródłem informacji przy użyciu wyszukiwarki 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 | ✔️ |
Obsługiwane kombinacje narzędzi
Możesz używać funkcji Grounding with Google Search z innymi narzędziami, takimi jak wykonywanie kodu i kontekst adresu URL, aby obsługiwać bardziej złożone przypadki użycia.
Uziemianie za pomocą modeli Gemini 1.5 (starsza wersja)
Narzędzie google_search jest zalecane w przypadku Gemini 2.0 i nowszych, ale Gemini 1.5 obsługuje starsze narzędzie o nazwie google_search_retrieval. To narzędzie udostępnia dynamictryb, w którym model decyduje, czy przeprowadzić wyszukiwanie na podstawie pewności, że prompt wymaga aktualnych informacji. Jeśli pewność modelu jest większa niż ustawiona przez Ciebie wartość dynamic_threshold (w zakresie od 0,0 do 1,0), wyszuka on informacje.
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
}
}
}]
}'
Co dalej?
- Wypróbuj grounding z użyciem wyszukiwarki Google w zbiorze Cookbook interfejsu Gemini API.
- Dowiedz się więcej o innych dostępnych narzędziach, takich jak wywoływanie funkcji.
- Dowiedz się, jak wzbogacać prompty o konkretne adresy URL za pomocą narzędzia kontekstu adresu URL.