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

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

概览

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

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

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

  • 基于聊天的智能体。
  • 地点信息总结。
  • 内容翻译。
  • 能够回答有关附近地点的问题的对话型助理，例如“附近有公园吗？”。
  • 有关地点的个性化说明，例如“您能详细介绍一下步行可达范围内的公园和适合家庭的餐厅吗？”

这对于房地产、旅游、出行和社交应用等行业非常有用。

如需获得“依托 Google 地图进行接地”方面的技术支持，请发送电子邮件至 maps-grounding-feedback-external@google.com。

支持的模型

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

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

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

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

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

控制台

如需将“依托 Google 地图进行接地”与 Vertex AI Studio 搭配使用，请按照以下步骤操作：

  1. 在 Google Cloud 控制台中，前往 Vertex AI Studio 页面。

    进入 Vertex AI Studio

  2. 点击 Freeform 标签页。
  3. 在侧边栏中，点击让模型回答接地切换开关。
  4. 点击自定义，并将 Google 地图设置为来源。
  5. 在文本框中输入提示，然后点击提交。

您的提示回答会接地到 Google 地图。

REST

在使用任何请求数据之前，请先进行以下替换：

  • LOCATION：处理请求的区域。
  • PROJECT_ID：您的项目 ID。
  • MODEL_ID：多模态模型的模型 ID。
  • TEXT：要包含在提示中的文本说明。
  • LATITUDE：位置所处的纬度。例如，纬度 37.7749 表示旧金山。您可以使用 Google 地图等服务或其他地理编码工具获取纬度和经度坐标。
  • LONGITUDE：位置所处的经度。例如，经度 -122.4194 表示旧金山。

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": "TEXT"
    }]
  }],
  "tools": [{
    "googleMaps": {}
  }],
  "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 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",
              "text": "**About:**\n\n* **Type:** Italian Restaurant\n* **Address:** 621 Wythe St, Alexandria, VA 22314, USA\n* **Open Now:** Yes\n* **Rating:** 4.2 (411 reviews)\n* **Price Level:** Moderate\n* **Phone:** (571) 777-8981\n* **Summary:** Down-to-earth, counter-serve stop offering Italian sandwiches, coffee & market goods.\n* **Additional Summary:** Relaxed Italian eatery known for sandwiches and pizza along with gourmet food items and gelato.\n* **Offers Takeout:** Yes\n* **Offers Delivery:** Yes\n* **Offers Dine-in:** Yes\n* **Good for Children:** Yes\n* **Has Restroom:** Yes\n* **Outdoor Seating:** Yes\n* **Live Music:** No\n* **Menu for Children:** No\n* **Serves Dessert:** Yes\n* **Serves Coffee:** Yes\n* **Good for Watching Sports:** No\n* **Serves Lunch:** Yes\n* **Serves Dinner:** Yes\n* **Serves Beer:** Yes\n* **Serves Vegetarian Food:** Yes\n\n**Opening Hours (local time):**\n\n* Monday: 11:00 AM – 7:00 PM\n* Tuesday: 10:00 AM – 7:00 PM\n* Wednesday: 11:00 AM – 7:00 PM\n* Thursday: 11:00 AM – 7:00 PM\n* Friday: 11:00 AM – 7:00 PM\n* Saturday: 11:00 AM – 7:00 PM\n* Sunday: 12:00 – 7:00 PM\n\n**Parking options:**\n\n* **Free parking lot:** Yes\n* **Free street parking:** Yes\n* **Valet parking:** No\n\n**Accessibility:**\n\n* **Wheelchair accessible parking:** Yes\n* **Wheelchair accessible restroom:** Yes\n\n**Payment options:**\n\n* **Credit Card:** Yes\n* **Debit Card:** Yes\n* **Cash Only:** No\n* **NFC:** Yes\n\n**Distance & Travel Time:**\n\n* 384.6 kilometers\n* 4.2 hours",
              "placeId": "places/ChIJOTRDf_qwt4kR2kV_WYUf63w"
            }
          },
          ...
        ],
        "groundingSupports": [
          {
            "segment": {
              "endIndex": 79,
              "text": "\"The Italian Place\" in Alexandria, VA, is good for children and offers takeout."
            },
            "groundingChunkIndices": [
              0
            ]
          },
          {
            "segment": {
              "startIndex": 80,
              "endIndex": 130,
              "text": "It has a rating of 4.2 stars based on 411 reviews."
            },
            "groundingChunkIndices": [
              0
            ]
          }
        ],
        "googleMapsWidgetContextToken": "widgetcontent/..."
      }
    }
  ],
  ...
}

可选：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：

HTML

  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>

JavaScript

  1. 创建上下文 widget。

    async function createWidget(contextToken) {
  await google.maps.importLibrary('places');
  let widgetContainer = document.querySelector('#wc');  // a div that contains the widget
  const placeContextualElement = new
      google.maps.places.PlaceContextualElement({ contextToken });
  widgetContainer.appendChild(placeContextualElement);
}

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

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

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

      function updateWidget(contextToken) {
    widget.contextToken = contextToken;
  }

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

    • 紧凑布局：layout: google.maps.places.PlaceContextualListLayout.COMPACT
    • 垂直布局：layout: google.maps.places.PlaceContextualListLayout.VERTICAL

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

      const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
    layout: google.maps.places.PlaceContextualListLayout.COMPACT
  });
  widget.appendChild(widgetConfig);

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

    • 二维路线图地图：mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP
    • 三维混合地图：mapMode: google.maps.places.PlaceContextualListMapMode.HYBRID
    • 没有地图：mapMode: google.maps.places.PlaceContextualListMapMode.NONE

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

      const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
    mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP
  });
  widget.appendChild(widgetConfig);

来源标明出处要求

在展示 Vertex AI 生成的直接引用了通过“依托 Google 地图进行接地”提供的信息的内容时，您必须指明用于支持回答的 Google 地图来源。

此图片显示了用于支持模型回答的 Google 地图来源。

显示来源的回答提示

告知最终用户接地来源的使用情况

您必须告知用户以下信息：

  • 用于支持 LLM 生成的内容的接地来源，这些来源与内容非常接近。
  • 接地来源必须在一次用户互动中可见。

显示 Google 地图来源网址

Google 地图来源在 groundingChunks 和 groundingSupports 中的 groundingMetadata 内返回。系统会针对地点和支持地点回答的内容（例如用户评价）返回 Google 地图来源，这些内容已用于帮助生成回答。

此代码示例展示了回答中的地点来源和地点回答来源：

  "groundingChunks": [
            {
              "maps": {
                "uri": "{Link to Maps Content}",
                "title": "{Name of Maps Place}",
                "text": "{Maps content that was sent to the model for this place}"
                "placeId": "{Place ID}",
                "placeAnswerSources":
                                  {
                    "review": "",
                    "authorAttribution": {
                      "displayName": "",
                      "photoUri": ""
                    },
                    "flagContentUri": "",
                    "googleMapsUri": ""
                  },
              },
               "flagContentUri": ""
              }
            }
          }
        ],

对于 LLM 引用的每个来源，必须按照以下要求生成链接预览：

  • 请按照文字提供方指南，将每项来源归属至 Google 地图。
  • 显示 Open Graph 网页标题 (og:title) 或采用以下格式的标题：

    [Place Name] - Google Maps

  • 使用来源网址前往来源材料。

如果 groundingChunks 中有地点问题解答来源，您必须执行以下操作：

  • 在 grounding_chunks.maps.placeAnswerSources.reviewSnippets.googleMapsUri 内呈现评价链接。
  • 显示 Open Graph 标题或格式为
    的标题

    Google Review of [Place Name] by [Author Name]。

    Place Name 可在 grounding_chunks.maps.title 中找到，Author Name 可在 grounding_chunks.maps.placeAnswerSources.reviewSnippets.authorAttribution.displayName 中找到。

  • 可选：使用其他内容（例如以下内容）增强链接预览：

    • 在 Google 地图文字提供方之前插入 Google 地图网站图标 (<link rel="icon" href="https://www.google.com/favicon.ico">)。
    • 说明 (og:description)
    • 照片 (og:image)

这些图片展示了最低要求，即显示地点链接。

显示来源的回答提示

您可以收起“来源”视图。

已折叠包含回答和来源的提示

此图片显示了地点的照片，这是一个可选链接，用于预览来源的属性。

包含回答和来源的提示

禁止地区

Google 地图会限制某些内容和活动，以维护安全可靠的平台。如需查看禁止地区的列表，请参阅 Google Maps Platform 禁止地区。

地点属性

本部分列出了用于描述地点并由“依托 Google 地图进行接地”用于生成回答的地点属性。这些属性用于确定“依托 Google 地图进行接地”可以回答的问题类型。

地点属性示例

此列表按字母顺序提供了有关地点的属性样本，您的模型可以使用这些属性来生成回答。

  • 地址
  • 路边自提
  • 借记卡
  • 距离
  • 免费停车场
  • 现场音乐表演
  • 儿童菜单
  • 营业时间
  • 付款方式（例如现金或信用卡）
  • 地点回答
  • 允许带宠物
  • 供应啤酒
  • 供应素食
  • 有无障碍设施
  • Wifi

地点回答是“依托 Google 地图进行接地”根据从用户评价中提取的信息生成的回答。如果元数据中提供的地点回答内容存在问题，您可以使用 API 响应中 PlaceAnswerSources 对象内 flagContentUri 字段中的链接向 Google 举报。

使用地点属性的示例

以下示例在有关不同类型地点的提问中使用了地点属性。借助“依托 Google 地图进行接地”，可使用这些属性来了解您的意图，然后根据与 Google 地图中地点关联的数据提供相关回答。

  • 计划家庭晚餐：您可能会问，“The Italian Place”适合带孩子去吗？它们提供外卖吗？它们的评分是多少？

    这些问题的回答有助于您确定餐厅是否适合家庭用餐，以及餐厅是否提供便捷的服务。

  • 为好友查询无障碍设施：您可以问：“我需要一家有轮椅无障碍入口的餐厅。”

    对该提示的回答可能有助于您确定相应地点是否满足特定的无障碍需求。

  • 寻找可以吃夜宵的地方：您可以问：“Burger Joint”现在营业吗？他们提供晚餐吗？他们周五的营业时间是几点？

    这些问题的回答有助于您找到在特定时间段内提供特定餐点的营业场所。

  • 与客户相约喝咖啡：您可以问：“Cafe Central”有 Wi-Fi 吗？他们供应咖啡吗？这些餐厅的价位如何？是否接受信用卡？

    这些问题的回答有助于您根据咖啡馆的设施、产品和服务以及付款方式来评估其是否适合举办商务会议。

后续步骤

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