Connessione a terra con Google Maps in Vertex AI

Questa pagina descrive come Grounding con Google Maps con Vertex AI può aiutarti a migliorare le tue applicazioni di AI generativa fornendo un contesto geospaziale.

Panoramica

Grounding con Google Maps con Vertex AI è un servizio che connette i modelli Gemini con dati geospaziali di Google Maps. Google Maps ha accesso a informazioni su milioni di località, tra cui attività, punti di riferimento e punti di interesse. Questi dati ti danno accesso a informazioni su oltre 250 milioni di luoghi che possono essere utilizzati per basare le risposte del modello, consentendo alle tue applicazioni e ai tuoi agenti AI di fornire dati locali e contesto geospaziale.

Puoi anche attivare il grounding simultaneo con Google Maps, la Ricerca Google e le tue origini dati.

Utilizzi del grounding con Google Maps

Puoi utilizzare Grounding con Google Maps per varie applicazioni, ad esempio:

  • Assistenti conversazionali che possono rispondere a domande sui luoghi nelle vicinanze, ad esempio "Dov'è il posto più vicino dove posso prendere un espresso italiano?"
  • Descrizioni personalizzate e informazioni della community, ad esempio"Puoi dirmi di più sui ristoranti adatti alle famiglie che si trovano a pochi passi?"
  • Riepiloghi delle aree intorno a luoghi specifici, come una stazione di ricarica EV o un hotel.

Ciò può essere utile per i casi d'uso in ambito immobiliare, viaggi, mobilità e app di social media.

Modelli supportati

Questa sezione elenca i modelli che supportano Grounding con Google Maps.

Per saperne di più sui modelli Gemini, consulta Modelli Gemini.

Utilizzare Grounding con Google Maps per basare le risposte del modello su dati reali

Questo esempio di codice mostra come utilizzare Grounding con Google Maps per basare le risposte del modello.

I risultati di ricerca possono essere personalizzati per una posizione geografica specifica utilizzando le coordinate di latitudine e longitudine. Per ulteriori informazioni, consulta l'API Grounding.

Console

Per utilizzare Grounding con Google Maps con Vertex AI:

  1. Nella console Google Cloud , vai alla pagina Vertex AI Studio.

    Vai a Vertex AI Studio

  2. Nella sezione Strumenti, fai clic su Grounding: Google. Viene visualizzato un riquadro di configurazione.

  3. Per utilizzare Google Maps, fai clic sul pulsante di attivazione/disattivazione Google Maps.

  4. Fai clic su Applica.

  5. Inserisci il prompt nel campo e fai clic su Invia. Le tue risposte rapide in Google Maps.

Python

Installa

pip install --upgrade google-genai

Per saperne di più, consulta la documentazione di riferimento dell'SDK.

Imposta le variabili di ambiente per utilizzare l'SDK Gen AI con Vertex AI: 

# 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(
              enable_widget=False # Optional: return Maps widget token
            ))
        ],
        tool_config=types.ToolConfig(
            retrieval_config = types.RetrievalConfig(
                lat_lng = types.LatLng( # Pass geo 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: ...'

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • LOCATION: la regione in cui elaborare la richiesta. Per utilizzare l'endpoint globale, escludi la località dal nome dell'endpoint e configura la località della risorsa come globale.
  • PROJECT_ID: il tuo ID progetto
  • MODEL_ID: L'ID modello del modello multimodale.
  • PROMPT: Il prompt da inviare al modello.
  • LATITUDE: la latitudine della posizione. Ad esempio, una latitudine di 37.7749 rappresenta San Francisco. Puoi ottenere le coordinate di latitudine e longitudine utilizzando servizi come Google Maps o altri strumenti di geocodifica.
  • LONGITUDE: la longitudine della posizione. Ad esempio, una longitudine di -122.4194 rappresenta San Francisco.
  • ENABLE_WIDGET: indica se restituire un token e attivare il widget Google Maps (il valore predefinito è false).

Metodo HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent

Corpo JSON della richiesta: 

{
  "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"
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

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

Proprietà del luogo

Questa sezione elenca le proprietà dei luoghi utilizzate per descrivere le località e utilizzate da Grounding con Google Maps per generare risposte. Queste proprietà vengono utilizzate per determinare i tipi di domande a cui può rispondere Grounding con Google Maps.

Proprietà del luogo di esempio

Questo elenco fornisce un campionamento alfabetico delle proprietà dei luoghi che possono essere utilizzate dal modello per generare risposte.

  • Indirizzo
  • Ritiro all'esterno
  • Carta di debito
  • Distanza
  • Parcheggio gratuito
  • Musica dal vivo
  • Menu per bambini
  • Orari di apertura
  • Opzioni di pagamento (ad es. contanti o carta di credito)
  • Risposta sul luogo
  • Animali ammessi
  • Serve birra
  • Serve cibo vegetariano
  • Accessibile in sedia a rotelle
  • Wi-Fi

Le risposte ai luoghi sono una risposta di Grounding con Google Maps basata su informazioni derivate dalle recensioni degli utenti.

Esempi di utilizzo delle proprietà dei luoghi

Gli esempi seguenti utilizzano le proprietà dei luoghi nelle domande su diversi tipi di luoghi. La fondazione con Google Maps utilizza le proprietà per comprendere la tua intenzione e poi fornisce risposte pertinenti in base ai dati associati ai luoghi in Google Maps.

  • Organizzare una cena in famiglia: potresti chiedere: "Il ristorante "The Italian Place" è adatto ai bambini e offre il servizio d'asporto?" Qual è la loro valutazione?

    Le risposte a queste domande ti aiutano a determinare se un ristorante è adatto a una famiglia e se offre un servizio conveniente.

  • Controllare l'accessibilità per un amico: potresti chiedere: Ho bisogno di un ristorante con un ingresso accessibile in sedia a rotelle.

    Una risposta a questa richiesta potrebbe aiutarti a determinare se la posizione soddisfa esigenze di accessibilità specifiche.

  • Trovare un posto per uno spuntino a tarda notte: potresti chiedere "Burger Joint" è aperto ora? Serve la cena? Quali sono gli orari di apertura per venerdì?

    Le risposte a queste domande ti aiutano a trovare un'attività aperta che serve un pasto specifico in un determinato momento.

  • Incontrare un cliente per un caffè: potresti chiedere: Il "Cafe Central" ha il Wi-Fi? Servono caffè? Qual è il loro livello di prezzo e accettano carte di credito?

    Le risposte a queste domande ti aiutano a valutare l'idoneità di un caffè per un incontro di lavoro in base ai servizi, alle offerte e alle opzioni di pagamento.

Le informazioni nei risultati basati su dati reali di Google Maps potrebbero differire dalle condizioni effettive della strada.

Comprendere la risposta

Le fonti di Google Maps vengono restituite in groundingMetadata entro groundingChunks. Le fonti vengono restituite per i luoghi e per le recensioni degli utenti, che sono state utilizzate per generare il risultato basato su Google Maps.

Questo esempio di codice mostra una fonte di luogo e una fonte di risposta di luogo nella risposta:

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

Requisiti per l'utilizzo del servizio

Questa sezione descrive i requisiti di utilizzo del servizio per Grounding con Google Maps.

Informa l'utente dell'utilizzo delle fonti di Google Maps

Per ogni risultato basato su dati reali di Google Maps, riceverai fonti in groundingChunks che supportano ogni risposta. Vengono restituiti anche i seguenti metadati:

  • source uri
  • titolo
  • ID

Quando presenti i risultati di Grounding con Google Maps con Vertex AI, devi specificare le fonti di Google Maps associate e informare gli utenti di quanto segue:

  • Le fonti di Google Maps devono seguire immediatamente i contenuti generati che supportano le fonti. Questi contenuti generati sono anche chiamati risultato basato su dati reali di Google Maps.
  • Le fonti di Google Maps devono essere visualizzabili in una sola interazione dell'utente.

Per ogni origine in groundingChunks e in grounding_chunks.maps.placeAnswerSources.reviewSnippets, deve essere generata un'anteprima del link in base ai seguenti requisiti:

Queste immagini mostrano i requisiti minimi per la visualizzazione delle fonti e dei link di Google Maps.

Prompt con risposta che mostra le fonti

Puoi comprimere la visualizzazione delle fonti.

Prompt con risposta e fonti compresse

(Facoltativo) Migliora l'anteprima del link con contenuti aggiuntivi, ad esempio:

  • Viene inserita una favicon di Google Maps prima dell'attribuzione del testo di Google Maps.
  • Una foto dall'URL di origine (og:image).

Per ulteriori informazioni su alcuni dei nostri fornitori di dati di Google Maps e sui relativi termini di licenza, consulta le note legali di Google Maps e Google Earth.

Linee guida per l'attribuzione di testo di Google Maps

Quando attribuisci le fonti a Google Maps nel testo, segui queste linee guida:

  • Non modificare in alcun modo il testo Google Maps:
    • Non modificare le maiuscole di Google Maps.
    • Non mandare a capo Google Maps.
    • Non localizzare Google Maps in un'altra lingua.
    • Impedisci ai browser di tradurre Google Maps utilizzando l'attributo HTML translate="no".
  • Formatta il testo Google Maps come descritto nella tabella seguente:
Proprietà Stile
Famiglia di caratteri Roboto. Il caricamento del carattere è facoltativo.
Famiglia di caratteri di riserva Qualsiasi carattere del corpo sans-serif già utilizzato nel tuo prodotto o "Sans-Serif" per richiamare il carattere di sistema predefinito
Stile carattere Normale
Spessore del carattere 400
Colore carattere Bianco, nero (#1F1F1F) o grigio (#5E5E5E). Mantenere un contrasto accessibile (4,5:1) rispetto allo sfondo.
Dimensione carattere Dimensioni carattere minime: 12 sp
Dimensioni carattere massime: 16 sp
Per saperne di più su sp, consulta Unità di dimensione carattere sul sito web Material Design.
Spaziatura tra le lettere Normale

CSS di esempio

Il seguente CSS esegue il rendering di Google Maps con lo stile e il colore tipografici appropriati su uno sfondo bianco o chiaro.

@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 di contesto, ID luogo e ID recensione

I dati di Google Maps includono token di contesto, ID luogo e ID recensione. Potresti memorizzare nella cache, archiviare ed esportare i seguenti dati delle risposte:

  • googleMapsWidgetContextToken
  • placeId
  • reviewId

Le limitazioni alla memorizzazione nella cache previste dai Termini del grounding con Google Maps non si applicano.

Territorio vietato

La funzionalità di grounding con Google Maps presenta limitazioni per determinati contenuti e attività per mantenere una piattaforma sicura e affidabile. Il Cliente non distribuirà né commercializzerà un'Applicazione del Cliente che offre la funzionalità di Grounding con Google Maps in un Territorio vietato. I territori attualmente vietati sono:

  • Cina
  • Crimea
  • Cuba
  • Repubblica Popolare di Donetsk
  • Iran
  • Repubblica popolare di Lugansk
  • Corea del Nord
  • Siria
  • Vietnam

Questo elenco potrebbe essere aggiornato di tanto in tanto.

(Facoltativo) Widget contestuale di Google Maps

Il widget contestuale è un'offerta pre-GA di Google Maps che funge da contenitore visivo utilizzato per supportare o integrare altri contenuti di Google Maps. Il widget contestuale di Google Maps ti consente di integrare Grounding con Google Maps nelle tue applicazioni per creare un'esperienza di chat conversazionale basata su LLM. Il widget contestuale viene visualizzato utilizzando il token di contesto, googleMapsWidgetContextToken, restituito nella risposta dell'API Vertex AI e può essere utilizzato per visualizzare contenuti visivi.

Il widget contestuale svolge diverse funzioni a seconda dello scenario:

  • Mostra le recensioni e le foto degli utenti, ovvero i contenuti generati dagli utenti, nello scenario in cui viene utilizzato il prompt di Google Maps per la generazione di risposte.

  • Consente di arricchire i risultati con visualizzazioni e dati della mappa quando Vertex AI genera solo una risposta di testo.

Per ulteriori informazioni sul widget contestuale, vedi Widget di grounding di Maps.

Esegui il rendering del widget contestuale di Google Maps

Per eseguire il rendering e utilizzare il widget contestuale di Google Maps, utilizza la versione alfa dell'API Google Maps JavaScript nella pagina che mostra il widget. Per ulteriori informazioni, consulta Caricare l'API Maps JavaScript.

I seguenti esempi di codice mostrano come utilizzare un widget contestuale:

  1. Crea un widget contestuale.

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

  2. In qualsiasi risposta basata su Google Maps, è presente un googleMapsWidgetContextToken corrispondente utilizzato per il rendering del widget contestuale, posizionato in prossimità della risposta generata.

    Per aggiornare il token di contesto, imposta 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. (Facoltativo) Specifica il layout dell'elenco. I valori validi includono:

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

    Questo esempio di codice mostra come modificare il layout elenco in un layout compatto.

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

  4. (Facoltativo) Cambia la modalità mappa. I valori validi includono:

    • Mappa della roadmap 2D: map-mode="roadmap"
    • Mappa ibrida 3D: map-mode="hybrid"
    • Nessuna mappa: map-mode="none"

    Questo esempio di codice mostra come passare alla modalità mappa 2D.

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

Passaggi successivi

  • Per scoprire di più su come basare i modelli Gemini sui tuoi dati, vedi Grounding con i tuoi dati.
  • Per scoprire di più sulle best practice per l'AI responsabile e sui filtri di sicurezza di Vertex AI, consulta AI responsabile.