Grounding dengan Google Maps di Vertex AI

Halaman ini menjelaskan bagaimana Perujukan dengan Google Maps dan Vertex AI dapat membantu meningkatkan kualitas aplikasi AI generatif Anda dengan memberikan konteks geospasial.

Ringkasan

Penyesuaian dengan Google Maps menggunakan Vertex AI adalah layanan yang menghubungkan model Gemini dengan data geospasial dari Google Maps. Google Maps memiliki akses ke informasi tentang jutaan lokasi, termasuk bisnis, landmark, dan tempat menarik. Data ini memberi Anda akses ke informasi tentang lebih dari 250 juta tempat yang dapat digunakan untuk mendasari respons model Anda, sehingga memungkinkan aplikasi dan agen AI Anda memberikan data lokal dan konteks geospasial.

Anda juga dapat mengaktifkan perujukan serentak dengan Google Maps, Google Penelusuran, dan perujukan dengan sumber data Anda.

Penggunaan Perujukan dengan Google Maps

Anda dapat menggunakan Grounding dengan Google Maps untuk berbagai aplikasi, seperti:

• Asisten percakapan yang dapat menjawab pertanyaan tentang tempat terdekat, seperti "Di mana tempat terdekat untuk mendapatkan espresso Italia?"
• Deskripsi yang dipersonalisasi dan insight komunitas, seperti"Bisakah Anda memberi tahu saya lebih lanjut tentang restoran ramah keluarga yang berada dalam jarak yang dapat ditempuh dengan berjalan kaki?"
• Ringkasan area di sekitar lokasi tertentu, seperti SPKLU atau hotel.

Hal ini dapat bermanfaat untuk kasus penggunaan di aplikasi real estat, perjalanan, mobilitas, dan media sosial.

Model yang didukung

Bagian ini mencantumkan model yang mendukung Perujukan dengan Google Maps.

• Gemini 2.5 Flash (Pratinjau)
• Gemini 2.5 Flash-Lite (Pratinjau)
• Gemini 2.5 Flash-Lite
• Gemini 2.5 Flash dengan audio native Live API (Pratinjau)
• Gemini 2.0 Flash dengan Live API (Pratinjau)
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

Untuk mengetahui informasi selengkapnya tentang model Gemini, lihat Model Gemini.

Menggunakan Perujukan dengan Google Maps untuk merujuk respons model Anda

Contoh kode ini menunjukkan cara menggunakan Perujukan dengan Google Maps untuk merujuk respons model Anda.

Hasil penelusuran dapat disesuaikan untuk lokasi geografis tertentu menggunakan koordinat lintang dan bujur. Untuk mengetahui informasi selengkapnya, lihat API Perujukan.

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/..."
      }
    }
  ],
  ...
}

Properti tempat

Bagian ini mencantumkan properti tempat yang digunakan untuk mendeskripsikan lokasi dan digunakan oleh Perujukan dengan Google Maps untuk menghasilkan respons. Properti ini digunakan untuk menentukan jenis pertanyaan yang dapat dijawab oleh Perujukan dengan Google Maps.

Contoh properti tempat

Daftar ini memberikan contoh properti yang diurutkan berdasarkan abjad tentang tempat yang dapat digunakan oleh model Anda untuk menghasilkan respons.

• Alamat
• Pengambilan di tepi jalan
• Kartu debit
• Jarak
• Tempat parkir gratis
• Musik live
• Menu untuk anak-anak
• Jam buka
• Opsi pembayaran (seperti tunai atau kartu kredit)
• Tempat jawaban
• Boleh bawa hewan peliharaan
• Menyajikan bir
• Menyajikan makanan vegetarian
• Dapat diakses pengguna kursi roda
• Wi-Fi

Jawaban tempat adalah respons dari Perujukan dengan Google Maps berdasarkan informasi yang berasal dari ulasan pengguna.

Contoh penggunaan properti tempat

Contoh berikut menggunakan properti tempat dalam pertanyaan tentang berbagai jenis tempat. Perujukan dengan Google Maps menggunakan properti untuk memahami maksud Anda, lalu memberikan jawaban yang relevan berdasarkan data yang terkait dengan tempat di Google Maps.

• Merencanakan makan malam keluarga: Anda dapat bertanya, Apakah "The Italian Place" cocok untuk anak-anak, dan apakah mereka menawarkan layanan pesan bawa? Berapa rating mereka?

  Jawaban atas pertanyaan-pertanyaan ini akan membantu Anda menentukan apakah restoran tersebut cocok untuk keluarga dan apakah restoran tersebut menawarkan layanan yang nyaman.

• Memeriksa aksesibilitas untuk teman: Anda dapat bertanya, Saya perlu restoran yang memiliki pintu masuk yang dapat diakses kursi roda.

  Respons terhadap perintah ini dapat membantu Anda menentukan apakah lokasi tersebut memenuhi kebutuhan aksesibilitas tertentu.

• Menemukan lokasi untuk camilan larut malam: Anda dapat bertanya, Apakah "Burger Joint" buka sekarang? Apakah mereka menyajikan makan malam? Jam berapa mereka buka pada hari Jumat?

  Jawaban atas pertanyaan ini membantu Anda menemukan restoran yang buka dan menyajikan makanan tertentu pada waktu tertentu.

• Bertemu klien di kedai kopi: Anda dapat bertanya, Apakah "Cafe Central" memiliki Wi-Fi? Apakah mereka menyajikan kopi? Berapa tingkat harganya, dan apakah mereka menerima kartu kredit?

  Jawaban atas pertanyaan ini akan membantu Anda menilai kesesuaian kafe untuk pertemuan bisnis berdasarkan fasilitas, penawaran, dan opsi pembayaran.

Informasi dalam Hasil Terperinci Google Maps mungkin berbeda dengan kondisi jalan yang sebenarnya.

Memahami respons Anda

Sumber Google Maps ditampilkan di groundingMetadata dalam groundingChunks. Sumber ditampilkan untuk tempat dan ulasan pengguna, yang telah digunakan untuk membantu membuat Hasil Berbasis Fakta Google Maps.

Contoh kode ini menunjukkan sumber tempat dan sumber jawaban tempat dalam respons:

"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}"
          }
        ]
      }
    },
  }
],

Persyaratan penggunaan layanan

Bagian ini menjelaskan persyaratan penggunaan layanan untuk Perujukan dengan Google Maps.

Memberi tahu pengguna tentang penggunaan sumber Google Maps

Untuk setiap Hasil yang Sesuai dengan Google Maps, Anda akan menerima sumber dalam groundingChunks yang mendukung setiap respons. Metadata berikut juga ditampilkan:

• URI sumber
• title
• ID

Saat menyajikan hasil dari Perujukan dengan Google Maps menggunakan Vertex AI, Anda harus menentukan sumber Google Maps terkait, dan memberi tahu pengguna Anda tentang hal berikut:

• Sumber Google Maps harus segera mengikuti konten yang dihasilkan yang didukung oleh sumber tersebut. Konten yang dihasilkan ini juga disebut sebagai Hasil yang Sesuai dengan Konteks Google Maps.
• Sumber Google Maps harus dapat dilihat dalam satu interaksi pengguna.

Menampilkan sumber Google Maps dengan link Google Maps

Untuk setiap sumber di groundingChunks dan di grounding_chunks.maps.placeAnswerSources.reviewSnippets, pratinjau link harus dibuat dengan mengikuti persyaratan berikut:

• Atribusikan setiap sumber ke Google Maps dengan mengikuti panduan atribusi teks Google Maps.
• Menampilkan judul sumber yang diberikan dalam respons.
• Tautkan ke sumber menggunakan uri atau googleMapsUri dari respons.

Gambar ini menunjukkan persyaratan minimum untuk menampilkan sumber dan link Google Maps.

Anda dapat menciutkan tampilan sumber.

Opsional: Tingkatkan kualitas pratinjau link dengan konten tambahan, seperti:

• Favicon Google Maps disisipkan sebelum atribusi teks Google Maps.
• Foto dari URL sumber (og:image).

Untuk mengetahui informasi selengkapnya tentang beberapa penyedia data Google Maps kami dan persyaratan lisensi mereka, lihat pemberitahuan hukum Google Maps dan Google Earth.

Panduan atribusi teks Google Maps

Saat Anda mengatribusikan sumber ke Google Maps dalam teks, ikuti panduan berikut:

• Jangan ubah teks Google Maps dengan cara apa pun:
  • Jangan mengubah kapitalisasi Google Maps.
  • Jangan pindahkan Google Maps ke beberapa baris.
  • Jangan melokalkan Google Maps ke bahasa lain.
  • Mencegah browser menerjemahkan Google Maps dengan menggunakan atribut HTML translate="no".
• Gaya teks Google Maps seperti yang dijelaskan dalam tabel berikut:

Contoh CSS

CSS berikut merender Google Maps dengan gaya dan warna tipografi yang sesuai di latar belakang putih atau terang.

@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;
}

Token konteks, ID tempat, dan ID ulasan

Data Google Maps mencakup token konteks, ID tempat, dan ID ulasan. Anda dapat menyimpan dalam cache, menyimpan, dan mengekspor data respons berikut:

• googleMapsWidgetContextToken
• placeId
• reviewId

Pembatasan terhadap penyimpanan cache dalam Persyaratan Grounding dengan Google Maps tidak berlaku.

Wilayah Terlarang

Penggunaan Google Maps sebagai dasar memiliki batasan untuk konten dan aktivitas tertentu guna mempertahankan platform yang aman dan andal. Pelanggan tidak akan mendistribusikan atau memasarkan Aplikasi Pelanggan yang menawarkan Perujukan dengan Google Maps di Wilayah yang Dilarang. Wilayah Terlarang saat ini adalah:

• China
• Krimea
• Kuba
• Republik Rakyat Donetsk
• Iran
• Republik Rakyat Luhansk
• Korea Utara
• Suriah
• Vietnam

Daftar ini dapat diperbarui dari waktu ke waktu.

Opsional: Widget kontekstual Google Maps

Widget kontekstual adalah Penawaran Pra-GA Google Maps yang merupakan penampung visual yang digunakan untuk mendukung atau melengkapi konten Google Maps lainnya. Widget kontekstual Google Maps memungkinkan Anda mengintegrasikan Perujukan dengan Google Maps ke dalam aplikasi untuk menciptakan pengalaman percakapan berbasis chat yang didukung LLM. Widget kontekstual dirender menggunakan token konteks, googleMapsWidgetContextToken, yang ditampilkan dalam respons Vertex AI API dan dapat digunakan untuk merender konten visual.

Widget kontekstual memiliki fungsi yang berbeda-beda, bergantung pada skenario Anda:

• Fitur ini menampilkan ulasan dan foto pengguna, yang merupakan konten buatan pengguna (UGC), dalam skenario saat perintah Google Maps digunakan untuk pembuatan jawaban.

• Fitur ini membantu memperkaya hasil dengan visualisasi dan data peta saat Vertex AI hanya menghasilkan respons teks.

Untuk mengetahui informasi selengkapnya tentang widget kontekstual, lihat widget perujukan Maps.

Merender widget kontekstual Google Maps

Untuk merender dan menggunakan widget kontekstual Google Maps, gunakan Google Maps JavaScript API versi alfa di halaman yang menampilkan widget. Untuk mengetahui informasi selengkapnya, lihat artikel Memuat Maps JavaScript API.

Contoh kode berikut menunjukkan cara menggunakan widget kontekstual:

1. Buat widget kontekstual.

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

2. Dalam setiap respons yang didasarkan pada Google Maps, ada googleMapsWidgetContextToken yang sesuai yang digunakan untuk merender widget kontekstual dan ditempatkan di dekat respons yang dihasilkan.

   Untuk memperbarui token konteks, tetapkan 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. Opsional: Tentukan tata letak daftar. Nilai yang valid mencakup berikut ini:

   • Tata letak ringkas: <gmp-place-contextual-list-config layout="compact">
   • Tata letak vertikal: <gmp-place-contextual-list-config layout="vertical">

   Contoh kode ini menunjukkan cara mengubah tata letak daftar menjadi tata letak rapat.

      <gmp-place-contextual id="widget">
        <gmp-place-contextual-list-config layout="compact">
        </gmp-place-contextual-list-config>
      </gmp-place-contextual>
   

4. Opsional: Ubah mode peta. Nilai yang valid mencakup berikut ini:

   • Peta jalan 2D: map-mode="roadmap"
   • Peta hybrid 3D: map-mode="hybrid"
   • Tidak ada peta: map-mode="none"

   Contoh kode ini menunjukkan cara mengubah mode peta menjadi peta 2D.

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

Langkah berikutnya

• Untuk mempelajari lebih lanjut cara mendasarkan model Gemini pada data Anda, lihat Mendasarkan dengan data Anda.
• Untuk mempelajari lebih lanjut praktik terbaik AI yang bertanggung jawab dan filter keamanan Vertex AI, lihat Responsible AI.