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 de Vertex AI Studio a mejorar tus aplicaciones de IA generativa proporcionando contexto geoespacial.

Información general

Grounding con Google Maps con Vertex AI Studio es un servicio 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 y permitir que tus aplicaciones y agentes de IA proporcionen datos locales y contexto geoespacial.

También puedes habilitar la fundamentación simultánea con Google Maps, la Búsqueda de Google y tus fuentes de datos.

Usos de Grounding con Google Maps

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

• 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 casos prácticos de aplicaciones inmobiliarias, de viajes, de movilidad y sociales.

Modelos admitidos

En esta sección se enumeran los modelos que admiten la función de acoplamiento 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.

Consola

Para usar Grounding con Google Maps en 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. En el panel, despliega Configuración del modelo y haz clic en el interruptor Fundamentación: Google.

3. Selecciona Google Maps.

4. Haz clic en Aplicar.

5. Introduce tu petición en el campo y haz clic en Enviar.

Python

Antes de probar este ejemplo, sigue las Python instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local.

Las respuestas de la petición se basan en Google Maps.

    # 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 to enable Maps widget
                ))
            ],
            tool_config=types.ToolConfig(
                retrieval_config = types.RetrievalConfig(
                    lat_lng = types.LatLng( # Pass 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

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

• LOCATION: la región en la que se procesará la solicitud.
• PROJECT_ID: tu ID de proyecto.
• MODEL_ID: ID del modelo multimodal.
• TEXT: las instrucciones de texto que se deben incluir en la petición.
• LATITUDE: latitud de la ubicación. Por ejemplo, la latitud 37.7749 representa San Francisco. Puedes obtener las coordenadas de latitud y longitud mediante servicios como Google Maps u otras herramientas de geocodificación.
• LONGITUDE: longitud de la ubicación. Por ejemplo, la longitud -122.4194 representa San Francisco.
• ENABLE_WIDGET: indica si se debe devolver un token y habilitar el widget de Google Maps (el valor predeterminado es false).

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": {
      "enableWidget": ENABLE_WIDGET
    }
  }],
  "toolConfig": {
    "retrievalConfig": {
      "latLng": {
        "latitude": LATITUDE,
        "longitude": LONGITUDE
      },
      "languageCode": "en_US"
    }
  },
  "model": "projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID"
}

Para enviar tu solicitud, despliega una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: En el siguiente comando se presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login , o bien usando Cloud Shell, que inicia sesión automáticamente en la CLI de gcloud . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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"

PowerShell (Windows)

Nota: El siguiente comando presupone que has iniciado sesión en la CLI de gcloud con tu cuenta de usuario ejecutando gcloud init o gcloud auth login . Para comprobar qué cuenta está activa, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la siguiente:

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

Entender tu respuesta

Las fuentes de Google Maps se devuelven en un plazo de groundingMetadata en groundingChunks. Se devuelven fuentes tanto de sitios como de reseñas de usuarios, que se han usado para generar el resultado fundamentado de Google Maps.

En este código de ejemplo se muestra una fuente de sitios y una fuente de respuestas de sitios en la respuesta:

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

Requisitos de uso del servicio

En esta sección se describen los requisitos de uso del servicio de Grounding con Google Maps.

Informar al usuario sobre el uso de las fuentes de Google Maps

Con cada resultado fundamentado de Google Maps, recibirás fuentes en groundingChunks. Cuando presentes resultados de Grounding con Google Maps con Vertex AI Studio, debes especificar las fuentes de Google Maps asociadas. En concreto, debe cumplir los siguientes requisitos:

• Las fuentes de Google Maps deben ir inmediatamente después del contenido generado que admiten. Este contenido generado también se conoce como resultado fundamentado de Google Maps.
• Las fuentes de Google Maps deben poder verse con una sola interacción del usuario.

Mostrar fuentes de Google Maps con enlaces de Google Maps

Para cada fuente de groundingChunks y grounding_chunks.maps.placeAnswerSources.reviewSnippets, 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 de Google Maps.
• Muestra el título de la fuente proporcionado en la respuesta.
• Enlaza a la fuente con uri o googleMapsUri desde la respuesta.

En estas imágenes se muestran los requisitos mínimos para mostrar las fuentes y sus enlaces de Google Maps.

Puede contraer la vista de las fuentes.

Opcional: Mejora la vista previa del enlace con contenido adicional, como:

• El icono de página de Google Maps se inserta antes de la atribución de texto de Google Maps.
• Foto de la URL de origen (og:image).

Para obtener más información sobre algunos de nuestros proveedores de datos de Google Maps y sus términos de licencia, consulta los avisos legales de Google Maps y Google Earth.

Requisitos de atribución de Google Maps

Cuando atribuyas fuentes a Google Maps en texto, sigue estas directrices:

• No modifiques el texto Google Maps de ninguna forma:

  • No cambies las mayúsculas y minúsculas de Google Maps.
  • No incluyas Google Maps en varias líneas.
  • No localices Google Maps a otro idioma.
  • Para evitar que los navegadores traduzcan Google Maps, usa el atributo HTML translate="no".

• Aplica el estilo Google Maps al texto tal como se describe en la siguiente tabla:

Propiedad	Estilo
Conjunto de fuentes	Roboto. Cargar la fuente es opcional.
Conjunto de fuentes de reserva	Cualquier fuente de cuerpo sin remates que ya se use en tu producto o "Sans-Serif" para invocar la fuente predeterminada del sistema
Estilo de fuente	Normal
Grosor de fuente	400
Color de fuente	Blanco, negro (#1F1F1F) o gris (#5E5E5E). Mantener un contraste accesible (4,5:1) con el fondo.
Tamaño de fuente	Tamaño de fuente mínimo: 12 sp Tamaño de fuente máximo: 16 sp Para obtener más información sobre las unidades sp, consulta las unidades de tamaño de fuente en el sitio web de Material Design.
Espaciado de las letras	Normal

Ejemplo de CSS

El siguiente CSS renderiza Google Maps con el estilo tipográfico y el color adecuados sobre un fondo blanco o claro.

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

Token de contexto, ID de sitio e ID de reseña

Los datos de Google Maps incluyen el token de contexto, el ID de sitio y el ID de reseña. Puede almacenar en caché, almacenar y exportar los siguientes datos de respuesta:

• googleMapsWidgetContextToken
• placeId
• reviewId

No se aplican las restricciones contra el almacenamiento en caché de los Términos de Grounding con Google Maps.

Territorios prohibidos

La función de grounding con Google Maps tiene restricciones para determinados contenidos y actividades con el objetivo de mantener una plataforma segura y fiable. Tu usuario no distribuirá ni promocionará una aplicación que ofrezca Grounding con Google Maps en un territorio prohibido, entre los que se incluyen los siguientes:

• China
• Crimea
• Cuba
• República Popular de Donetsk
• Irán
• República Popular de Luhansk
• Corea del Norte
• Siria
• Vietnam

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.

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.

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

La información de los resultados concretos de Google Maps puede diferir de las condiciones reales de la carretera.

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 reseñas y fotos de usuarios, que es contenido generado por usuarios (CGU), en el caso en el que se usa la petición 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:

1. Crea un widget contextual.

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

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

   Para actualizar el token de contexto, define 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. Entre los valores válidos se incluyen los siguientes:

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

   En este ejemplo 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. Entre los valores válidos se incluyen los siguientes:

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

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

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

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.