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 原生音訊 (預先發布版)
• Gemini 2.0 Flash with Live API (Preview)
• 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/..."
      }
    }
  ],
  ...
}

地點屬性

本節列出用於描述地點的地點屬性，以及 Grounding with Google Maps 用於生成回覆的屬性。這些屬性是用來判斷 Grounding with Google Maps 可回答的問題類型。

地點屬性範例

這份清單提供地點的屬性範例 (依字母順序排列)，模型可使用這些屬性生成回覆。

• 地址
• 店外取貨
• 簽帳金融卡
• 距離
• 免費停車場
• 提供現場音樂演奏
• 兒童菜單
• 營業時間
• 付款方式 (例如現金或信用卡)
• 地點回答
• 寵物友善
• 供應啤酒
• 供應素食料理
• 有無障礙設施
• Wifi

地點答案是 Grounding with Google Maps 根據使用者評論資訊生成的內容。

使用地點屬性的範例

以下範例在有關不同類型地點的問題中，使用地點屬性。以 Google 地圖為基礎時，系統會使用屬性瞭解你的意圖，然後根據 Google 地圖中與地點相關聯的資料，提供相關回覆。

• 規劃家庭聚餐：你可以詢問「The Italian Place」是否適合兒童，以及是否提供外帶服務。他們的評分是多少？

  這些問題的答案有助於判斷餐廳是否適合家庭用餐，以及餐廳是否提供便利的服務。

• 為朋友確認無障礙設施：你可能會詢問「我需要有無障礙入口的餐廳」。

  這項提示的回覆內容可能有助於判斷該地點是否符合特定無障礙需求。

• 尋找宵夜地點：你可以問「『Burger Joint』現在營業嗎？他們提供晚餐嗎？星期五的營業時間是什麼時候？

  回答這些問題有助於您在特定時間找到供應特定餐點的營業場所。

• 與客戶在咖啡廳會面：你可能會問「『中央咖啡廳』有 Wi-Fi 嗎？」他們是否供應咖啡？價位如何？是否接受信用卡？

  根據這些問題的答案，你可以評估咖啡廳的設施、供應項目和付款方式是否適合舉辦商務會議。

Google 地圖基礎結果中的資訊可能與實際路況不同。

瞭解回覆內容

Google 地圖來源會傳回 groundingMetadata 內的 groundingChunks。系統會傳回地點和使用者評論的來源， 這些來源有助於生成 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

使用 Vertex AI 呈現「利用 Google 地圖建立基準」的結果時，您必須指定相關聯的 Google 地圖來源，並告知使用者下列事項：

• Google 地圖來源必須緊接在來源支援的生成內容後方。這類生成內容也稱為「Google 地圖基礎結果」。
• Google 地圖來源必須在一次使用者互動中顯示。

顯示 Google 地圖來源和連結

在 groundingChunks 和 grounding_chunks.maps.placeAnswerSources.reviewSnippets 中，每個來源都必須按照下列規定產生連結預覽畫面：

• 請按照 Google 地圖文字出處標註規範，將每個來源標註為 Google 地圖。
• 顯示回覆中提供的來源標題。
• 使用回覆中的 uri 或 googleMapsUri 連結至來源。

這些圖片顯示來源和 Google 地圖連結的最低顯示需求。

你可以收合來源檢視畫面。

選用：加入其他內容，例如：

• Google 地圖 Favicon 會插入 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 地圖基礎功能會限制特定內容和活動。客戶不得在禁止地區發布或行銷提供 Grounding with Google Maps 的客戶應用程式。目前禁止的國家/地區如下：

• 中國
• 克里米亞
• 古巴
• 頓內次克人民共和國
• 伊朗
• 盧甘斯克人民共和國
• 北韓
• 敘利亞
• 越南

這份清單可能會不時更新。

選用：Google 地圖情境小工具

情境小工具是 Google 地圖正式發布前產品，屬於視覺化容器，用於支援或補充其他 Google 地圖內容。Google 地圖情境小工具可讓您將 Grounding with Google Maps 整合至應用程式，打造對話式大型語言模型輔助的即時通訊體驗。情境小工具是使用情境權杖 googleMapsWidgetContextToken 算繪，該權杖會顯示在 Vertex AI API 回應中，可用於算繪視覺內容。

情境小工具會根據不同情境提供不同功能：

• 在 Google 地圖提示詞用於生成答案的情況下，這項功能會顯示使用者評論和相片，也就是使用者原創內容 (UGC)。

• 當 Vertex AI 只生成文字回覆時，這項功能有助於以地圖視覺化效果和資料豐富結果。

如要進一步瞭解內容相關小工具，請參閱「地圖基礎小工具」。

算繪 Google 地圖情境小工具

如要算繪及使用 Google 地圖情境小工具，請在顯示小工具的頁面上使用 Google Maps JavaScript API 的 Alpha 版。詳情請參閱「載入 Maps JavaScript API」。

下列程式碼範例說明如何使用情境小工具：

1. 建立情境小工具。

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

2. 在任何以 Google 地圖為基礎的回覆中，都會有對應的 googleMapsWidgetContextToken，用於算繪內容相關的小工具，並放置在產生的回覆附近。

   如要更新內容權杖，請設定 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. 選用：變更地圖模式。有效值包括：

   • 2D 發展藍圖地圖：map-mode="roadmap"
   • 3D 混合地圖：map-mode="hybrid"
   • 沒有地圖：map-mode="none"

   這個程式碼範例示範如何將地圖模式變更為 2D 地圖。

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

後續步驟

• 如要進一步瞭解如何根據資料設定 Gemini 模型，請參閱「根據資料設定」一文。
• 如要進一步瞭解負責任的 AI 最佳做法和 Vertex AI 的安全篩選器，請參閱「負責任的 AI」。