在 Vertex AI 中使用 Google 地图进行接地

本页面介绍了“Vertex AI 依托 Google 地图进行接地”如何通过提供地理空间上下文信息来帮助增强生成式 AI 应用。

概览

“Vertex AI 依托 Google 地图进行接地”是一项服务，可将 Gemini 模型与 Google 地图中的地理空间数据相关联。Google 地图可以访问数百万个位置的信息，包括商家、地标和地图注点。借助这些数据，您可以访问超过 2.5 亿个地点的信息，这些信息可用于让模型回答接地，使 AI 应用和智能体能够提供本地数据和地理空间上下文信息。

您还可以同时启用基于 Google 地图进行接地、基于 Google 搜索进行接地以及基于数据源进行接地。

依托 Google 地图进行接地的用途

您可以将“依托 Google 地图进行接地”用于各种应用，例如：

• 能够回答有关附近地点的问题的对话型助理，例如“哪里可以喝到最近的意大利浓缩咖啡？”。
• 个性化说明和社区信息资料，例如“您能详细介绍一下步行可达范围内的适合家庭的餐厅吗？”
• 特定位置（例如电动车辆充电站或酒店）周边区域的摘要。

这对于房地产、旅游、出行和社交媒体应用等使用情形非常有用。

支持的模型

本部分列出了支持“依托 Google 地图进行接地”的模型。

• Gemini 2.5 Flash （预览版）
• Gemini 2.5 Flash-Lite （预览版）
• Gemini 2.5 Flash-Lite
• Gemini 2.5 Flash（支持 Live API 原生音频功能） （预览版）
• 支持 Live API 的 Gemini 2.0 Flash （预览版）
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

如需详细了解 Gemini 模型，请参阅 Gemini 模型。

使用"依托 Google 地图进行接地"让模型回答接地

此代码示例演示了如何使用“依托 Google 地图进行接地”让模型回答接地。

您可以使用纬度和经度坐标，针对特定地理位置自定义搜索结果。如需了解详情，请参阅 Grounding API。

pip install --upgrade google-genai

# 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_VERTEXAI=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 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: ...'

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

{
  "contents": [{
    "role": "user",
    "parts": [{
      "text": "PROMPT"
    }]
  }],
  "tools": [{
    "googleMaps": {
      "enableWidget": "ENABLE_WIDGET"
    }
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      },
      "languageCode": "en_US"
    }
  },
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

$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/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

{
  "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
            ]
          },
        ],
        "googleMapsWidgetContextToken": "widgetcontent/..."
      }
    }
  ],
  ...
}

地点属性

本部分列出了用于描述地点并由“依托 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}"
          }
        ]
      }
    },
  }
],

服务使用要求

本部分介绍了“依托 Google 地图进行接地”的服务使用要求。

告知用户 Google 地图来源的使用情况

对于每条依托 Google 地图的回答，您都会收到groundingChunks中支持相应回答的来源。系统还会返回以下元数据：

• 来源 URI
• title
• ID

在展示“依托 Google 地图进行接地”与 Vertex AI 搭配使用时的结果时，您必须指明关联的 Google 地图来源，并告知用户以下信息：

• Google 地图来源必须紧跟在来源支持的生成内容之后。此类生成的内容也称为 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 地图文本的样式：

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。您可能会缓存、存储和导出以下响应数据：

• googleMapsWidgetContextToken
• placeId
• reviewId

依托 Google 地图进行接地的条款中有关禁止缓存的限制不适用。

禁止地区

Google 地图中的“根据 Google 地图提供的信息进行定位”功能会限制某些内容和活动，以维护安全可靠的平台。客户不得在禁止地区分发或营销提供 Google 地图基础功能的客户应用。目前的禁止地区包括：

• 中国
• 克里米亚
• 古巴
• 顿涅茨克人民共和国
• 伊朗
• 卢甘斯克人民共和国
• 朝鲜
• 叙利亚
• 越南

此列表可能会不时更新。

可选：Google 地图上下文 widget

上下文 widget 是一种 Google 地图非正式版产品，是一种用于支持或补充其他 Google 地图内容的视觉容器。借助 Google 地图上下文 widget，您可以将“依托 Google 地图进行接地”集成到应用中，从而打造由对话式 LLM 提供支持的聊天体验。上下文 widget 使用上下文 token googleMapsWidgetContextToken 进行渲染，该 token 在 Vertex AI API 响应中返回，可用于渲染视觉内容。

上下文 widget 可根据您的使用场景提供不同的功能：

• 它会在使用 Google 地图提示生成回答的场景中显示用户评价和照片（即用户生成的内容 [UGC]）。

• 当 Vertex AI 仅生成文本回答时，它有助于通过地图可视化和数据来丰富结果。

如需详细了解上下文相关 widget，请参阅地图接地 widget。

渲染 Google 地图上下文 widget

如需渲染和使用 Google 地图上下文 widget，请在显示该 widget 的页面上使用 Alpha 版 Google Maps JavaScript API。如需了解详情，请参阅加载 Maps JavaScript API。

以下代码示例演示了如何使用上下文 widget：

1. 创建上下文 widget。

     <body>
      <gmp-place-contextual id="widget"></gmp-place-contextual>
     </body>
   

2. 在任何依托 Google 地图进行接地的回答中，都有一个相应的 googleMapsWidgetContextToken，用于呈现上下文 widget，并放在生成的回答附近。

   如需更新上下文 token，请设置 widget.contextToken property。

   "googleMapsWidgetContextToken": "widgetcontent/AcBXPQdpWQWbap9H-OH8sEKmOXxmEKAYvff0tvthhneMQC3VrqWCjpnPBl4-Id98FGiA_S_t8aeAeJj0T6JkWFX56Bil8oBSR0W8JH3C_RSYLbTjxKdpxc9yNn6JcZTtolIRZon9xi6WpNGuSyjcIxWu2S0hwpasNOpUlWrG1RxVCB4WD1fsz_pwR236mG36lMxevXTQ_JnfdYNuQwQ4Lc3vn...<snip>...
   Ts5VJE_b3IC5eE_6wez0nh61r7foTUZpP7BXMwxR-7Wyfcj6x1v6mIWsFGr1o0p_HSAMNqWPg-aFVnkPLhAkOR6MaNZOfezTva-gxHlu7z_haFvYxcUE1qfNVQ",
   

   function updateWidget(contextToken) {
     let widget = document.querySelector('#widget');
     widget.contextToken = contextToken;
   }
   

3. 可选：指定列表布局。有效值包括：

   • 紧凑布局：<gmp-place-contextual-list-config layout="compact">
   • 垂直布局：<gmp-place-contextual-list-config layout="vertical">

   此代码示例演示了如何将列表布局更改为紧凑布局。

      <gmp-place-contextual id="widget">
        <gmp-place-contextual-list-config layout="compact">
        </gmp-place-contextual-list-config>
      </gmp-place-contextual>
   

4. 可选：更改地图模式。有效值包括：

   • 二维路线图地图：map-mode="roadmap"
   • 三维混合地图：map-mode="hybrid"
   • 没有地图：map-mode="none"

   此代码示例演示了如何将地图模式更改为二维地图。

      <gmp-place-contextual id="widget">
        <gmp-place-contextual-list-config map-mode="roadmap">
        </gmp-place-contextual-list-config>
      </gmp-place-contextual>
   

后续步骤

• 如需详细了解如何将 Gemini 模型接地到您的数据，请参阅利用数据进行接地。
• 如需详细了解 Responsible AI 最佳实践和 Vertex AI 的安全性过滤机制，请参阅 Responsible AI。