Grounding con Google Maps en Vertex AI

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

Información general

Grounding con Google Maps en Vertex AI es un servicio de vista previa que conecta los modelos de Gemini con datos geoespaciales de Google Maps. Google Maps tiene acceso a información sobre millones de ubicaciones, como empresas, monumentos y puntos de interés. Estos datos te dan acceso a información sobre más de 250 millones de sitios 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 Grounding con Google Maps

Puedes usar Grounding con Google Maps para diversas aplicaciones, como las siguientes:

• Agentes basados en chat.
• Resumen de la información de un sitio.
• Traducción de contenido.
• Asistentes conversacionales que pueden responder preguntas sobre sitios cercanos, como "¿Hay algún parque cerca?".
• Descripciones personalizadas de lugares, como "¿Puedes darme más información sobre los parques y los restaurantes familiares que estén a poca distancia?"

Esto puede ser útil en sectores como el inmobiliario, el de viajes, el de movilidad y el de aplicaciones sociales.

Si necesitas asistencia técnica con Grounding con Google Maps, envía un correo a maps-grounding-feedback-external@google.com.

Modelos admitidos

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

• Gemini 2.5 Flash-Lite
• Gemini 2.5 Flash con audio nativo de la API Live (versión preliminar)
• Gemini 2.0 Flash con la API Live (versión preliminar)
• Gemini 2.5 Pro
• Gemini 2.5 Flash
• Gemini 2.0 Flash

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

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

Este código de ejemplo muestra cómo usar Grounding con Google Maps para fundamentar las respuestas de tu modelo.

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

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

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent" | Select-Object -Expand Content

{
  "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 de Acceso Previo a la Disponibilidad General de Google Maps que es un contenedor visual que se usa para complementar o apoyar 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 basada en LLMs. El widget contextual se renderiza mediante 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 tiene diferentes funciones según el caso:

• Muestra contenido subjetivo generado por usuarios (CGU) en el caso de que se usen peticiones de Google Maps para generar respuestas.

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

Para obtener más información sobre el widget contextual, consulta el artículo sobre el widget de información de Maps.

Renderizar el widget contextual de Google Maps

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

En los siguientes ejemplos de código se muestra cómo usar un widget contextual:

Requisitos de atribución de la fuente

Cuando presentes contenido generado por Vertex AI que haga referencia directa a información disponible mediante la fundamentación con Google Maps, debes especificar las fuentes de Google Maps que se han usado para respaldar la respuesta.

Esta imagen muestra las fuentes de Google Maps que se han usado para respaldar la respuesta del modelo.

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

Debes informar a tus usuarios de lo siguiente:

• Las fuentes de información que se han usado para respaldar el contenido generado por el LLM cerca del contenido.
• Las fuentes de información deben poder consultarse en una sola interacción del usuario.

Mostrar las URLs de origen de Google Maps

Las fuentes de Google Maps se devuelven en el groundingMetadata dentro de groundingChunks y groundingSupports. Se devuelven fuentes de Google Maps tanto para los sitios como para el contenido de respuesta de los sitios, como las reseñas de los usuarios, que se han utilizado para generar la respuesta.

En este código de ejemplo se muestra una fuente de Place y una fuente de respuesta de Place 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": ""
              }
            }
          }
        ],

Por cada fuente a la que haga referencia el LLM, se debe generar una vista previa del enlace que cumpla los siguientes requisitos:

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

  [Place Name] - Google Maps

• Ve al material de origen mediante la URL de origen.

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

• Renderiza los enlaces de reseñas en 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 enlace con contenido adicional, como:

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

En estas imágenes se muestran los requisitos mínimos, que son mostrar los enlaces de sitio.

Puede contraer la vista de las fuentes.

En esta imagen se muestra la foto del sitio, que es un enlace opcional para previsualizar los atributos de las fuentes.

Territorios prohibidos

Google Maps restringe determinado contenido y actividades para mantener una plataforma segura y fiable. Para ver una lista de los territorios prohibidos, consulta los territorios prohibidos de Google Maps Platform.

Propiedades del sitio

En esta sección se enumeran las propiedades de los sitios 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 la función de fundamentación con Google Maps.

Propiedades de sitios de ejemplo

En esta lista se ofrece una muestra alfabética de las propiedades de los sitios que puede usar tu modelo para generar respuestas.

• Dirección
• Recogida en tienda sin entrar
• Tarjeta de débito
• Distancia
• Aparcamiento gratuito
• Música en directo
• Menú infantil
• Horario de apertura
• Opciones de pago (como efectivo o tarjeta de crédito)
• Respuesta sobre sitio
• Se admiten mascotas
• Sirve cerveza
• Se sirven comidas vegetarianas
• Accesibilidad para sillas de ruedas
• Wi-Fi

Las respuestas de sitios son respuestas de Grounding con Google Maps basadas en información derivada de las reseñas de los usuarios. Si hay algún problema con el contenido de la respuesta de Lugar proporcionada en los metadatos, puede informarlo a Google mediante un enlace del campo flagContentUri del objeto PlaceAnswerSources en la respuesta de la API.

Ejemplos de uso de propiedades de lugar

En los siguientes ejemplos se usan propiedades de sitios en preguntas sobre diferentes tipos de sitios. La función de grounding con Google Maps usa las propiedades para entender tu intención y, a continuación, proporciona respuestas relevantes basadas en los datos asociados a los sitios de Google Maps.

• Organizar una cena familiar: puedes preguntar ¿Es "The Italian Place" un buen sitio para niños? ¿Ofrecen comida para llevar? ¿Cuál es su valoración?

  Las respuestas a estas preguntas te ayudarán a determinar si un restaurante es adecuado para una familia y si ofrece un servicio cómodo.

• Consultar la accesibilidad para un amigo: puedes preguntar Necesito un restaurante que tenga una entrada accesible para sillas de ruedas.

  Una respuesta a esta petición puede ayudarte a determinar si la ubicación cumple requisitos de accesibilidad específicos.

• Buscar un sitio para tomar un tentempié a altas horas de la noche: puedes preguntar ¿Está abierto ahora "Burger Joint"? ¿Sirven cenas? ¿Cuál es su horario de apertura el viernes?

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

• Quedar con un cliente para tomar un café: puedes preguntar ¿Hay Wi-Fi en el Café Central? ¿Sirven café? ¿Cuál es su nivel de precios y aceptan tarjetas de crédito?

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

Siguientes pasos

• Para obtener más información sobre cómo basar los modelos de Gemini en tus datos, consulta Basar los modelos en 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.