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);
  5. 可选:更改地图模式。有效值包括:
    • 2D 路线图地图:google.maps.places.PlaceContextualListMapMode.ROADMAP
    • 3D 混合地图:google.maps.places.PlaceContextualListMapMode.HYBRID
    • 无地图:google.maps.places.PlaceContextualListMapMode.NONE
  6. 以下示例展示了如何将地图模式更改为 2D 地图:

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

禁止投放广告的地区

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