Google 地图基础微件

上下文 widget 是一种 Google 地图 Pre-GA 产品，是一个用于支持或补充其他 Google 地图内容的视觉容器。借助 Google 地图情境微件，您可以将 Google 地图接地集成到应用中，打造由 LLM 赋能的对话式聊天体验。上下文 widget 使用上下文令牌 googleMapsWidgetContextToken 进行渲染，该令牌在 Vertex AI API 响应中返回，可用于渲染视觉内容。

情境化 widget 可根据您的使用场景提供不同的功能：

  • 在 Google 地图提示用于生成答案的场景中，它会显示主观的用户生成内容 (UGC)。
  • 当 Vertex AI 仅生成文本回答时，此插件有助于通过地图可视化效果和数据来丰富结果。

内容相关 widget 的运作方式

上下文 widget 会以 googleMapsWidgetContextToken 的形式显示 Vertex AI 依托 Google 地图进行接地的回答。使用此令牌可呈现上下文相关微件并显示响应。 了解详情。事件流如下所示：

  1. 使用依托 Google 地图接地的查询调用 Vertex AI API。
  2. Vertex AI 会返回 googleMapsWidgetContextToken。
  3. 使用令牌呈现上下文相关微件。
  4. 上下文 widget 会显示 Vertex AI 的回答。

以下示例展示了从 Vertex AI API 返回的上下文令牌的格式。

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

渲染 Google 地图上下文 widget

如需呈现和使用 Google 地图上下文 widget，请在显示该 widget 的网页上使用 Maps JavaScript API 的 Alpha 版。如需了解详情，请参阅加载 Maps JavaScript API。 您还必须使用已启用以加载 Google Maps JavaScript API 的 API 密钥。 验证 places 库是否已加载。

以下部分介绍了如何呈现 Google 地图情境化 widget。使用自定义 HTML 或 JavaScript 创建情境 widget。

使用自定义 HTML 元素

以下部分介绍了如何使用自定义 HTML 元素呈现 Google 地图情境 widget。通过将 gmp-place-contextual 元素添加到网页中来创建情境化 widget。

  1. 将 gmp-place-contextual 元素添加到网页中：

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

  2. 在任何以 Google 地图为依据的回答中，都有一个相应的 googleMapsWidgetContextToken，可用于呈现情境化 widget。 以下函数展示了如何更新上下文令牌： 

    let widget = document.querySelector('#widget'); // a div that contains the 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. 可选：更改地图模式。有效值包括：
    • 2D 路线图地图：<gmp-place-contextual-map-config map-mode="roadmap">
    • 3D 混合地图：<gmp-place-contextual-map-config map-mode="hybrid">
    • 无地图：<gmp-place-contextual-map-config map-mode="none">
    5. 以下示例展示了如何将地图模式更改为 2D 地图： 
    <gmp-place-contextual id="widget">
  <gmp-place-contextual-map-config map-mode="roadmap">
  </gmp-place-contextual-map-config>
</gmp-place-contextual>

使用 JavaScript

以下部分介绍了如何通过以编程方式创建 PlaceContextualElement 并将其附加到 DOM 来呈现 Google 地图情境化 widget。

  1. 创建情境化 widget。

    let widget = document.querySelector('#widget');  // a div that contains the widget

async function createWidget(contextToken) {
  await google.maps.importLibrary('places');
  const placeContextualElement = new
      google.maps.places.PlaceContextualElement({ contextToken }); // contextToken can be empty at initialization.
  widget.appendChild(placeContextualElement);
}
  2. 在任何以 Google 地图为依据的回答中，都有一个相应的 googleMapsWidgetContextToken，用于呈现情境化 widget。以下函数展示了如何更新上下文令牌： 
    widget.contextToken = contextToken;
  3. 可选：指定列表布局。有效值包括：
    • 紧凑布局：google.maps.places.PlaceContextualListLayout.COMPACT
    • 纵向布局：google.maps.places.PlaceContextualListLayout.VERTICAL

    4. 以下示例展示了如何将列表布局更改为紧凑型：

    const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
  layout: google.maps.places.PlaceContextualListLayout.COMPACT
});
widget.appendChild(widgetConfig);
  4. 可选：更改地图模式。有效值包括：
    • 2D 路线图地图：google.maps.places.PlaceContextualListMapMode.ROADMAP
    • 3D 混合地图：google.maps.places.PlaceContextualListMapMode.HYBRID
    • 无地图：google.maps.places.PlaceContextualListMapMode.NONE

    5. 以下示例展示了如何将地图模式更改为 2D 地图：

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

禁止投放广告的地区

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