本页面介绍了“Gemini Enterprise Agent Platform 依托 Google 地图进行接地”如何通过提供地理空间上下文信息来帮助增强生成式 AI 应用。
概览
Grounding with Google Maps 是 Gemini Enterprise Agent Platform 中的一项服务,可将 Gemini 模型与 Google 地图中的地理空间数据相关联。Google 地图可以访问数百万个位置的信息,包括商家、地标和地图注点。借助这些数据,您可以访问超过 2.5 亿个地点的信息,这些信息可用于让模型回答接地,使 AI 应用和智能体能够提供本地数据和地理空间上下文信息。
您还可以同时启用基于 Google 地图进行接地、基于 Google 搜索进行接地以及基于数据源进行接地。
依托 Google 地图进行接地的用途
您可以将“依托 Google 地图进行接地”用于各种应用,例如:
- 能够回答有关附近地点的问题的对话型助理,例如“最近的意式浓缩咖啡馆在哪里?”
- 个性化说明和社区数据洞见,例如“您能详细介绍一下步行可达范围内的全家皆宜餐厅吗?”
- 特定地点(例如电动车辆充电站或酒店)周边区域的摘要。
这对于房地产、旅游、出行和社交媒体应用等应用场景非常有用。
支持的模型
本部分列出了支持“依托 Google 地图进行接地”的模型。
点击即可展开支持的模型
- 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
如需详细了解 Gemini 模型,请参阅 Gemini 模型。
使用"依托 Google 地图进行接地"让模型回答接地
此代码示例演示了如何使用“依托 Google 地图进行接地”让模型回答接地。
您可以使用经纬度坐标,针对特定地理位置自定义搜索结果。
控制台
如需将 Grounding with Google 地图与 Gemini Enterprise Agent Platform 搭配使用,请按照以下步骤操作:
在 Google Cloud 控制台中,前往 Agent Studio 页面。
在侧边栏中的模型设置下,前往接地部分,然后点击 Google 搜索、Google 地图对应的修改图标。系统会显示一个配置窗格。
开启 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
from google import genai
from google.genai.types import (
GenerateContentConfig,
GoogleMaps,
HttpOptions,
Tool,
)
client = genai.Client(http_options=HttpOptions(api_version="v1"))
response = client.models.generate_content(
model="gemini-2.5-flash",
contents="Where can I get the best espresso near me?",
config=GenerateContentConfig(
tools=[
# Use Google Maps Tool
Tool(google_maps=GoogleMaps())
],
tool_config=types.ToolConfig(
retrieval_config = types.RetrievalConfig(
lat_lng = types.LatLng( # Pass geo coordinates for location-aware grounding
latitude=40.7128,
longitude=-74.006
),
language_code = "en_US", # Optional: localize Maps results
),
),
),
)
print(response.text)
# Example response:
# 'Here are some of the top-rated places to get espresso near you: ...'
REST
在使用任何请求数据之前,请先进行以下替换:
- LOCATION:处理请求的区域。 如需使用全球端点,请清除端点名称中的相应位置,并将资源位置配置为全球。
- PROJECT_ID:您的项目 ID。 。
- MODEL_ID:多模态模型的模型 ID。
- PROMPT:要发送给模型的提示。
- LATITUDE:位置所处的纬度。 例如,纬度
37.7749表示旧金山。您可以使用 Google 地图或其他地理编码工具等服务获取经纬度坐标。 - LONGITUDE:位置所处的经度。 例如,经度
-122.4194表示旧金山。 - GROUNDING_TYPES:要启用的 Google 地图接地类型。目前支持
places和routing。places:搜索地点信息,包括场所、著名地图注点和地理位置。routing:查找路线并沿路线搜索。
places。
HTTP 方法和网址:
POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent
请求 JSON 正文:
{
"contents": [{
"role": "user",
"parts": [{
"text": "PROMPT"
}]
}],
"tools": [{
"googleMaps": {
"groundingTypes": {
"places": {},
"routing": {}
}
}
}],
"toolConfig": {
"retrievalConfig": {
"latLng": {
"latitude": LATITUDE,
"longitude": LONGITUDE
},
"languageCode": "en_US"
}
},
"model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}
如需发送您的请求,请展开以下选项之一:
您应该收到类似以下内容的 JSON 响应:
{
"candidates": [
{
"content": {
"role": "model",
"parts": [
{
"text": "\"The Italian Place\" in Alexandria, VA, is good for children and offers takeout. It has a rating of 4.2 stars based on 411 reviews."
}
]
},
"finishReason": "STOP",
"groundingMetadata": {
"groundingChunks": [
{
"maps": {
"uri": "https://maps.google.com/?cid=9001322937822692826",
"title": "The Italian Place",
"placeId": "places/ChIJOTRDf_qwt4kR2kV_WYUf63w"
}
},
{
"maps": {
"uri": "https://maps.google.com/?cid=9001322937822692826",
"title": "Hank's Pasta Bar",
"placeId": "places/MMVtPzn9FGcevML89",
"placeAnswerSources": {
"reviewSnippets": [
{
"id": "places/ChIJOTRDf_qwt4kR2kV_WYUf63w",
"title": "Google Maps Review",
"uri": "https://maps.google.com/?cid=9001322937822692826"
},
]
}
}
},
...
],
"groundingSupports": [
{
"segment": {
"endIndex": 79,
"text": "\"The Italian Place\" in Alexandria, VA, is good for children and offers takeout."
},
"groundingChunkIndices": [
0
]
},
],
}
}
],
...
}
地点属性
本部分列出了用于描述地点并由“依托 Google 地图进行接地”用于生成回答的地点属性。这些属性用于确定“依托 Google 地图进行接地”可以回答的问题类型。
地点属性示例
此列表按字母顺序提供了有关地点的属性样本,您的模型可以使用这些属性来生成回答:
- 地址
- 繁忙程度趋势
- 路边自提
- 借记卡
- 距离
- 电动车辆充电站信息(连接器类型、充电速度和可用性)
- 免费停车场
- 油价和可用的燃料类型
- 适合儿童
- 现场音乐表演
- Menu highlights
- 营业时间
- 付款方式(例如现金或信用卡)
- 允许带宠物
- 查看数据分析
- 供应啤酒
- 供应素食
- 有无障碍设施
- Wifi
使用地点属性的示例
以下示例在有关不同类型地点的提问中使用了地点属性。借助“依托 Google 地图进行接地”,可使用这些属性来了解您的意图,然后根据与 Google 地图中地点关联的数据提供相关回答。
计划家庭晚餐:您可能会问,“The Italian Place”适合带孩子去吗?它们提供外卖吗?它们的评分是多少?
这些问题的回答有助于您确定餐厅是否适合家庭用餐,以及餐厅是否提供便捷的服务。
探索菜单亮点和招牌菜:您可能会问,“The Italian Place”菜单上最推荐的意面是哪款?他们有素食主菜吗?评价者对他们的番茄酱有什么看法?
这些问题的回答会使用菜单亮点和评价数据分析,帮助您探索特定的美食和社区最爱。
为好友查询无障碍设施:您可以问:“我需要一家有轮椅无障碍入口的餐厅。”
对该提示的回答可能有助于您确定相应地点是否满足特定的无障碍需求。
寻找可以吃夜宵的地方:您可以问:“Burger Joint”现在营业吗?他们提供晚餐吗?他们周五的营业时间是几点?
这些问题的回答有助于您找到在特定时间段内提供特定餐点的营业场所。
为自驾游规划电动汽车充电和酒店设施:您可以这样问:我住在“Overnight Motel”。他们是否提供现场电动车辆充电站?支持哪些连接器类型?周五晚上他们的停车区有多忙?
这些问题的回答结合了电动车辆充电站信息和繁忙程度趋势,可帮助您规划车辆充电并评估您停留期间的拥挤程度。
比较附近的油价和特种燃料价格:您可以询问:加利福尼亚州山景城附近有哪些加油站出售柴油或氢气?它们当前的价格对比情况如何?
这些问题的回答利用汽油价格和可用燃料类型,帮助您找到特种燃料和经济实惠的加油站。
根据评价总结工作氛围:您可以问:“Breakfast Cafe”的客户评价摘要中关于噪音水平、座椅舒适度和 Wi-Fi 可靠性是如何说的?适合远程工作吗?
此提示的回答利用评价数据分析,根据社区共识评估咖啡馆是否适合工作或学习。
Google 地图接地结果中的信息可能与实际路况或场地情况有所不同。
理解回答
Google 地图来源在 groundingChunks 中的 groundingMetadata 内返回。系统会针对地点返回来源,这些内容已用于帮助生成 Google 地图接地结果。uri 字段可能会链接到支持性评价,或直接链接到 Google 地图上的地点信息表。
此代码示例展示了回答中的地点来源:
"groundingChunks": [
{
"maps": {
"uri": "{Link to place sheet or review on Maps}",
"title": "{Name of Maps Place}",
"placeId": "{Place ID}"
}
}
],
路线规划 - 查找路线
Grounding with Google 地图支持“查找路线”功能。借助此功能,您的 AI 智能体可以了解物理移动、实时行程估算以及地点之间的空间关系。借助“查找路线”功能,您的模型可以提供性能经过优化的路线和准确的行程时间,并考虑实时路况。通过此集成,Grounding with Google 地图可以根据行程时间过滤地点、提供精确的点对点路线,并计算特定交通方式的预计通勤时间。
功能
“查找路线”功能可计算出发地和目的地之间的精确行程距离和时长。
“查找路线”支持以下功能:
交通方式:驾车、步行、骑车、公交和双轮机动车路线规划(并非所有国家/地区都支持所有出行方式)
多个航点:出发地和目的地之间最多可设置 13 个中间经停点
实时路况:考虑当前路况信息,提供准确的“实时”行程时间,而非静态平均值
以下是“查找路线”支持的问题类型示例:
基于行程时间的邻近性:“纽约市 1335 6th Ave 的希尔顿酒店步行 10 分钟范围内有哪些美式餐厅?”
通勤估算:“从西雅图派克市场乘坐公共交通工具到国会山需要多长时间?”
启用“查找路线”
在 REST API 和 SDK 中,如果省略 grounding_types,Grounding with Google 地图默认仅使用地点数据。如需启用路线功能,您必须在请求配置中的 grounding_types 中明确配置 routing。如果您想同时使用地点和路线工具,则必须在 grounding_types 中同时指定 places 和 routing。
了解响应
当提示触发“查找路线”功能时,模型会生成由结构化元数据支持的自然语言回答。这样,您就可以向用户显示精确的行程信息。
载荷响应中会返回以下数据:
时长:在不同地点之间出行所需的时间,如果请求中包含交通信息,则会考虑交通状况。例如,“500 秒”。
距离:路线的实际距离。例如“1.9 公里”。
多段线:经过编码的文本字符串,可让您在地图上直观呈现特定路线。
以下是针对提示“如何从我入住的希尔顿酒店(纽约市第六大道 1335 号)前往 Carmine's 餐厅?”的示例回答
如要从纽约市 1335 6th Ave 的 Hilton Hotel 前往 Carmine's 餐厅,您需要前往 Carmine's - Time Square 分店,地址为 200 W 44th St, New York, NY 10036, USA。
以下是步行路线:
从希尔顿酒店出发:从希尔顿酒店(地址:1335 6th Ave)出来。
沿第 6 大道向南步行:沿第 6 大道(美洲大道)向南步行,前往西 44 街。
右转进入 W 44th Street:右转进入 W 44th Street。
Carmine's 在您的左侧:沿 W 44th Street 步行,Carmine's 位于 200 W 44th St,在您的左侧。
步行距离约为 0.5 英里,大约需要 10-15 分钟。
以下是针对提示“在西雅图,从派克市场乘坐公共交通工具到国会山需要多长时间?”的回答示例
若要从西雅图的派克市场前往国会山,您可以选择以下几种公共交通方式:
有轨电车(轻轨):从派克市场附近的西湖区乘坐有轨电车前往国会山大约需要 3 分钟。包括换乘在内,总行程时间约为 9 分钟,有轨电车每 10 分钟一班。
公交:从 Pike St & 4th Ave(派克市场附近)乘坐 King County Metro 直达公交前往国会山大约需要 11 分钟,每 20 分钟一班。或者,您也可以乘坐 49 路公交车,大约需要 16 分钟。
路线规划 - 沿路线搜索
借助沿路线搜索功能,您的 AI 智能体可以发现与用户规划的行程在地理位置上相关且方便的地图注点。通过将回答与 Google 地图的路线规划和空间搜索引擎相结合,您的模型可以提供尽可能减少绕路的建议,并了解公路旅行或通勤的物流流程。
功能
借助“沿路线搜索”功能,您的应用可以识别位于起点和终点之间生成的路径上的特定商家、设施或景点。仅支持“驾车”出行方式。
以下示例说明了沿路线搜索工具可以处理的问题类型。
- 基本路线搜索:“查找从 1800 Amphibious Blvd. Mountain View, CA 94045 到 456 Sunny St, Sunnyvale CA 沿途的加油站。”(通常,出发地和目的地地址是从聊天记录中推导出来的。)
- 基于地点属性进行搜索:“在旧金山和 1800 Amphibious Blvd. Mountain View, CA 94045 之间,是否有任何评分至少为 4 星的面包店?”
- 多路段路线搜索:“我打算从旧金山自驾前往圣路易斯奥比斯波,再前往洛杉矶,请推荐旧金山到圣路易斯奥比斯波之间以及圣路易斯奥比斯波到洛杉矶之间的三个电动汽车充电桩选项。”
启用沿路线搜索
沿路线搜索功能需要同时具备地点和路线功能,才能发现沿途的地点。在 REST API 和 SDK 中,您必须在请求配置中的 grounding_types 中明确配置 places 和 routing。
了解响应
当提示触发沿路线搜索工具时,模型会生成一个自然语言回答,该回答由结合了地点和路线数据的结构化元数据提供支持。这样可以确保建议的地点确实方便实际出行路线。groundingMetadata 将包含返回的地点的 groundingChunks 以及沿途搜索的路线。
提示示例 [基本路线搜索]:
查找从 1800 Amphibious Blvd. Mountain View, CA 94045 到 456 Sunny St, Sunnyvale CA 沿途的加油站。
示例响应 [基本路线搜索]:
以下是从 1800 Amphibious Blvd. Mountain View, CA 94045 到 456 Sunny St, Sunnyvale, CA 沿途的一些加油站:
- Example Gas station - 位于 123 Example Rd, Sunnyvale, CA 94045。 该加油站获得的评分为 3.5 星(基于 122 条评价),销售氢气、丙烷和汽油,并提供洗车服务。今晚营业至 9:50,并设有洗手间。
- Fictional Gas station - 位于 456 Fictional Ave, Sunnyvale, CA 94045。该加油站获得的评分为 3.6 星(基于 52 条评价),设有便利店和洗车服务。该加油站 24 小时营业,并设有洗手间。
- Generic Gas station - 位于 789 W Generic St, Sunnyvale, CA 94045。该营业地点获得的评分为 3.6 星(基于 35 条评价)。该车站 24 小时开放,并设有洗手间。
提示示例 [多段路线搜索]:
我打算从旧金山自驾前往圣路易斯奥比斯波,再前往洛杉矶。请推荐旧金山到圣路易斯奥比斯波之间以及圣路易斯奥比斯波到洛杉矶之间的三个充电桩选项。
示例响应 [多路段路线搜索]:
以下是您从旧金山到洛杉矶的自驾游路线中,在圣路易斯奥比斯波停留时可选择的一些电动汽车充电桩。
旧金山和圣路易斯奥比斯波之间:
- Example Charger:位于 123 Example Blvd, Campbell, CA 95008,评分为 4.5。
- Fictional EV Station:该充电站位于 456 Fictional Rd, Gilroy, CA 95008,评分为 4.4。
- Generic Charging Station:此充电站位于 789 Generic St, Salinas, CA 95008,评分为 3.5。
圣路易斯奥比斯波和洛杉矶之间:
- Example Charger:位于 123 Example Rd, San Luis Obispo, CA 93123,评分为 4.3。
- Fictional EV Station:该充电站位于 456 Fictional Ave, Santa Barbara, CA 93123,评分为 3.9。
- Generic Charging Station:该充电站位于 789 Generic St, Glendale, CA 93123,评分为 3.0。
祝您自驾游愉快!
服务使用要求
本部分介绍了 Grounding with Google 地图的服务使用要求。
告知用户 Google 地图来源的使用情况
对于每个 Google 地图接地结果,您都会收到groundingChunks中支持相应回答的来源。系统还会返回以下元数据:
- 源 URI
- 标题
- ID
在展示通过 Gemini Enterprise Agent Platform 使用 Grounding with Google Maps 获得的结果时,您必须指明相关的 Google 地图来源,并告知用户以下信息:
- Google 地图来源必须紧跟在这些来源支持的生成内容之后。此类生成的内容也称为 Google 地图接地结果。
- Google 地图来源必须在一次用户互动中可见。
对于语音优先界面
来源:Google 地图来源必须显示在配套界面中,该界面会显示任何 AI 语音对话的逐字历史记录。此记录必须遵守来源要求,并受适用的数据缓存和存储限制的约束。
主动披露来源:必须让最终用户合理了解 Google 地图在其体验中扮演的角色,以及如何在互动时找到详细来源。
主动披露来源时,必须传达以下要点:
AI 生成的内容可能包含来自 Google 地图的信息。
配套界面中提供了详细来源。
您必须使用以下至少一种方法来主动披露来源。
视觉显示:对于在带屏幕的设备上进行的语音互动,只要使用 Grounding with Google 地图,就必须在屏幕上显示主动披露声明。
语音通知:向用户朗读主动披露声明。此操作必须在 Grounding with Google 地图支持的首次互动期间进行,并且至少每 6 个月重复一次。
披露声明示例:“AI 生成的内容可能包含来自 Google 地图的信息。你可以在配套应用中找到详细来源。”
持续披露:必须让最终用户能够持续访问一项说明,即 Google 地图内容可能会用于 AI 生成的内容(例如,在语音设置菜单或语音互动披露声明中)。
用户询问:您的语音助理必须准确回答最终用户关于内容来源的询问,包括 AI 生成的内容包含来自 Google 地图的信息时。如果 Google 地图是来源,请将最终用户引导至配套界面,以便访问特定来源信息。
显示 Google 地图来源和 Google 地图链接
对于 groundingChunks 中的每个来源,必须按照以下要求生成链接预览:
- 请按照 Google 地图文字提供方指南,将每项来源归属至 Google 地图。
- 显示回答中提供的来源标题。
- 使用回答中的
uri链接到来源。
这些图片展示了显示来源和 Google 地图链接的最低要求。
您可以收起“来源”视图。
可选:使用其他内容(例如以下内容)增强链接预览:
- 在 Google 地图文字提供方之前插入 Google 地图网站图标。
- 来自来源网址 (
og:image) 的照片。
如需详细了解我们的部分 Google 地图数据提供商及其许可条款,请参阅 Google 地图和 Google 地球法律声明。
Google 地图文本提供方信息指南
在文字中将来源归属至 Google 地图时,请遵循以下准则:
- 请勿以任何方式修改文本 Google 地图:
- 请勿更改 Google Maps 的大小写。
- 请勿将 Google 地图换行。
- 请勿将 Google 地图 本地化为其他语言。
- 使用 HTML 属性
translate="no"阻止浏览器翻译 Google 地图。
- 按照下表中的说明设置 Google 地图文本的样式:
| 属性 | 样式 |
|---|---|
| 字体系列 | Roboto加载字体是可选操作。 |
| 后备字体系列 | 产品中已使用的任何 Sans Serif 正文字体,或用于调用默认系统字体的“Sans-Serif” |
| 字体样式 | 正常 |
| 字体粗细 | 400 |
| 字体颜色 | 白色、黑色 (#1F1F1F) 或灰色 (#5E5E5E)。与背景保持无障碍对比度 (4.5:1)。 |
| 字体大小 | 最小字号:12sp 最大字号:16sp 如需了解 sp,请参阅 Material Design 网站上的“字号单位”。 |
| 字母间距 | 正常 |
示例 CSS
以下 CSS 代码段以适当的排版样式和颜色在白色或浅色背景上呈现 Google 地图。
@import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');
.GMP-attribution {
font-family: Roboto, Sans-Serif;
font-style: normal;
font-weight: 400;
font-size: 1rem;
letter-spacing: normal;
white-space: nowrap;
color: #5e5e5e;
}
地点 ID 和评价 ID
Google 地图数据包括地点 ID 和评价 ID。您可能会缓存、存储和导出以下回答数据:
placeIdreviewId
《Grounding with Google Maps 条款》中关于缓存的限制不适用。
禁止地区
Grounding with Google 地图对某些内容和活动有限制,以维护安全可靠的平台。客户不得在禁止区域分发或营销提供 Grounding with Google 地图的客户应用。如需了解详情,请参阅 Google Maps Platform 禁止地区。禁止销售的地区列表可能会不时更新。
结算
Grounding with Google Maps 会针对每个 Google 地图查询收费(请参阅价格)。
客户向 Gemini 提交的请求可能会触发一次或多次 Google 地图查询。下表列举了一些示例:
| 提示示例 | 潜在 Google 地图查询数 | 查询生成示例 |
|---|---|---|
| 纽约市希尔顿酒店(1335 6th Ave)附近的寿司餐厅。 | 3 次地点搜索查询(Google 地图查询),假设此提示会生成 3 次扇出查询。 | 3 个扇出地点搜索查询: - 曼哈顿中城希尔顿酒店附近最好的寿司店 - 纽约第六大道 1335 号附近的寿司店 - 纽约第六大道 1335 号附近的日式餐厅 |
| 如何从希尔顿酒店(1335 6th Ave)前往 200 W 44th St, New York | 1 个查询路线查询(Google 地图查询) | 1 个查询路线的查询: - 从 Hilton Hotel, 1335 6th Ave, New York, NY 到 200 W 44th St, New York, NY 10036 的路线 |
| 从希尔顿酒店(纽约市第六大道 1335 号)到机场的距离。 | 4 次 Google 地图查询(1 次地点搜索查询 + 3 次路线查询),假设地点搜索返回 3 个机场。 | 1 个扇出地点搜索查询: - 纽约市附近的机场 3 个查找路线查询: - 从 1335 6th Ave, New York, NY 10019, USA 到 John F. Kennedy International Airport, Queens, NY 11430, USA - Directions from 1335 6th Ave, New York, NY 10019, USA to Newark Liberty International Airport, Newark, NJ 07114, USA - Directions from 1335 6th Ave, New York, NY 10019, USA to LaGuardia |
| 查找从 1800 Amphibious Blvd. Mountain View, CA 94045 到 456 Sunny St, Sunnyvale CA 沿途的加油站。 | 1 次沿路线搜索查询(Google 地图查询) | 1 个沿路线搜索查询: - 从 1800 Amphibious Blvd. Mountain View, CA 94045 到 456 Sunny St, Sunnyvale CA 的加油站 |
后续步骤
- 如需详细了解如何将 Gemini 模型接地到您的数据,请参阅利用数据进行接地。
- 如需详细了解 Responsible AI 最佳实践和 Gemini Enterprise Agent Platform 的安全性过滤机制,请参阅 Responsible AI。