Fundamentos con Google Maps en Vertex AI

En esta página, se describe cómo la fundamentación con Google Maps en Vertex AI puede ayudarte a mejorar tus aplicaciones de IA generativa proporcionando contexto geoespacial.

Descripción general

La fundamentación con Google Maps en Vertex AI es un servicio en versión preliminar que conecta los modelos de Gemini con los datos geoespaciales de Google Maps. Google Maps tiene acceso a información sobre millones de ubicaciones, incluidas empresas, lugares emblemáticos y puntos de interés. Estos datos te brindan acceso a información sobre más de 250 millones de lugares que se pueden usar para fundamentar las respuestas de tu modelo, lo que permite que tus aplicaciones y agentes de IA proporcionen datos locales y contexto geoespacial.

Usos de la fundamentación con Google Maps

Puedes usar la fundamentación con Google Maps para diversas aplicaciones, como las siguientes:

  • Agentes basados en chat
  • Es un resumen de la información del lugar.
  • Traducción de contenido
  • Asistentes conversacionales que pueden responder preguntas sobre lugares cercanos, como "¿Hay parques cerca?".
  • Descripciones personalizadas de lugares, como "¿Me puedes contar más sobre los parques y los restaurantes aptos para familias que se encuentran a una distancia a pie?"

Esto puede ser útil para industrias como la inmobiliaria, la de viajes, la de movilidad y las aplicaciones sociales.

Para obtener asistencia técnica con la fundamentación con Google Maps, envía un correo electrónico a maps-grounding-feedback-external@google.com.

Modelos compatibles

En esta sección, se enumeran los modelos que admiten la fundamentación con Google Maps.

Para obtener más información sobre los modelos de Gemini, consulta Modelos de Gemini.

Usa la fundamentación con Google Maps para fundamentar las respuestas de tu modelo

En esta muestra de código, se indica cómo usar la fundamentación con Google Maps para fundamentar las respuestas de tu modelo.

Los resultados de la búsqueda se pueden personalizar para una ubicación geográfica específica con las coordenadas de latitud y longitud. Para obtener más información, consulta la API de Grounding.

Console

Para usar Grounding with Google Maps con Vertex AI Studio, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Vertex AI Studio.

    Ir a Vertex AI Studio

  2. Haz clic en la pestaña Freeform.
  3. En el panel lateral, haz clic en el botón de activación Fundamentar las respuestas del modelo.
  4. Haz clic en Personalizar y establece Google Maps como la fuente.
  5. Ingresa tu instrucción en el cuadro de texto y haz clic en Enviar.

Tus respuestas a las instrucciones ahora se basan en Google Maps.

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: La región para procesar la solicitud.
  • PROJECT_ID: El ID del proyecto.
  • MODEL_ID: El ID del modelo multimodal.
  • TEXT: Las instrucciones de texto que se incluirán en el mensaje.
  • LATITUDE: Es la latitud de la ubicación. Por ejemplo, una latitud de 37.7749 representa San Francisco. Puedes obtener las coordenadas de latitud y longitud con servicios como Google Maps o con otras herramientas de geocodificación.
  • LONGITUDE: Es la longitud de la ubicación. Por ejemplo, una longitud de -122.4194 representa San Francisco.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Opcional: Widget contextual de Google Maps

El widget contextual es una Oferta previa a la DG de Google Maps que es un contenedor visual que se usa para complementar o respaldar otro contenido de Google Maps. El widget contextual de Google Maps te permite integrar Grounding con Google Maps en tus aplicaciones para crear una experiencia de chat conversacional potenciada por un LLM. El widget contextual se renderiza con el token de contexto, googleMapsWidgetContextToken, que se devuelve en la respuesta de la API de Vertex AI y se puede usar para renderizar contenido visual.

El widget contextual cumple diferentes funciones según la situación:

  • Muestra contenido generado por el usuario (CGU) subjetivo en la situación en la que se usan instrucciones de Google Maps para generar respuestas.

  • Ayuda a enriquecer los resultados con visualizaciones y datos del mapa cuando Vertex AI genera solo una respuesta de texto.

Para obtener más información sobre el widget contextual, consulta Widget de fundamentación de Maps.

Renderiza el widget contextual de Google Maps

Para renderizar y usar el widget contextual de Google Maps, usa la versión alfa de la API de Google Maps JavaScript en la página que muestra el widget. Para obtener más información, consulta Carga la API de Maps JavaScript.

En las siguientes muestras de código, se muestra cómo usar un widget contextual:

HTML

  1. Crea un widget contextual.

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

  2. En cualquier respuesta basada en Google Maps, hay un googleMapsWidgetContextToken correspondiente que se usa para renderizar el widget contextual y se coloca cerca de la respuesta generada.

    Para actualizar el token de contexto, configura 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. Opcional: Especifica el diseño de la lista. Los valores válidos incluyen lo siguiente:

    • Diseño compacto: <gmp-place-contextual-list-config layout="compact">
    • Diseño vertical: <gmp-place-contextual-list-config layout="vertical">

    En esta muestra de código, se muestra cómo cambiar el diseño de la lista a un diseño compacto.

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

  4. Opcional: Cambia el modo del mapa. Los valores válidos incluyen lo siguiente:

    • Mapa de ruta en 2D: map-mode="roadmap"
    • Mapa híbrido en 3D: map-mode="hybrid"
    • Sin mapa: map-mode="none"

    En este muestra de código, se muestra cómo cambiar el modo del mapa a un mapa en 2D.

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

JavaScript

  1. Crea un widget contextual.

    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. En cualquier respuesta basada en Google Maps, hay un googleMapsWidgetContextToken correspondiente que se usa para renderizar el widget contextual y se coloca cerca de la respuesta generada.

    Para actualizar el token de contexto, configura la propiedad 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. Opcional: Especifica el diseño de la lista. Los valores válidos incluyen lo siguiente:

    • Diseño compacto: layout: google.maps.places.PlaceContextualListLayout.COMPACT
    • Diseño vertical: layout: google.maps.places.PlaceContextualListLayout.VERTICAL

    En esta muestra de código, se muestra cómo cambiar el diseño de la lista a un diseño compacto.

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

  4. Opcional: Cambia el modo del mapa. Los valores válidos incluyen lo siguiente:

    • Mapa de ruta en 2D: mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP
    • Mapa híbrido en 3D: mapMode: google.maps.places.PlaceContextualListMapMode.HYBRID
    • Sin mapa: mapMode: google.maps.places.PlaceContextualListMapMode.NONE

    En este muestra de código, se muestra cómo cambiar el modo del mapa a un mapa en 2D.

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

Requisitos de atribución de la fuente

Cuando presentes contenido generado por Vertex AI que haga referencia directamente a información disponible a través de la fundamentación con Google Maps, debes especificar las fuentes de Google Maps que se usaron para respaldar la respuesta.

En esta imagen, se muestran las fuentes de Google Maps que se usaron para respaldar la respuesta del modelo.

Instrucción con respuesta que muestra las fuentes

Informa al usuario final sobre el uso de fuentes de fundamentación

Debes informar a los usuarios sobre lo siguiente:

  • Son las fuentes de fundamentación que se usaron para respaldar el contenido generado por el LLM cerca del contenido.
  • Las fuentes de fundamentación deben poder verse en una sola interacción del usuario.

Mostrar URLs de origen de Google Maps

Las fuentes de Google Maps se muestran en groundingMetadata dentro de groundingChunks y groundingSupports. Las fuentes de Google Maps se muestran tanto para los lugares como para el contenido de las respuestas de lugares, como las opiniones de los usuarios, que se usaron para ayudar a generar la respuesta.

En este muestra de código, se muestran una fuente de lugar y una fuente de respuesta de lugar en la respuesta:

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

Para cada fuente a la que hace referencia el LLM, se debe generar una vista previa del vínculo según los siguientes requisitos:

  • Atribuye cada fuente a Google Maps según los lineamientos de atribución de texto.
  • Muestra el título de la página de Open Graph (og:title) o el título con el formato
    .

    [Place Name] - Google Maps

  • Navega al material de origen con la URL de origen.

Si hay fuentes de respuestas sobre lugares en groundingChunks, debes hacer lo siguiente:

  • Renderiza los vínculos de revisión dentro de grounding_chunks.maps.placeAnswerSources.reviewSnippets.googleMapsUri.
  • Muestra el título de Open Graph o un título con el formato:

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

    Place Name se encuentra en grounding_chunks.maps.title y Author Name se encuentra en grounding_chunks.maps.placeAnswerSources.reviewSnippets.authorAttribution.displayName.

  • Opcional: Mejora la vista previa del vínculo con contenido adicional, como el siguiente:

    • Ícono de página de Google Maps (<link rel="icon" href="https://www.google.com/favicon.ico">) insertado antes del texto de atribución de Google Maps.
    • Descripción (og:description)
    • Foto (og:image)

Estas imágenes muestran los requisitos mínimos, que consisten en mostrar los vínculos de la página de Places.

Instrucción con respuesta que muestra las fuentes

Puedes contraer la vista de las fuentes.

Instrucción con respuesta y fuentes contraídas

En esta imagen, se muestra la foto del lugar, que es un vínculo opcional para obtener una vista previa de los atributos de las fuentes.

Instrucción con respuesta y fuentes

Territorios prohibidos

Google Maps restringe cierto contenido y actividades para mantener una plataforma segura y confiable. Para obtener una lista de los territorios prohibidos, consulta Territorios Prohibidos de Google Maps Platform.

Propiedades del lugar

En esta sección, se enumeran las propiedades de lugares que se usan para describir ubicaciones y que utiliza Grounding con Google Maps para generar respuestas. Estas propiedades se usan para determinar los tipos de preguntas que puede responder Grounding con Google Maps.

Ejemplo de propiedades de lugar

En esta lista, se proporciona una muestra alfabética de las propiedades sobre lugares que tu modelo puede usar para generar respuestas.

  • Dirección
  • Retiros en la puerta
  • Tarjeta de débito
  • Distancia
  • Estacionamiento gratuito
  • Música en vivo
  • Menú para niños
  • Horario de atención
  • Opciones de pago (como efectivo o tarjeta de crédito)
  • Respuesta sobre un lugar
  • Se permiten mascotas
  • Ofrece cervezas
  • Ofrece comida vegetariana
  • Con acceso para silla de ruedas
  • Wi-Fi

Las respuestas de lugares son una respuesta de Grounding con Google Maps basada en la información derivada de las opiniones de los usuarios. Si hay un problema con el contenido de la respuesta de Lugar proporcionada en los metadatos, puedes informarlo a Google a través de un vínculo en el campo flagContentUri dentro del objeto PlaceAnswerSources en la respuesta de la API.

Ejemplos de uso de las propiedades de lugar

En los siguientes ejemplos, se usan propiedades de lugar en preguntas sobre diferentes tipos de lugares. La fundamentación con Google Maps usa las propiedades para comprender tu intención y, luego, proporciona respuestas pertinentes basadas en los datos asociados con los lugares en Google Maps.

  • Planificar una cena familiar: Podrías preguntar: ¿"The Italian Place" es un buen lugar para niños y ofrece comida para llevar? ¿Cuál es su calificación?

    Las respuestas a estas preguntas te ayudan a determinar si un restaurante es adecuado para una familia y si ofrece un servicio conveniente.

  • Verificar la accesibilidad para un amigo: Podrías preguntar: Necesito un restaurante que tenga una entrada accesible para personas en silla de ruedas.

    Una respuesta a esta instrucción puede ayudarte a determinar si la ubicación satisface necesidades de accesibilidad específicas.

  • Encontrar un lugar para comer un bocadillo a altas horas de la noche: Podrías preguntar: ¿"Burger Joint" está abierto ahora? ¿Sirven cena? ¿Cuál es el horario de atención del viernes?

    Las respuestas a estas preguntas te ayudan a encontrar un establecimiento abierto que sirva una comida específica en un momento determinado.

  • Reunirse con un cliente para tomar un café: Podrías preguntar: ¿"Café Central" tiene Wi-Fi? ¿Sirven café? ¿Cuál es su nivel de precios y si aceptan tarjetas de crédito?

    Las respuestas a estas preguntas te ayudan a evaluar la idoneidad de una cafetería para una reunión de negocios en función de los servicios, las ofertas y las opciones de pago.

¿Qué sigue?

  • Para obtener más información sobre cómo fundamentar los modelos de Gemini con tus datos, consulta Fundamentación con tus datos.
  • Para obtener más información sobre las prácticas recomendadas de IA responsable y los filtros de seguridad de Vertex AI, consulta IA responsable.