Ancrage avec Google Maps dans Vertex AI

Cette page explique comment l'ancrage avec Google Maps dans 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 dans Vertex AI est un service en aperçu 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 monuments 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.

Utilisations de l'ancrage avec Google Maps

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

  • Agents basés sur le chat.
  • Synthèse des informations sur un lieu.
  • Traduction de contenus
  • Assistants conversationnels capables de répondre à des questions sur les lieux à proximité, comme "Y a-t-il des parcs à proximité ?".
  • Des descriptions personnalisées de lieux, par exemple "Pouvez-vous m'en dire plus sur les parcs et les restaurants adaptés aux familles qui se trouvent à distance de marche ?"

Cela peut être utile pour des secteurs tels que l'immobilier, les voyages, la mobilité et les applications sociales.

Pour obtenir de l'aide technique concernant l'ancrage avec Google Maps, envoyez un e-mail à maps-grounding-feedback-external@google.com.

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 Studio, procédez comme suit :

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

    Accéder à Vertex AI Studio

  2. Cliquez sur l'onglet Forme libre.
  3. Dans le panneau latéral, cliquez sur le bouton d'activation Ancrer des réponses de modèle.
  4. Cliquez sur Personnaliser et définissez Google Maps comme source.
  5. Saisissez votre requête dans la zone de texte et cliquez sur Envoyer.

Vos réponses aux requêtes sont ancrées sur Google Maps.

REST

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

  • LOCATION : région dans laquelle traiter la requête.
  • PROJECT_ID : l'ID de votre projet.
  • MODEL_ID : l'ID du modèle multimodal.
  • TEXT : instructions textuelles à inclure dans la requête.
  • 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.

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": "TEXT"
    }]
  }],
  "tools": [{
    "googleMaps": {}
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      }
    }
  },
  "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",
              "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/..."
      }
    }
  ],
  ...
}

(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 à vos applications pour créer une expérience de chat conversationnelle basée sur un 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 du contenu subjectif généré 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 :

HTML

  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>

JavaScript

  1. Créez un widget contextuel.

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

  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 la propriété 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;
  }

  3. Facultatif : Spécifiez la mise en page de la liste. Les valeurs valides sont les suivantes:

    • Mise en page compacte : layout: google.maps.places.PlaceContextualListLayout.COMPACT
    • Mise en page verticale : layout: google.maps.places.PlaceContextualListLayout.VERTICAL

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

      const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
    layout: google.maps.places.PlaceContextualListLayout.COMPACT
  });
  widget.appendChild(widgetConfig);

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

    • Carte de route 2D : mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP
    • Carte hybride 3D : mapMode: google.maps.places.PlaceContextualListMapMode.HYBRID
    • Aucune carte : mapMode: google.maps.places.PlaceContextualListMapMode.NONE

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

      const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
    mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP
  });
  widget.appendChild(widgetConfig);

Exigences concernant l'attribution de la source

Lorsque vous présentez du contenu généré par Vertex AI qui fait directement référence à des informations mises à disposition à l'aide de l'ancrage avec Google Maps, vous devez spécifier les sources Google Maps qui ont été utilisées pour étayer la réponse.

Cette image montre les sources Google Maps qui ont été utilisées pour étayer la réponse du modèle.

Requête avec réponse affichant les sources

Informer l'utilisateur final de l'utilisation des sources d'ancrage

Vous devez informer vos utilisateurs des points suivants :

  • Les sources d'ancrage utilisées pour étayer le contenu généré par le LLM à proximité du contenu.
  • Les sources d'ancrage doivent être visibles en une seule interaction utilisateur.

Afficher les URL sources Google Maps

Les sources Google Maps sont renvoyées dans groundingMetadata dans groundingChunks et groundingSupports. Les sources Google Maps sont renvoyées à la fois pour les lieux et pour le contenu de réponse associé (par exemple, les avis des utilisateurs) qui ont été utilisés pour générer la réponse.

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}",
                "text": "{Maps content that was sent to the model for this place}"
                "placeId": "{Place ID}",
                "placeAnswerSources":
                                  {
                    "review": "",
                    "authorAttribution": {
                      "displayName": "",
                      "photoUri": ""
                    },
                    "flagContentUri": "",
                    "googleMapsUri": ""
                  },
              },
               "flagContentUri": ""
              }
            }
          }
        ],

Pour chaque source référencée par le LLM, un aperçu du lien doit être généré en respectant les exigences suivantes :

  • Attribuez chaque source à Google Maps en suivant les consignes concernant l'attribution de texte.
  • Affichez le titre de la page Open Graph (og:title) ou le titre au format
    .

    [Place Name] - Google Maps

  • Accédez au contenu source à l'aide de l'URL source.

Si des sources de réponses sur le lieu se trouvent dans groundingChunks, vous devez procéder comme suit :

  • Afficher les liens d'examen dans grounding_chunks.maps.placeAnswerSources.reviewSnippets.googleMapsUri.
  • Affichez le titre Open Graph ou un titre au format suivant :
    .

    Google Review of [Place Name] by [Author Name].

    Place Name se trouve dans grounding_chunks.maps.title et Author Name se trouve dans grounding_chunks.maps.placeAnswerSources.reviewSnippets.authorAttribution.displayName.

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

    • Favicon Google Maps (<link rel="icon" href="https://www.google.com/favicon.ico">) inséré avant l'attribution textuelle de Google Maps.
    • Description (og:description)
    • Photo (og:image)

Ces images montrent les exigences minimales, à savoir afficher les liens vers les lieux.

Requête avec réponse affichant les sources

Vous pouvez réduire la vue des sources.

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

Cette image montre la photo du lieu, qui est un lien facultatif permettant de prévisualiser les attributs des sources.

Requête avec réponse et sources

Territoires interdits

Google Maps limite certains contenus et activités pour maintenir une plate-forme sûre et fiable. Pour obtenir la liste des territoires interdits, consultez Territoires interdits sur Google Maps Platform.

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 de l'ancrage avec Google Maps basées sur des informations issues des avis des utilisateurs. Si le contenu de la réponse sur le lieu fournie dans les métadonnées pose problème, vous pouvez le signaler à Google à l'aide d'un lien dans le champ flagContentUri à l'intérieur de l'objet PlaceAnswerSources dans la réponse de l'API.

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.

É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.