Fundierung mit Google Maps in Vertex AI

Auf dieser Seite wird beschrieben, wie Sie Ihre generativen KI-Anwendungen mit Grounding mit Google Maps in Vertex AI durch die Bereitstellung von geospatialem Kontext verbessern können.

Übersicht

„Grounding with Google Maps with Vertex AI“ ist ein Dienst, der Gemini-Modelle mit geografischen Daten von Google Maps verbindet. Google Maps hat Zugriff auf Informationen zu Millionen von Orten, darunter Unternehmen, Sehenswürdigkeiten und POIs. Mit diesen Daten haben Sie Zugriff auf Informationen zu über 250 Millionen Orten, die Sie verwenden können, um die Antworten Ihres Modells zu fundieren. So können Ihre KI-Anwendungen und ‑Agents lokale Daten und geospatialen Kontext bereitstellen.

Sie können auch die gleichzeitige Fundierung mit Google Maps, der Google Suche und Ihren Datenquellen aktivieren.

Anwendungsbereiche der Fundierung mit Google Maps

Sie können die Fundierung mit Google Maps für verschiedene Anwendungen verwenden, z. B.:

• Konversationelle Assistenten, die Fragen zu Orten in der Nähe beantworten können, z. B. „Wo gibt es in der Nähe einen italienischen Espresso?“
• Personalisierte Beschreibungen und Community-Informationen, z. B. „Kannst du mir mehr über familienfreundliche Restaurants in Gehweite erzählen?“
• Zusammenfassungen von Gebieten in der Nähe bestimmter Orte, z. B. einer Ladestation für Elektrofahrzeuge oder eines Hotels.

Das kann für Anwendungsfälle in Immobilien-, Reise-, Mobilitäts- und Social-Media-Apps von Vorteil sein.

Unterstützte Modelle

In diesem Abschnitt sind die Modelle aufgeführt, die Grounding mit Google Maps unterstützen.

• Gemini 2.5 Flash (Vorschau)
• Gemini 2.5 Flash-Lite (Vorschau)
• Gemini 2.5 Flash-Lite
• Gemini 2.5 Flash mit nativer Audio-Live-API (Vorabversion)
• Gemini 2.0 Flash mit Live API (Vorschau)
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

Weitere Informationen zu den Gemini-Modellen finden Sie unter Gemini-Modelle.

Fundierung mit Google Maps verwenden, um die Antworten Ihres Modells zu fundieren

In diesem Codebeispiel wird gezeigt, wie Sie die Fundierung mit Google Maps verwenden, um die Antworten Ihres Modells zu fundieren.

Suchergebnisse können mithilfe der Breiten- und Längengradkoordinaten für einen bestimmten geografischen Standort angepasst werden. Weitere Informationen finden Sie in der 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/..."
      }
    }
  ],
  ...
}

Ortsattribute

In diesem Abschnitt werden die Ortsattribute aufgeführt, die zur Beschreibung von Orten verwendet werden und die von Grounding mit Google Maps zum Generieren von Antworten verwendet werden. Mit diesen Eigenschaften wird festgelegt, welche Arten von Fragen mit Grounding mit Google Maps beantwortet werden können.

Beispiele für Ortseigenschaften

Diese Liste enthält eine alphabetisch sortierte Auswahl von Eigenschaften zu Orten, die von Ihrem Modell zum Generieren von Antworten verwendet werden können.

• Adresse
• Abholung vor dem Laden
• Debitkarte
• Entfernung
• Kostenlose Parkplätze
• Livemusik
• Menü für Kinder
• Öffnungszeiten
• Zahlungsoptionen (z. B. Barzahlung oder Kreditkarte)
• Antwort zu Ort
• Haustierfreundlich
• Bier
• Vegetarische Speisen
• Rollstuhlgerecht
• WLAN

Ortsbezogene Antworten sind Antworten, die auf Informationen aus Nutzerrezensionen basieren und mit Google Maps fundiert werden.

Beispiele für die Verwendung von Orteigenschaften

In den folgenden Beispielen werden Ortsattribute in Fragen zu verschiedenen Arten von Orten verwendet. Bei der Fundierung mit Google Maps werden die Eigenschaften verwendet, um Ihre Intention zu verstehen. Anschließend werden relevante Antworten auf Grundlage der Daten zu Orten in Google Maps bereitgestellt.

• Ein Familienessen planen: Sie könnten fragen: Ist „The Italian Place“ für Kinder geeignet und bieten sie Essen zum Mitnehmen an? Wie ist ihre Bewertung?

  Anhand der Antworten auf diese Fragen können Sie feststellen, ob ein Restaurant für eine Familie geeignet ist und ob es einen praktischen Service bietet.

• Barrierefreiheit für einen Freund prüfen: Sie könnten fragen: Ich suche ein Restaurant mit einem rollstuhlgerechten Eingang.

  Eine Antwort auf diesen Prompt kann Ihnen helfen, festzustellen, ob der Ort bestimmte Anforderungen an die Barrierefreiheit erfüllt.

• Einen Ort für einen Mitternachtssnack finden: Sie könnten fragen: Ist „Burger Joint“ jetzt geöffnet? Wird hier Abendessen serviert? Welche Öffnungszeiten gelten am Freitag?

  Die Antworten auf diese Fragen helfen Ihnen, ein geöffnetes Lokal zu finden, in dem zu einer bestimmten Zeit ein bestimmtes Gericht serviert wird.

• Mit einem Kunden in einem Café treffen: Sie könnten fragen: Hat das „Cafe Central“ WLAN? Gibt es hier Kaffee? Wie hoch ist das Preisniveau und werden Kreditkarten akzeptiert?

  Anhand der Antworten auf diese Fragen können Sie die Eignung eines Cafés für ein Geschäftstreffen anhand von Annehmlichkeiten, Angeboten und Zahlungsoptionen beurteilen.

Die Informationen in den fundierten Google Maps-Ergebnissen können von den tatsächlichen Straßenverhältnissen abweichen.

Ihre Antwort verstehen

Google Maps-Quellen werden in groundingMetadata innerhalb von groundingChunks zurückgegeben. Quellen werden für Orte und Nutzerrezensionen zurückgegeben, die zur Generierung des fundierten Google Maps-Ergebnisses verwendet wurden.

In diesem Codebeispiel werden eine Ortsquelle und eine Ortsantwortquelle in der Antwort veranschaulicht:

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

Anforderungen an die Dienstnutzung

In diesem Abschnitt werden die Anforderungen für die Nutzung von Fundierung mit Google Maps beschrieben.

Nutzer über die Verwendung von Google Maps-Quellen informieren

Bei jedem fundierten Google Maps-Ergebnis erhalten Sie Quellen in groundingChunks, die jede Antwort untermauern. Die folgenden Metadaten werden ebenfalls zurückgegeben:

• Quell-URI
• Titel
• ID

Wenn Sie Ergebnisse der Fundierung mit Google Maps mit Vertex AI präsentieren, müssen Sie die zugehörigen Google Maps-Quellen angeben und Ihre Nutzer über Folgendes informieren:

• Die Google Maps-Quellen müssen direkt auf die generierten Inhalte folgen, die durch die Quellen belegt werden. Diese generierten Inhalte werden auch als Google Maps Grounded Result bezeichnet.
• Die Google Maps-Quellen müssen innerhalb einer Nutzerinteraktion sichtbar sein.

Google Maps-Quellen mit Google Maps-Links anzeigen

Für jede Quelle in groundingChunks und in grounding_chunks.maps.placeAnswerSources.reviewSnippets muss eine Linkvorschau generiert werden, die den folgenden Anforderungen entspricht:

• Weisen Sie jede Quelle Google Maps gemäß den Richtlinien für die Quellenangabe von Text in Google Maps zu.
• Zeigen Sie den in der Antwort angegebenen Quellentitel an.
• Verlinken Sie die Quelle mit uri oder googleMapsUri aus der Antwort.

Diese Bilder zeigen die Mindestanforderungen für die Anzeige der Quellen und Google Maps-Links.

Sie können die Ansicht der Quellen minimieren.

Optional: Sie können die Linkvorschau mit zusätzlichen Inhalten wie den folgenden erweitern:

• Vor der Google Maps-Quellenangabe wird ein Google Maps-Favicon eingefügt.
• Ein Foto von der Quell-URL (og:image).

Weitere Informationen zu einigen unserer Google Maps-Datenanbieter und ihren Lizenzbedingungen finden Sie in den rechtlichen Hinweisen zu Google Maps und Google Earth.

Richtlinien für die Google Maps-Quellenangabe als Text

Wenn Sie Quellen in Text Google Maps zuordnen, müssen Sie die folgenden Richtlinien beachten:

• Ändern Sie den Text Google Maps nicht:
  • Ändern Sie die Groß- und Kleinschreibung von Google Maps nicht.
  • Fügen Sie keinen Zeilenumbruch in Google Maps ein.
  • Google Maps darf nicht in eine andere Sprache lokalisiert werden.
  • Verhindern Sie, dass Browser Google Maps übersetzen, indem Sie das HTML-Attribut translate="no" verwenden.
• Formatieren Sie den Text Google Maps wie in der folgenden Tabelle beschrieben:

Beispiel-CSS

Mit dem folgenden CSS wird Google Maps mit dem entsprechenden typografischen Stil und der entsprechenden Farbe auf einem weißen oder hellen Hintergrund gerendert.

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

Kontext-Token, Orts-ID und Rezensions-ID

Die Google Maps-Daten umfassen Kontext-Token, Orts-ID und Rezensions-ID. Sie können die folgenden Antwortdaten im Cache speichern, speichern und exportieren:

• googleMapsWidgetContextToken
• placeId
• reviewId

Die Einschränkungen für das Caching in den Nutzungsbedingungen für die Fundierung mit Google Maps gelten nicht.

Unzulässiges Gebiet

Für die Fundierung mit Google Maps gelten Einschränkungen für bestimmte Inhalte und Aktivitäten, um eine sichere und zuverlässige Plattform zu gewährleisten. Der Kunde darf in einem verbotenen Gebiet keine Kundenanwendung vertreiben oder bewerben, die Grounding mit Google Maps bietet. Die derzeit verbotenen Gebiete sind:

• China
• Krim
• Kuba
• Volksrepublik Donezk
• Iran
• Volksrepublik Lugansk
• Nordkorea
• Syrien
• Vietnam

Diese Liste kann von Zeit zu Zeit aktualisiert werden.

Optional: Kontextbezogenes Google Maps-Widget

Das kontextbezogene Widget ist ein Pre-GA-Angebot von Google Maps, das als visueller Container zur Unterstützung oder Ergänzung anderer Google Maps-Inhalte verwendet wird. Mit dem kontextbezogenen Google Maps-Widget können Sie Grounding mit Google Maps in Ihre Anwendungen einbinden, um eine dialogbasierte, LLM-basierte Chatfunktion zu erstellen. Das kontextbezogene Widget wird mit dem Kontext-Token googleMapsWidgetContextToken gerendert, das in der Antwort der Vertex AI API zurückgegeben wird und zum Rendern visueller Inhalte verwendet werden kann.

Das kontextbezogene Widget hat je nach Szenario unterschiedliche Funktionen:

• Es werden Nutzerrezensionen und ‑fotos angezeigt, die von Nutzern erstellte Inhalte sind, wenn Google Maps-Prompts zur Antwortgenerierung verwendet werden.

• Damit lassen sich Ergebnisse mit Kartendarstellungen und Daten anreichern, wenn Vertex AI nur eine Textantwort generiert.

Weitere Informationen zum kontextbezogenen Widget finden Sie unter Maps-Fundierungs-Widget.

Kontextbezogenes Google Maps-Widget rendern

Wenn Sie das kontextbezogene Google Maps-Widget rendern und verwenden möchten, müssen Sie die Alphaversion der Google Maps JavaScript API auf der Seite verwenden, auf der das Widget angezeigt wird. Weitere Informationen finden Sie unter Maps JavaScript API laden.

Die folgenden Codebeispiele zeigen, wie ein kontextbezogenes Widget verwendet wird:

1. Kontextbezogenes Widget erstellen

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

2. In jeder Antwort, die auf Google Maps basiert, gibt es ein entsprechendes googleMapsWidgetContextToken, mit dem das kontextbezogene Widget gerendert wird. Es wird in unmittelbarer Nähe der generierten Antwort platziert.

   Legen Sie widget.contextToken property fest, um das Kontext-Token zu aktualisieren.

   "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. Optional: Geben Sie das Listenlayout an. Gültige Werte sind:

   • Kompaktes Layout: <gmp-place-contextual-list-config layout="compact">
   • Vertikales Layout: <gmp-place-contextual-list-config layout="vertical">

   In diesem Codebeispiel wird gezeigt, wie das Listenlayout in ein kompaktes Layout geändert wird.

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

4. Optional: Ändern Sie den Kartenmodus. Gültige Werte sind:

   • 2D-Roadmap-Karte: map-mode="roadmap"
   • 3D-Hybridkarte: map-mode="hybrid"
   • Keine Karte: map-mode="none"

   In diesem Codebeispiel wird gezeigt, wie Sie den Kartenmodus in eine 2D-Karte ändern.

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

Nächste Schritte

• Weitere Informationen zur Fundierung von Gemini-Modellen auf Ihren Daten finden Sie unter Fundierung mit Ihren Daten.
• Weitere Informationen zu Best Practices für verantwortungsbewusste KI und den Sicherheitsfiltern von Vertex AI finden Sie unter Verantwortungsbewusste KI.