Google 地图基础微件

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

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

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

内容相关 widget 的运作方式

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

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

以下示例展示了从 Vertex AI API 返回的上下文 token 的外观。

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

渲染 Google 地图上下文 widget

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

使用 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);

禁止地区

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