Questa pagina descrive come il grounding con Google Maps in Vertex AI può aiutarti a migliorare le tue applicazioni di AI generativa fornendo un contesto geospaziale.
Panoramica
Grounding con Google Maps in Vertex AI è un servizio di anteprima che collega i modelli Gemini ai dati geospaziali di Google Maps. Google Maps ha accesso a informazioni su milioni di località, tra cui attività commerciali, punti di riferimento e punti di interesse. Questi dati ti consentono di accedere a informazioni su oltre 250 milioni di luoghi che possono essere utilizzati per basare le risposte del tuo modello, consentendo alle tue applicazioni e ai tuoi agenti AI di fornire dati locali e contesto geospaziale.
Utilizzi del grounding con Google Maps
Puoi utilizzare Grounding con Google Maps per varie applicazioni, ad esempio:
- Agenti basati sulla chat.
- Riepilogo delle informazioni sul luogo.
- Traduzione dei contenuti.
- Assistenti conversazionali in grado di rispondere a domande su luoghi nelle vicinanze, ad esempio "Ci sono parchi nelle vicinanze?".
- Descrizioni personalizzate di luoghi, ad esempio "Puoi dirmi di più sui parchi e sui ristoranti adatti alle famiglie che si trovano a una distanza raggiungibile a piedi?"
Ciò può essere utile per settori come quello immobiliare, dei viaggi, della mobilità e delle applicazioni social.
Per assistenza tecnica con Grounding con Google Maps, invia un'email all'indirizzo maps-grounding-feedback-external@google.com.
Modelli supportati
Questa sezione elenca i modelli che supportano la fondazione con Google Maps.
- Gemini 2.5 Flash-Lite
- Gemini 2.5 Flash con audio nativo dell'API Live (anteprima)
- Gemini 2.0 Flash con API Live (anteprima)
- Gemini 2.5 Pro
- Gemini 2.5 Flash
- Gemini 2.0 Flash
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 Studio, segui questi passaggi:
- Nella console Google Cloud , vai alla pagina Vertex AI Studio.
- Fai clic sulla scheda Freeform.
- Nel riquadro laterale, fai clic sul pulsante di attivazione/disattivazione Risposte del modello di base.
- Fai clic su Personalizza e imposta Google Maps come origine.
- Inserisci il prompt nella casella di testo e fai clic su Invia.
Le tue risposte rapide a Google Maps.
REST
Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:
- LOCATION: la regione in cui elaborare la richiesta.
- PROJECT_ID: il tuo ID progetto
- MODEL_ID: L'ID modello del modello multimodale.
- TEXT: Le istruzioni di testo da includere nel prompt.
- LATITUDE: la latitudine della posizione. Ad esempio, una latitudine di
37.7749rappresenta 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.4194rappresenta San Francisco.
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": "TEXT"
}]
}],
"tools": [{
"googleMaps": {}
}],
"toolConfig": {
"retrievalConfig": {
"latLng": {
"latitude": LATITUDE,
"longitude": LONGITUDE
}
}
},
"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",
"text": "**About:**\n\n* **Type:** Italian Restaurant\n* **Address:** 621 Wythe St, Alexandria, VA 22314, USA\n* **Open Now:** Yes\n* **Rating:** 4.2 (411 reviews)\n* **Price Level:** Moderate\n* **Phone:** (571) 777-8981\n* **Summary:** Down-to-earth, counter-serve stop offering Italian sandwiches, coffee & market goods.\n* **Additional Summary:** Relaxed Italian eatery known for sandwiches and pizza along with gourmet food items and gelato.\n* **Offers Takeout:** Yes\n* **Offers Delivery:** Yes\n* **Offers Dine-in:** Yes\n* **Good for Children:** Yes\n* **Has Restroom:** Yes\n* **Outdoor Seating:** Yes\n* **Live Music:** No\n* **Menu for Children:** No\n* **Serves Dessert:** Yes\n* **Serves Coffee:** Yes\n* **Good for Watching Sports:** No\n* **Serves Lunch:** Yes\n* **Serves Dinner:** Yes\n* **Serves Beer:** Yes\n* **Serves Vegetarian Food:** Yes\n\n**Opening Hours (local time):**\n\n* Monday: 11:00 AM – 7:00 PM\n* Tuesday: 10:00 AM – 7:00 PM\n* Wednesday: 11:00 AM – 7:00 PM\n* Thursday: 11:00 AM – 7:00 PM\n* Friday: 11:00 AM – 7:00 PM\n* Saturday: 11:00 AM – 7:00 PM\n* Sunday: 12:00 – 7:00 PM\n\n**Parking options:**\n\n* **Free parking lot:** Yes\n* **Free street parking:** Yes\n* **Valet parking:** No\n\n**Accessibility:**\n\n* **Wheelchair accessible parking:** Yes\n* **Wheelchair accessible restroom:** Yes\n\n**Payment options:**\n\n* **Credit Card:** Yes\n* **Debit Card:** Yes\n* **Cash Only:** No\n* **NFC:** Yes\n\n**Distance & Travel Time:**\n\n* 384.6 kilometers\n* 4.2 hours",
"placeId": "places/ChIJOTRDf_qwt4kR2kV_WYUf63w"
}
},
...
],
"groundingSupports": [
{
"segment": {
"endIndex": 79,
"text": "\"The Italian Place\" in Alexandria, VA, is good for children and offers takeout."
},
"groundingChunkIndices": [
0
]
},
{
"segment": {
"startIndex": 80,
"endIndex": 130,
"text": "It has a rating of 4.2 stars based on 411 reviews."
},
"groundingChunkIndices": [
0
]
}
],
"googleMapsWidgetContextToken": "widgetcontent/..."
}
}
],
...
}
(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, che viene restituito nella risposta dell'API Vertex AI e può essere utilizzato per visualizzare i contenuti visivi.
Il widget contestuale svolge diverse funzioni a seconda dello scenario:
Visualizza contenuti soggettivi generati dagli utenti (UGC) nello scenario in cui i prompt di Google Maps vengono utilizzati 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:
HTML
Crea un widget contestuale.
<body> <gmp-place-contextual id="widget"></gmp-place-contextual> </body>In qualsiasi risposta basata su Google Maps, è presente un
googleMapsWidgetContextTokencorrispondente utilizzato per il rendering del widget contestuale e 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; }(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>- Layout compatto:
(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>- Mappa della roadmap 2D:
JavaScript
Crea un widget contestuale.
async function createWidget(contextToken) { await google.maps.importLibrary('places'); let widgetContainer = document.querySelector('#wc'); // a div that contains the widget const placeContextualElement = new google.maps.places.PlaceContextualElement({ contextToken }); widgetContainer.appendChild(placeContextualElement); }In qualsiasi risposta basata su Google Maps, è presente un
googleMapsWidgetContextTokencorrispondente utilizzato per il rendering del widget contestuale e posizionato in prossimità della risposta generata.Per aggiornare il token di contesto, imposta la proprietà
widget.contextToken."googleMapsWidgetContextToken": "widgetcontent/AcBXPQdpWQWbap9H-OH8sEKmOXxmEKAYvff0tvthhneMQC3VrqWCjpnPBl4-Id98FGiA_S_t8aeAeJj0T6JkWFX56Bil8oBSR0W8JH3C_RSYLbTjxKdpxc9yNn6JcZTtolIRZon9xi6WpNGuSyjcIxWu2S0hwpasNOpUlWrG1RxVCB4WD1fsz_pwR236mG36lMxevXTQ_JnfdYNuQwQ4Lc3vn...<snip>... Ts5VJE_b3IC5eE_6wez0nh61r7foTUZpP7BXMwxR-7Wyfcj6x1v6mIWsFGr1o0p_HSAMNqWPg-aFVnkPLhAkOR6MaNZOfezTva-gxHlu7z_haFvYxcUE1qfNVQ",function updateWidget(contextToken) { widget.contextToken = contextToken; }(Facoltativo) Specifica il layout dell'elenco. I valori validi includono:
- Layout compatto:
layout: google.maps.places.PlaceContextualListLayout.COMPACT - Layout verticale:
layout: google.maps.places.PlaceContextualListLayout.VERTICAL
Questo esempio di codice mostra come modificare il layout elenco in un layout compatto.
const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({ layout: google.maps.places.PlaceContextualListLayout.COMPACT }); widget.appendChild(widgetConfig);- Layout compatto:
(Facoltativo) Cambia la modalità mappa. I valori validi includono:
- Mappa della roadmap 2D:
mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP - Mappa ibrida 3D:
mapMode: google.maps.places.PlaceContextualListMapMode.HYBRID - Nessuna mappa:
mapMode: google.maps.places.PlaceContextualListMapMode.NONE
Questo esempio di codice mostra come passare alla modalità mappa 2D.
const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({ mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP }); widget.appendChild(widgetConfig);- Mappa della roadmap 2D:
Requisiti di attribuzione della fonte
Quando presenti contenuti generati da Vertex AI che fanno riferimento direttamente a informazioni rese disponibili tramite il grounding con Google Maps, devi specificare le fonti di Google Maps utilizzate per supportare la risposta.
Questa immagine mostra le fonti di Google Maps utilizzate per supportare la risposta del modello.
Informare l'utente finale dell'utilizzo delle fonti di grounding
Devi informare i tuoi utenti di quanto segue:
- Le fonti di base utilizzate per supportare i contenuti generati dal modello LLM nelle immediate vicinanze dei contenuti.
- Le fonti di base devono essere visualizzabili con una sola interazione dell'utente.
Visualizzare gli URL di origine di Google Maps
Le fonti di Google Maps vengono restituite all'interno di groundingMetadata entro
groundingChunks e groundingSupports. Le fonti di Google Maps vengono restituite
sia per i luoghi sia per i contenuti di risposta dei luoghi di supporto, come le recensioni degli utenti, che
sono stati utilizzati per generare la risposta.
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}",
"text": "{Maps content that was sent to the model for this place}"
"placeId": "{Place ID}",
"placeAnswerSources":
{
"review": "",
"authorAttribution": {
"displayName": "",
"photoUri": ""
},
"flagContentUri": "",
"googleMapsUri": ""
},
},
"flagContentUri": ""
}
}
}
],
Per ogni fonte a cui fa riferimento il LLM, deve essere generata un'anteprima del link che soddisfi i seguenti requisiti:
- Attribuisci ogni fonte a Google Maps seguendo le linee guida per l'attribuzione di testo.
- Visualizza il titolo della pagina Open Graph (
og:title) o il titolo con il formato:[Place Name] - Google Maps - Vai al materiale di origine utilizzando l'URL di origine.
Se in groundingChunks sono presenti origini di risposte sui luoghi, devi eseguire le seguenti operazioni:
- Visualizza i link alle recensioni all'interno di
grounding_chunks.maps.placeAnswerSources.reviewSnippets.googleMapsUri. - Visualizza il titolo Open Graph o un titolo con il formato:
Google Review of [Place Name] by [Author Name].Place Namesi trova ingrounding_chunks.maps.titleeAuthor Namesi trova ingrounding_chunks.maps.placeAnswerSources.reviewSnippets.authorAttribution.displayName. (Facoltativo) Migliora l'anteprima del link con contenuti aggiuntivi, ad esempio:
- Favicon di Google Maps (
<link rel="icon" href="https://www.google.com/favicon.ico">) inserito prima del testo di attribuzione di Google Maps. - Descrizione (
og:description) - Foto (
og:image)
- Favicon di Google Maps (
Queste immagini mostrano i requisiti minimi, ovvero la visualizzazione dei link di Place.
Puoi comprimere la visualizzazione delle fonti.
Questa immagine mostra la foto del luogo, che è un link facoltativo per visualizzare l'anteprima degli attributi delle fonti.
Territori vietati
Google Maps limita determinati contenuti e attività per mantenere una piattaforma sicura e affidabile. Per un elenco dei territori vietati, consulta Territori vietati di Google Maps Platform.
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. Se si verifica un problema con i contenuti della risposta del luogo fornita nei metadati, puoi segnalarlo a Google utilizzando un link nel campo flagContentUri all'interno dell'oggetto PlaceAnswerSources nella risposta dell'API.
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.
Passaggi successivi
- Per scoprire di più su come basare i modelli Gemini sui tuoi dati, consulta 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.