Ancrage avec Google Maps dans Vertex AI

Cette page explique comment l'ancrage avec Google Maps et Vertex AI peut vous aider à améliorer vos applications d'IA générative en fournissant un contexte géospatial.

Présentation

L'ancrage avec Google Maps et Vertex AI est un service qui connecte les modèles Gemini aux données géospatiales de Google Maps. Google Maps a accès à des informations sur des millions de lieux, y compris des établissements, des points de repère et des points d'intérêt. Ces données vous donnent accès à des informations sur plus de 250 millions de lieux qui peuvent être utilisées pour ancrer les réponses de votre modèle, ce qui permet à vos applications et agents d'IA de fournir des données locales et un contexte géospatial.

Vous pouvez également activer l'ancrage simultané avec Google Maps, la recherche Google et vos sources de données.

Utilisations de l'ancrage avec Google Maps

Vous pouvez utiliser Grounding avec Google Maps pour diverses applications, par exemple :

  • Assistants conversationnels capables de répondre à des questions sur les lieux à proximité, comme "Où puis-je trouver un expresso italien à proximité ?"
  • Des descriptions personnalisées et des informations de la communauté, par exemple "Peux-tu me donner plus d'informations sur les restaurants adaptés aux familles qui se trouvent à distance de marche ?"
  • Résumés des zones autour de lieux spécifiques, comme une borne de recharge de véhicules électriques ou un hôtel.

Cela peut être utile pour les cas d'utilisation dans les applications immobilières, de voyage, de mobilité et de réseaux sociaux.

Modèles compatibles

Cette section liste les modèles compatibles avec l'ancrage avec Google Maps.

Pour en savoir plus sur les modèles Gemini, consultez Modèles Gemini.

Utiliser l'ancrage avec Google Maps pour ancrer les réponses de votre modèle

Cet exemple de code montre comment utiliser l'ancrage avec Google Maps pour ancrer les réponses de votre modèle.

Les résultats de recherche peuvent être personnalisés pour une zone géographique spécifique à l'aide des coordonnées de latitude et de longitude. Pour en savoir plus, consultez l'API Ancrage.

Console

Pour utiliser l'ancrage avec Google Maps avec Vertex AI, procédez comme suit :

  1. Dans la console Google Cloud , accédez à la page Vertex AI Studio.

    Accéder à Vertex AI Studio

  2. Dans la section Outils, cliquez sur Ancrage : Google. Un volet de configuration s'affiche.

  3. Pour utiliser Google Maps, cliquez sur le bouton bascule Google Maps.

  4. Cliquez sur Appliquer.

  5. Saisissez votre requête dans le champ, puis cliquez sur Envoyer. Vos réponses aux requêtes sont ancrées sur Google Maps.

Python

Installer

pip install --upgrade google-genai

Pour en savoir plus, lisez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Gen AI avec 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

Avant d'utiliser des données de requête, effectuez les remplacements suivants :

  • LOCATION : région dans laquelle traiter la requête. Pour utiliser le point de terminaison global, excluez l'emplacement du nom du point de terminaison et configurez l'emplacement de la ressource sur "global".
  • PROJECT_ID : l'ID de votre projet.
  • MODEL_ID : l'ID du modèle multimodal.
  • PROMPT : requête à envoyer au modèle.
  • LATITUDE : latitude de l'emplacement. Par exemple, une latitude de 37.7749 représente San Francisco. Vous pouvez obtenir les coordonnées de latitude et de longitude à l'aide de services tels que Google Maps ou d'autres outils de géocodage.
  • LONGITUDE : longitude de l'emplacement. Par exemple, une longitude de -122.4194 représente San Francisco.
  • ENABLE_WIDGET : indique s'il faut renvoyer un jeton et activer le widget Google Maps (la valeur par défaut est false).

Méthode HTTP et URL : 

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

Vous devriez recevoir une réponse JSON de ce type :

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

Propriétés du lieu

Cette section liste les propriétés de lieu utilisées pour décrire les lieux et utilisées par l'ancrage avec Google Maps pour générer des réponses. Ces propriétés permettent de déterminer les types de questions auxquelles l'ancrage avec Google Maps peut répondre.

Exemples de propriétés de lieu

Cette liste fournit un échantillon alphabétique de propriétés sur les lieux que votre modèle peut utiliser pour générer des réponses.

  • Adresse
  • Drive disponible
  • Carte de débit
  • Distance
  • Parking gratuit
  • Concerts
  • Menu pour enfants
  • Horaires d'ouverture
  • Options de paiement (espèces ou carte de crédit, par exemple)
  • Réponse sur le lieu
  • Animaux acceptés
  • Bière
  • Sert des plats végétariens
  • Accessible en fauteuil roulant
  • Wi-Fi

Les réponses sur les lieux sont des réponses fournies par l'ancrage avec Google Maps, basées sur des informations issues des avis des utilisateurs.

Exemples d'utilisation des propriétés de lieu

Les exemples suivants utilisent des propriétés de lieu dans des questions sur différents types de lieux. L'ancrage avec Google Maps utilise les propriétés pour comprendre votre intention, puis fournit des réponses pertinentes en fonction des données associées aux lieux dans Google Maps.

  • Organiser un dîner en famille : vous pouvez demander "Est-ce que "The Italian Place" est adapté aux enfants et propose des plats à emporter ?" Quelle est sa note ?

    Les réponses à ces questions vous aident à déterminer si un restaurant convient à une famille et s'il propose un service pratique.

  • Vérifier l'accessibilité pour un ami : vous pouvez demander J'ai besoin d'un restaurant avec une entrée accessible en fauteuil roulant.

    Une réponse à cette requête peut vous aider à déterminer si le lieu répond à des besoins spécifiques en matière d'accessibilité.

  • Trouver un endroit pour une collation tardive : vous pouvez demander "Est-ce que le restaurant "Burger Joint" est ouvert maintenant ?" Sert-il à dîner ? Quels sont leurs horaires d'ouverture pour vendredi ?

    Les réponses à ces questions vous aident à trouver un établissement ouvert qui sert un repas spécifique à une heure précise.

  • Prendre un café avec un client : vous pouvez demander Le "Café Central" a-t-il le Wi-Fi ? Propose-t-il du café ? Quel est leur niveau de prix et acceptent-ils les cartes de crédit ?

    Les réponses à ces questions vous aident à évaluer si un café est adapté à une réunion d'affaires en fonction des équipements, des offres et des options de paiement.

Les informations fournies dans les résultats de Google Maps concernant les routes fermées peuvent différer des conditions réelles de la route.

Comprendre votre réponse

Les sources Google Maps sont renvoyées dans groundingMetadata dans groundingChunks. Les sources sont renvoyées pour les lieux et les avis des utilisateurs qui ont contribué à générer le résultat ancré Google Maps.

Cet exemple de code montre une source de lieu et une source de réponse de lieu dans la réponse :

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

Conditions d'utilisation du service

Cette section décrit les conditions d'utilisation de Grounding avec Google Maps.

Informer l'utilisateur sur l'utilisation des sources Google Maps

Pour chaque résultat ancré Google Maps, vous recevrez des sources dans groundingChunks qui étayent chaque réponse. Les métadonnées suivantes sont également renvoyées :

  • URI source
  • titre
  • ID

Lorsque vous présentez des résultats d'ancrage avec Google Maps dans Vertex AI, vous devez spécifier les sources Google Maps associées et informer vos utilisateurs des points suivants :

  • Les sources Google Maps doivent suivre immédiatement le contenu généré qu'elles soutiennent. Ce contenu généré est également appelé résultat ancré Google Maps.
  • Les sources Google Maps doivent être visibles en une seule interaction utilisateur.

Pour chaque source dans groundingChunks et dans grounding_chunks.maps.placeAnswerSources.reviewSnippets, un aperçu du lien doit être généré en respectant les exigences suivantes :

Ces images montrent les exigences minimales pour afficher les sources et les liens Google Maps.

Requête avec réponse affichant les sources

Vous pouvez réduire l'affichage des sources.

Requête avec réponse et sources réduites

Facultatif : Améliorez l'aperçu du lien avec du contenu supplémentaire, par exemple :

  • Un favicon Google Maps est inséré avant l'attribution de texte Google Maps.
  • Photo provenant de l'URL source (og:image).

Pour en savoir plus sur certains de nos fournisseurs de données Google Maps et sur leurs conditions de licence, consultez les mentions légales de Google Maps et Google Earth.

Consignes relatives à l'attribution de texte Google Maps

Lorsque vous attribuez des sources à Google Maps dans un texte, suivez ces consignes :

  • Ne modifiez en aucun cas le texte Google Maps :
    • Ne modifiez pas la casse de Google Maps.
    • N'insérez pas Google Maps sur plusieurs lignes.
    • Ne localisez pas Google Maps dans une autre langue.
    • Empêchez les navigateurs de traduire Google Maps en utilisant l'attribut HTML translate="no".
  • Mettez en forme le texte Google Maps comme décrit dans le tableau suivant :
Propriété Style
Famille de polices Roboto. Le chargement de la police est facultatif.
Famille de polices de remplacement Toute police de corps sans serif déjà utilisée dans votre produit ou "Sans-Serif" pour appeler la police système par défaut
Style de police Normal
Épaisseur de la police 400
Couleur de la police Blanc, noir (#1F1F1F) ou gris (#5E5E5E). Maintenez un contraste accessible (4.5:1) par rapport à l'arrière-plan.
Taille de police Taille de police minimale : 12 sp
Taille de police maximale : 16 sp
Pour en savoir plus sur les sp, consultez la section "Unités de taille de police" sur le site Web Material Design.
L'espacement entre les lettres Normal

Exemple de CSS

Le code CSS suivant affiche Google Maps avec le style typographique et la couleur appropriés sur un arrière-plan clair ou blanc.

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

Jeton de contexte, ID de lieu et ID d'avis

Les données Google Maps incluent le jeton de contexte, l'ID de lieu et l'ID d'avis. Vous pouvez mettre en cache, stocker et exporter les données de réponse suivantes :

  • googleMapsWidgetContextToken
  • placeId
  • reviewId

Les restrictions de mise en cache des conditions d'ancrage avec Google Maps ne s'appliquent pas.

Territoire interdit

L'ancrage avec Google Maps est soumis à des restrictions pour certains contenus et activités afin de maintenir une plate-forme sûre et fiable. Le Client s'engage à ne pas distribuer ni commercialiser une Application du client qui propose l'ancrage avec Google Maps dans un Territoire interdit. Les territoires actuellement interdits sont les suivants :

  • Chine
  • Crimée
  • Cuba
  • République populaire de Donetsk
  • Iran
  • République populaire de Lougansk
  • Corée du Nord
  • Syrie
  • Viêt Nam

Cette liste peut être mise à jour de temps en temps.

(Facultatif) Widget contextuel Google Maps

Le widget contextuel est une offre Google Maps en prédisponibilité générale. Il s'agit d'un conteneur visuel utilisé pour prendre en charge ou compléter d'autres contenus Google Maps. Le widget contextuel Google Maps vous permet d'intégrer l'ancrage avec Google Maps dans vos applications pour créer une expérience de chat conversationnelle optimisée par les LLM. Le widget contextuel est affiché à l'aide du jeton de contexte googleMapsWidgetContextToken, qui est renvoyé dans la réponse de l'API Vertex AI et peut être utilisé pour afficher du contenu visuel.

Le widget contextuel remplit différentes fonctions selon votre scénario :

  • Il affiche les avis et les photos des utilisateurs, qui sont des contenus générés par les utilisateurs (CGU), dans le scénario où l'invite Google Maps est utilisée pour générer des réponses.

  • Il permet d'enrichir les résultats avec des visualisations de cartes et des données lorsque Vertex AI ne génère qu'une réponse textuelle.

Pour en savoir plus sur le widget contextuel, consultez Widget d'ancrage Maps.

Afficher le widget contextuel Google Maps

Pour afficher et utiliser le widget contextuel Google Maps, utilisez la version alpha de l'API Maps JavaScript sur la page qui affiche le widget. Pour en savoir plus, consultez Charger l'API Maps JavaScript.

Les exemples de code suivants montrent comment utiliser un widget contextuel :

  1. Créez un widget contextuel.

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

  2. Dans toute réponse ancrée dans Google Maps, un googleMapsWidgetContextToken correspondant est utilisé pour afficher le widget contextuel et placé à proximité de la réponse générée.

    Pour mettre à jour le jeton de contexte, définissez 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. Facultatif : Spécifiez la mise en page de la liste. Les valeurs valides sont les suivantes:

    • Mise en page compacte : <gmp-place-contextual-list-config layout="compact">
    • Mise en page verticale : <gmp-place-contextual-list-config layout="vertical">

    Cet exemple de code montre comment modifier la mise en page de la liste pour la rendre compacte.

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

  4. Facultatif : Modifiez le mode Plan. Les valeurs valides sont les suivantes:

    • Carte de route 2D : map-mode="roadmap"
    • Carte hybride 3D : map-mode="hybrid"
    • Aucune carte : map-mode="none"

    Cet exemple de code montre comment passer au mode Plan 2D.

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

Étapes suivantes

  • Pour savoir comment ancrer des modèles Gemini sur vos données, consultez Ancrage avec vos données.
  • Pour en savoir plus sur les bonnes pratiques d'IA responsable et les filtres de sécurité de Vertex AI, consultez IA responsable.