依托 Google 搜索进行接地可将 Gemini 模型与实时网络内容相关联,并支持所有可用语言。这样一来,Gemini 就可以提供更准确的答案,并引用知识截止日期之后的可验证来源。
接地可帮助您构建能够执行以下操作的应用:
- 提高事实准确性:通过以真实世界的信息为依据来减少模型幻觉。
- 获取实时信息:回答有关近期活动和主题的问题。
提供引用:通过显示模型声明的来源来建立用户信任。
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" \
-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": {}
}
]
}'
如需了解详情,请尝试使用搜索工具笔记本。
依托 Google 搜索进行接地的运作方式
启用 google_search
工具后,模型会自动处理搜索、处理和引用信息的整个工作流程。
- 用户提示:您的应用在启用
google_search
工具的情况下,将用户提示发送到 Gemini API。 - 提示分析:模型会分析提示,并确定 Google 搜索是否可以改进回答。
- Google 搜索:如果需要,模型会自动生成一个或多个搜索查询并执行这些查询。
- 搜索结果处理:模型处理搜索结果、综合信息并生成回答。
- 以搜索结果为依据的回答:API 会返回以搜索结果为依据的最终且用户友好的回答。此回答包含模型的文字答案和
groundingMetadata
,其中包含搜索查询、网页搜索结果和引用。
了解接地响应
如果成功进行了事实依据核查,响应中会包含 groundingMetadata
字段。此结构化数据对于验证声明和在应用中打造丰富的引用体验至关重要。
{
"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]
}
]
}
}
]
}
Gemini API 会通过 groundingMetadata
返回以下信息:
webSearchQueries
:所用搜索查询的数组。这有助于调试和了解模型的推理过程。searchEntryPoint
:包含用于呈现所需搜索建议的 HTML 和 CSS。如需了解完整的使用要求,请参阅服务条款。groundingChunks
:包含 Web 来源(uri
和title
)的对象数组。groundingSupports
:用于将模型回答text
与groundingChunks
中的来源相关联的块数组。每个块都将文本segment
(由startIndex
和endIndex
定义)与一个或多个groundingChunkIndices
相关联。这是创建内嵌引用的关键。
您还可以将 Google 搜索作为回答依据与 网址 上下文工具结合使用,以便基于公开 Web 数据和您提供的特定网址来生成回答。
使用内嵌引用注明来源
该 API 会返回结构化引用数据,让您可以完全控制如何在界面中显示来源。您可以使用 groundingSupports
和 groundingChunks
字段将模型的陈述直接关联到其来源。以下是一种常见模式,用于处理元数据以创建包含内嵌可点击引用的回答。
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);
包含内嵌引用的新回答将如下所示:
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:/...)
价格
使用“使用 Google 搜索建立依据”时,系统会根据包含 google_search
工具的 API 请求向您的项目收取费用。如果模型决定执行多个搜索查询来回答单个提示(例如,在同一 API 调用中搜索 "UEFA Euro 2024 winner"
和 "Spain vs England Euro 2024 final score"
),则该请求计为一次工具使用。
如需详细了解价格信息,请参阅 Gemini API 价格页面。
支持的模型
不包括实验性模型和预览版模型。您可以在模型概览页面上查看这些模型的功能。
型号 | 使用 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 | ✔️ |
使用 Gemini 1.5 模型进行接地(旧版)
虽然建议 Gemini 2.0 及更高版本使用 google_search
工具,但 Gemini 1.5 支持名为 google_search_retrieval
的旧版工具。该工具提供了一种 dynamic
模式,可让模型根据其对提示需要最新信息的置信度来决定是否执行搜索。如果模型的置信度高于您设置的 dynamic_threshold
(介于 0.0 和 1.0 之间的值),它就会执行搜索。
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
}
}
}]
}'
后续步骤
- 不妨试试 Gemini API 实战宝典中的“依托 Google 搜索进行接地”。
- 了解其他可用工具,例如函数调用。
- 了解如何使用 网址 上下文工具通过特定网址扩充提示。