本页面介绍了 Grounding with Google 地图 with Gemini Enterprise Agent Platform 如何通过提供地理空间上下文信息来帮助增强生成式 AI 应用。
概览
Grounding with Google Maps with Gemini Enterprise Agent Platform 是一项服务，可将 Gemini 模型与 Google 地图中的地理空间数据相关联。Google 地图可以访问数百万个位置的信息，包括商家、地标和地图注点。借助这些数据，您可以访问超过 2.5 亿个地点的信息，这些信息可用于让模型回答接地，使 AI 应用和智能体能够提供本地数据和地理空间上下文信息。
您还可以同时启用基于 Google 地图进行接地、基于 Google 搜索进行接地以及基于数据源进行接地。
依托 Google 地图进行接地的用途
您可以将“依托 Google 地图进行接地”用于各种应用，例如：
- 能够回答有关附近地点的问题的对话型助理，例如“哪里可以喝到最近的意式浓缩咖啡？”
- 个性化说明和社区信息资料，例如“您能详细介绍一下步行可达范围内的适合家庭的餐厅吗？”
- 特定位置（例如电动车辆充电站或酒店）周边区域的摘要。
这对于房地产、旅游、出行和社交媒体应用等使用情形非常有用。
支持的模型
本部分列出了支持“依托 Google 地图进行接地”的模型。
点击即可展开支持的型号
如需详细了解 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](/resource-manager/docs/creating-managing-projects#identifiers)。。
- 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 地图进行接地”可以回答的问题类型。
地点属性示例
此列表按字母顺序提供了有关地点的属性样本，您的模型可以使用这些属性来生成回答。
- 地址
- 路边自提
- 借记卡
- 距离
- 免费停车场
- 现场音乐表演
- 儿童菜单
- 营业时间
- 付款方式（例如现金或信用卡）
- 地点回答
- 允许带宠物
- 供应啤酒
- 供应素食
- 有无障碍设施
- Wifi
地点回答是“依托 Google 地图进行接地”根据从用户评价中提取的信息生成的回答。
使用地点属性的示例
以下示例在有关不同类型地点的提问中使用了地点属性。借助“依托 Google 地图进行接地”，可使用这些属性来了解您的意图，然后根据与 Google 地图中地点关联的数据提供相关回答。
计划家庭晚餐：您可能会问，“The Italian Place”适合带孩子去吗？它们提供外卖吗？它们的评分是多少？
这些问题的回答有助于您确定餐厅是否适合家庭用餐，以及餐厅是否提供便捷的服务。
为好友查询无障碍设施：您可以问：“我需要一家有轮椅无障碍入口的餐厅。”
对该提示的回答可能有助于您确定相应地点是否满足特定的无障碍需求。
寻找可以吃夜宵的地方：您可以问：“Burger Joint”现在营业吗？他们提供晚餐吗？他们周五的营业时间是几点？
这些问题的回答有助于您找到在特定时间段内提供特定餐点的营业场所。
与客户相约喝咖啡：您可以问：“Cafe Central”有 Wi-Fi 吗？他们供应咖啡吗？这些餐厅的价位如何？是否接受信用卡？
这些问题的回答有助于您根据咖啡馆的设施、产品和服务以及付款方式来评估其是否适合举办商务会议。
Google 地图接地结果中的信息可能与实际路况有所不同。
理解回答
Google 地图来源在 groundingChunks 中的 groundingMetadata 内返回。系统会针对地点和用户评价返回来源，这些内容已用于帮助生成 Google 地图接地结果。
此代码示例展示了回答中的地点来源和地点回答来源：
"groundingChunks": [
{
"maps": {
"uri": "{Link to Maps Content}",
"title": "{Name of Maps Place}",
"placeId": "{Place ID}",
"placeAnswerSources": {
"reviewSnippets" : [
{
"reviewId": "{Review ID}",
"googleMapsUri": "{Link to Maps Content}",
"title": "{Title of review}"
}
]
}
},
}
],
路线规划 - 查找路线
Grounding with Google 地图支持“查找路线”功能。借助此功能，AI 代理可以了解身体运动、实时行程估算以及位置之间的空间关系。借助“查找路线”功能，您的模型可以提供经过性能优化的路线和准确的出行时间，并考虑实时路况。此集成功能可让 Grounding with Google 地图根据行程时间过滤地点，提供精确的点到点路线，并计算特定交通方式的预计通勤时间。
功能
查找路线功能可计算出出发地和目的地之间的精确行程距离和时长。
“查找路线”功能支持以下操作：
交通方式：驾车、步行、骑车、乘坐公交和驾驶双轮机动车的路线规划（并非所有交通方式都适用于所有国家/地区）
多个途经点：出发地和目的地之间最多可添加 13 个中间经停点
实时路况：考虑当前路况信息，提供准确的“实时”行程时间，而不是静态平均值
以下是“查找路线”支持的问题类型示例：
基于行程时间的邻近度：“纽约市第六大道 1335 号的希尔顿酒店附近有哪些美国餐厅，步行 10 分钟即可到达？”
通勤时间估算：“从西雅图的派克市场到国会山乘坐公共交通需要多长时间？”
了解响应
当提示触发“查找路线”功能时，模型会生成由结构化元数据支持的自然语言回答。这样一来，您就可以向用户显示准确的出行信息。
载荷响应中会返回以下数据：
时长：在考虑交通状况（如果已请求）的情况下，在各个位置之间移动所需的时间。例如，“500 秒”。
距离：路线的实际距离。例如，“1.9 公里”。
多段线：一种经过编码的文本字符串，可用于在地图上直观呈现特定路线。
以下是针对提示“How do I get to Carmine's restaurant from the Hilton Hotel (1335 6th Ave in NYC) where I'm staying?”的回答示例。
如需从纽约市第 6 大道 1335 号的希尔顿酒店前往 Carmine's 餐厅，您需要前往位于美国纽约市西 44 街 200 号的 Carmine's - Time Square 分店，邮编为 10036。
以下是步行路线：
从希尔顿酒店出发：从 1335 6th Ave 的希尔顿酒店出口离开。
沿第六大道向南走：沿第六大道（美洲大道）向南行驶，前往西 44 街。
右转进入西 44 街：右转进入西 44 街。
Carmine's 位于您的左侧：沿 W 44th Street 向下走，Carmine's 位于您的左侧，地址为 200 W 44th St。
此路线大约 0.5 英里，应该需要 10-15 分钟。
以下是针对提示“从西雅图的派克市场乘坐公共交通工具前往国会山需要多长时间？”的回答示例。
如需在西雅图从派克市场前往国会山，您可以选择以下几种公共交通方式：
有轨电车（轻轨）：从派克市场附近的 Westlake 站到国会山站大约需要 3 分钟。包括换乘在内，总行程时间约为 9 分钟，电车每 10 分钟发车一次。
公交：从派克街和第四大道（派克市场附近）乘坐金县地铁直达 Capitol Hill 大约需要 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 星的面包店？”
- 多段路线搜索：“我要从旧金山自驾前往圣路易斯奥比斯波，然后再前往洛杉矶，请推荐三处位于旧金山和圣路易斯奥比斯波之间以及圣路易斯奥比斯波和洛杉矶之间的电动汽车充电站？”
了解响应
当提示触发“沿途搜索”工具时，模型会生成自然语言答案，该答案由结构化元数据提供支持，其中包含地点数据和路线数据。这样可确保建议的地点实际上位于实际的旅行路线上。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 沿途的一些加油站：
- 示例加油站 - 位于 123 Example Rd, Sunnyvale, CA 94045。 该加油站获得的评分为 3.5 星（基于 122 条评价），销售氢气、丙烷和汽油，并提供洗车服务。该餐厅今晚营业至晚上 9:50，并设有洗手间。
- 虚构的加油站 - 位于 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 大道 123 号，评分为 4.5。
- 虚构的电动汽车充电站：您可以在加利福尼亚州吉尔罗伊市虚构路 456 号找到此充电站，其评分为 4.4。
- 通用充电站：此充电站位于加利福尼亚州萨利纳斯市通用街 789 号，邮编为 95008，评分为 3.5。
圣路易斯奥比斯波和洛杉矶之间：
- 充电站示例：此充电站位于加利福尼亚州圣路易斯奥比斯波市 Example Rd 123 号，评分为 4.3。
- 虚构的电动车辆充电站：此充电站位于 456 Fictional Ave, Santa Barbara, CA 93123，评分为 3.9。
- Generic Charging Station：您可以在加利福尼亚州格伦代尔市 Generic 街 789 号找到此充电站，其评分为 3.0。
祝您旅途愉快！
服务使用要求
本部分介绍了 Grounding with Google 地图的服务使用要求。
告知用户 Google 地图来源的使用情况
对于每个 Google 地图接地结果，您都会收到groundingChunks中支持相应回答的来源。系统还会返回以下元数据：
- 源 URI
- 标题
- ID
在展示通过 Grounding with Google Maps 与 Gemini Enterprise Agent Platform 结合使用而获得的结果时，您必须指明关联的 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 和 grounding_chunks.maps.placeAnswerSources.reviewSnippets 中的每个来源，必须按照以下要求生成链接预览：
- 请按照 Google 地图文字提供方指南，将每项来源归属至 Google 地图。
- 显示回答中提供的来源标题。
- 使用回答中的
uri或googleMapsUri链接到来源。
这些图片展示了显示来源和 Google 地图链接的最低要求。
您可以收起“来源”视图。
可选：使用其他内容（例如以下内容）增强链接预览：
- 在 Google 地图文字提供方之前插入 Google 地图网站图标。
- 来源网址 (
og:image) 中的照片。
如需详细了解部分 Google 地图数据提供商及其许可条款，请参阅 Google 地图和 Google 地球法律声明。
Google 地图文字提供方信息指南
在文本中将来源归属至 Google 地图时，请遵循以下准则：
- 请勿以任何方式修改 Google 地图文字：
- 请勿更改 Google 地图的大小写。
- 请勿将 Google 地图换行显示。
- 请勿将 Google 地图本地化为其他语言。
- 使用 HTML 属性
translate="no"阻止浏览器翻译 Google 地图。
- 按照下表中的说明设置 Google 地图文本的样式：
| 属性 | 样式 |
|---|---|
| 字体系列 | Roboto加载字体是可选的。 |
| 后备字体系列 | 产品中已使用的任何无衬线正文字体，或“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 地图查询的潜在数量 | 查询生成示例 |
|---|---|---|
| 希尔顿酒店（纽约市第 6 大道 1335 号）附近的寿司餐厅。 | 3 个地点搜索查询（Google 地图查询），假设此提示生成 3 个扇出查询。 | 3 个扇出地点搜索查询： - 曼哈顿中城希尔顿酒店附近的最佳寿司店 - 纽约第 6 大道 1335 号附近的寿司店 - 纽约第 6 大道 1335 号附近的日式餐厅 |
| 如何从 1335 6th Ave. 的 Hilton Hotel 前往 200 W 44th St, New York | 1 条“查询路线”查询（Google 地图查询） | 1 次“查询路线”查询： - 从纽约市第六大道 1335 号希尔顿酒店到纽约市西 44 街 200 号的路线 |
| 从纽约市希尔顿酒店（第六大道 1335 号）到机场的距离。 | 4 次 Google 地图查询（1 次地点搜索查询 + 3 次查找路线查询），假设地点搜索返回 3 个机场。 | 1 个扇出地点搜索查询： - 纽约市附近的机场 3 个查找路线查询： - 从美国纽约市第 6 大道 1335 号到约翰·F·肯尼迪国际机场的路线肯尼迪国际机场，纽约市皇后区，邮编：11430，美国 - 从美国纽约市第六大道 1335 号到美国新泽西州纽瓦克市纽瓦克自由国际机场的路线 - 从美国纽约市第六大道 1335 号到拉瓜迪亚 |
| 查找从 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。