本页面介绍了如何使用 Google 搜索引擎(使用公开可用的 Web 数据)的结果作为 Gemini 回答的依据。此外,还说明了回答中包含的搜索建议。
依托 Google 搜索进行接地
如果您想将模型与世界知识、各种可能的主题或互联网上的最新信息相关联,请使用“依托 Google 搜索进行接地”功能。
如需详细了解 Gemini Enterprise Agent Platform 中的模型接地功能,请参阅接地概览。
支持的模型
本部分列出了支持“依托搜索进行接地”的模型。
点击即可展开支持的模型
- Gemini Robotics ER 2
- Gemini Nano Banana 2.1
- Gemini 4 Argon Cyber Permissive
- Gemini 4 Argon
- Gemini 3.8 Live
- Gemini 3.8 Flash
- Gemini 3.7 Flash
- Gemini 3.6 Flash
- Gemini 3.5 Flash-Lite
- Gemini 3.5 Flash
- Gemini 3.1 Pro
- Gemini 3.1 Flash-Lite
- Gemini 3.1 Flash 图片
- Gemini 3 Pro Image
- Gemini 3 Flash
- Gemini 2.5 Pro
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash(支持 Gemini Live API 原生音频功能)
- Gemini 2.5 Flash
支持的语言
如需查看受支持的语言列表,请参阅语言。
使用“依托 Google 搜索进行接地”功能
按照以下说明借助公开提供的网络数据让模型接地。
注意事项
如需使用“依托 Google 搜索进行接地”,您必须启用 Google 搜索建议。如需了解详情,请参阅使用 Google 搜索建议。
为了获得理想的结果,请使用
1.0温度。如需详细了解如何设置此配置,请参阅模型参考文档中的 Gemini API 请求正文。“依托 Google 搜索进行接地”功能每天最多可处理 100 万个接地提示。如果您需要更多接地提示,请联系 Google Cloud 支持团队寻求帮助。
工具组合:Gemini API 不支持在同一
generateContent请求中将搜索工具(例如googleSearch)与非搜索工具(例如函数调用或 Gemini Enterprise Agent Platform RAG Engineretrieval工具)结合使用。 仅当所有工具均为搜索工具时,方可支持多种工具。
您可以使用纬度和经度坐标,针对最终用户的特定地理位置自定义搜索结果。如需了解详情,请参阅 Grounding API。
控制台
如需将“依托 Google 搜索进行接地”与 Gemini Enterprise Agent Platform 上的 Agent Studio 搭配使用,请按照以下步骤操作:
- 在 Google Cloud 控制台中,前往 Agent Studio 页面。
- 在侧边栏中的模型设置下,前往接地部分,然后开启 Google 搜索切换开关。
- 在字段中输入提示,然后点击提交。
您的提示回答现在会使用“依托 Google 搜索进行接地”。
Python
安装
pip install --upgrade google-genai
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Go
了解如何安装或更新 Go。
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Java
了解如何安装或更新 Java。
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
Node.js
安装
npm install @google/genai
如需了解详情,请参阅 SDK 参考文档。
设置环境变量以将 Google Gen AI SDK 与 Vertex AI 搭配使用:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_ENTERPRISE=True
REST
在使用任何请求数据之前,请先进行以下替换:
- LOCATION:处理请求的区域。 如需使用全球端点,请清除端点名称中的相应位置,并将资源位置配置为全球。
- PROJECT_ID:您的项目 ID。 。
- MODEL_ID:多模态模型的模型 ID。
- TEXT:要包含在提示中的文本说明。
- EXCLUDE_DOMAINS:可选:不用于接地的网域列表。
- LATITUDE:可选:最终用户所在位置的纬度。例如,纬度
37.7749表示旧金山。您可以使用 Google 地图或其他地理编码工具等服务获取经纬度坐标。 - LONGITUDE:可选:最终用户所在位置的经度。例如,经度
-122.4194表示旧金山。
HTTP 方法和网址:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
请求 JSON 正文:
{
"contents": [{
"role": "user",
"parts": [{
"text": "TEXT"
}]
}],
"tools": [{
"googleSearch": {
"exclude_domains": [ "domain.com", "domain2.com" ]
}
}],
"toolConfig": {
"retrievalConfig": {
"latLng": {
"latitude": LATITUDE,
"longitude": LONGITUDE
}
}
},
"model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}
如需发送您的请求,请展开以下选项之一:
您应该收到类似以下内容的 JSON 响应:
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "The weather in Chicago this weekend, will be partly cloudy. The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday. There is a slight chance of rain on both days.\n"
}
]
},
"finishReason": "STOP",
"groundingMetadata": {
"webSearchQueries": [
"weather in Chicago this weekend"
],
"searchEntryPoint": {
"renderedContent": "..."
},
"groundingChunks": [
{
"web": {
"uri": "https://www.google.com/search?q=weather+in+Chicago,+IL",
"title": "Weather information for locality: Chicago, administrative_area: IL",
"domain": "google.com"
}
},
{
"web": {
"uri": "...",
"title": "weatherbug.com",
"domain": "weatherbug.com"
}
}
],
"groundingSupports": [
{
"segment": {
"startIndex": 85,
"endIndex": 214,
"text": "The temperature will be between 49°F (9°C) and 55°F (13°C) on Saturday and between 51°F (11°C) and 56°F (13°C) on Sunday."
},
"groundingChunkIndices": [
0
],
"confidenceScores": [
0.8662828
]
},
{
"segment": {
"startIndex": 215,
"endIndex": 261,
"text": "There is a slight chance of rain on both days."
},
"groundingChunkIndices": [
1,
0
],
"confidenceScores": [
0.62836814,
0.6488607
]
}
],
"retrievalMetadata": {}
}
}
],
"usageMetadata": {
"promptTokenCount": 10,
"candidatesTokenCount": 98,
"totalTokenCount": 108,
"trafficType": "ON_DEMAND",
"promptTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 10
}
],
"candidatesTokensDetails": [
{
"modality": "TEXT",
"tokenCount": 98
}
]
},
"modelVersion": "gemini-2.0-flash",
"createTime": "2025-05-19T14:42:55.000643Z",
"responseId": "b0MraIMFoqnf-Q-D66G4BQ"
}
依托 Google 图片搜索进行接地
借助“使用 Google 图片搜索建立依据”功能,模型可以在生成图片时,将从 Google 图片搜索中检索到的网页图片用作视觉上下文。Google 图片搜索是现有“依托 Google 搜索进行接地”工具中的一种新搜索类型,与标准 Google 网页搜索并存。Gemini Nano Banana 2.1 和 Gemini 3.1 Flash Image 的“使用 Google 图片搜索进行接地”功能目前处于预览版阶段。
API 请求配置
如需启用 Google 图片搜索,请在 API 请求中配置 googleSearch 工具,并在 searchTypes 对象中指定 imageSearch。您可以单独使用 Google 图片搜索,也可以将其与 Google 网页搜索结合使用。
REST
在使用任何请求数据之前,请先进行以下替换:
- LOCATION:处理请求的区域。如需使用 全球端点,请清除端点名称中的相应位置,并将资源位置配置为全球。
- PROJECT_ID:。
- MODEL_ID:多模态模型的模型 ID。
- SEARCH_TERM:图片的搜索字词。
HTTP 方法和网址:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
请求 JSON 正文:
{
"contents": [
{
"role": "user",
"parts": [
{
"text": "SEARCH_TERM"
}
]
}
],
"tools": [
{
"googleSearch": {
"searchTypes": {
"imageSearch": {},
"webSearch": {}
}
}
}
],
"model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}
如需发送请求,请选择以下方式之一:
curl
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"
PowerShell
将请求正文保存在名为 request.json 的文件中,然后执行以下命令:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content
您应该会收到一个成功的状态代码 (2xx) 和一个空响应。
显示要求
将 Google 图片搜索与“依托 Google 搜索进行接地”搭配使用时,您必须遵守以下条件:
来源注明:您必须提供指向包含来源图片的网页(“包含网页”,而非图片文件本身)的链接,且该链接必须能让用户识别为链接。
直接导航:如果您还选择显示来源图片,则必须提供从来源图片到其所在来源网页的直接单点击路径。任何其他延迟或阻碍最终用户访问来源网页的实现方式(包括但不限于任何多点击路径或使用中间图片查看器)均不被允许。
响应
对于使用图片搜索的有依据的回答,该 API 会提供清晰的归因和元数据,以便将其输出与经过验证的来源相关联。groundingMetadata 对象包含以下字段:
imageSearchQueries:模型用于视觉上下文(也称为“图片搜索”)的特定查询。groundingChunks:包含检索到的结果的来源信息。对于图片来源,这些内容会作为使用image分块类型的重定向网址返回。每个分块都包含image对象内的以下字段:sourceUri:用于归因的网页网址(也称为“着陆页”)。imageUri:直接图片网址。title:来源网页的标题。domain:来源网页的网域。
groundingSupports:提供特定映射,将生成的内容与其在分块中的相关引用来源关联起来。searchEntryPoint:包含 Google 搜索条状标签,其中包含用于呈现 Google 搜索建议的合规 HTML 和 CSS。
以下示例展示了响应中的 groundingMetadata 结构:
{
"groundingMetadata": {
"groundingChunks": [
{
"image": {
"sourceUri": "EXAMPLE_SOURCE_URI",
"imageUri": "EXAMPLE_IMAGE_URI",
"title": "Example source title",
"domain": "example.com"
}
}
],
"imageSearchQueries": [
"example search query"
]
}
}
理解回答
如果您的模型提示从 Agent Studio 或 API 成功使用“依托 Google 搜索进行接地”,则回答会包含带有来源链接(网址)的元数据。但是,有多种原因可能会导致此元数据无法提供,并且提示回答不会落地。这些原因包括模型回答中的来源相关性低或信息不完整。
文内引用
内嵌引用使用 API 返回的结构化 grounding_metadata,将生成的文本的特定片段链接到可验证的来源。
此功能支持所有接地方法,包括 Google 搜索、Google 地图和智能体搜索,可提供在应用中显示准确、互动式引用所需的精确来源详细信息。
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="Where will the next FIFA World Cup be held?",
config=types.GenerateContentConfig(
tools=[types.Tool(google_search=types.GoogleSearch())],
),
)
display(Markdown(response.text))
print(response.candidates[0].grounding_metadata.grounding_chunks)
display(HTML(response.candidates[0].grounding_metadata.search_entry_point.rendered_content))
输出示例:
…
Citations:
Wikipedia. "2026 FIFA World Cup." Retrieved February 11, 2026. (https://en.wikipedia.org/wiki/2026_FIFA_World_Cup)
US Soccer Players. "2026 FIFA World Cup FAQ — Dates, Hosts, Tickets, Teams & More." (https://ussoccerplayers.com/2026-fifa-world-cup-faq)
Holafly. "2026 World Cup host cities and countries: Full list of stadiums." (https://travel.holafly.com/esims/2026-world-cup-host-cities/)
…
接地支持
必须显示接地支持,因为这有助于您验证发布方的回答,并为用户提供更多学习途径。
对来自网络来源的回答的接地支持应以内嵌和汇总形式显示。例如,请参阅下图,了解如何执行此操作。

使用备用搜索引擎选项
使用“依托 Google 搜索进行接地”时,客户应用可以:
- 提供备用搜索引擎选项,
- 将其他搜索引擎设为默认选项,
- 显示其自身或第三方的搜索建议或搜索结果,前提是:任何非 Google 结果都必须与 Google 的接地结果和搜索建议分开显示,并且显示方式不会让用户感到困惑或误以为这些结果来自 Google。
优势
将“依托 Google 搜索进行接地”作为工具使用时,可以执行以下需要规划、推理和思考的复杂提示和工作流:
- 您可以进行接地,以帮助确保回答基于最新、最准确的信息。
- 您可以从网络中检索制品,以便进行分析。
- 您可以查找相关图片、视频或其他媒体,以协助进行多模态推理或任务生成。
- 您可以执行编码、技术问题排查和其他专业任务。
- 您可以查找特定于某个区域的信息,或协助准确翻译内容。
- 您可以找到相关网站进行浏览。
使用 Google 搜索建议
使用“依托 Google 搜索进行接地”时,如果您在回答中收到搜索建议,则必须在生产环境和应用中显示搜索建议。
具体而言,您必须显示接地的回答的元数据中包含的搜索查询。回答包括:
"content":LLM 生成的回答。"webSearchQueries":用于搜索建议的查询。
例如,在以下代码段中,Gemini 会回答 Google 搜索连接提示,该提示询问一种热带植物。
"predictions": [
{
"content": "Monstera is a type of vine that thrives in bright indirect light…",
"groundingMetadata": {
"webSearchQueries": ["What's a monstera?"],
}
}
]
您可以使用 Google 搜索建议获取此输出并进行显示。
搜索建议的要求
搜索建议功能需要满足以下条件:
| 要求 | 说明 |
|---|---|
| 正确做法 |
|
| 错误做法 |
|
显示要求
以下是显示要求:
- 完全按照所提供的方式显示搜索建议,不对颜色、字体或外观进行任何修改。确保搜索建议按照以下模拟中指定的方式进行渲染,包括针对浅色和深色模式:

- 每当显示接地回答时,其相应的 Google 搜索建议都应保持可见。
- 在品牌塑造方面,您必须严格遵循 Google 的指南(第三方使用 Google 品牌特征时适用),详见欢迎访问我们的品牌资源中心。
- 当您使用“使用 Google 搜索建立依据”时,系统会显示搜索建议内容信息条。包含搜索建议内容信息条的字段必须与 LLM 提供的基于事实回答宽度相同。
点按时的行为
用户点按条状标签后,会直接前往条状标签中显示的搜索字词的对应 Google 搜索结果页 (SRP)。SRP 可以在应用内浏览器或单独的浏览器应用中打开。请务必不要以任何方式最小化、移除或遮挡 SRP 的显示内容。以下动画模拟展示了点按与 SRP 的交互。
点按时的行为

实现搜索建议的代码
当您使用 API 为搜索回答建立依据时,模型回答会在 renderedContent 字段中提供合规的 HTML 和 CSS 样式,您可以实现该字段以在应用中显示搜索建议。
此外,搜索建议之前称为搜索入口点。虽然您可能会在某些 API 字段中看到对“搜索入口点”的引用,但这两个术语都是指您在 API 响应中收到的当前“搜索建议”。
以下示例展示了如何使用 curl 将回答与搜索结果进行接地:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3.5-flash:generateContent -d '{
"contents": {
"role": "user",
"parts": {
"text": "Why is the sky blue?"
}
},
"tools": [
{
"googleSearch": {}
}
]
}'
Gemini 3 的结算变化
在 Gemini 3 模型上使用“依托 Google 搜索进行接地”时,系统会针对 Gemini 生成并发送到 Google 搜索的每个搜索查询进行结算。一个提示可能会导致一个或多个搜索查询。
示例
此示例展示了可能需要付费的用户提示和搜索查询。
- 用户提示:请介绍一下阿尔伯特·爱因斯坦的一生。
- Gemini 可能会生成以下搜索查询:
- 阿尔伯特·爱因斯坦的出生和早期教育
- 阿尔伯特·爱因斯坦的相对论
- 阿尔伯特·爱因斯坦在美国的生活
在此示例中,这三个搜索查询会产生费用。
后续步骤
- 如需详细了解接地,请参阅接地概览。
- 了解如何发送聊天提示请求。
- 了解负责任的 AI 最佳实践和 Gemini Enterprise Agent Platform 安全过滤条件。