Fundamentação com o Google Maps no Vertex AI

Esta página descreve como a fundamentação com o Google Maps e a Vertex AI pode ajudar a melhorar as suas aplicações de IA generativa, fornecendo contexto geoespacial.

Vista geral

A fundamentação com o Google Maps com a Vertex AI é um serviço que associa os modelos Gemini a dados geoespaciais do Google Maps. O Google Maps tem acesso a informações sobre milhões de localizações, incluindo empresas, pontos de referência e pontos de interesse. Estes dados dão-lhe acesso a informações sobre mais de 250 milhões de locais que podem ser usados para fundamentar as respostas do seu modelo, permitindo que os seus agentes e aplicações de IA forneçam dados locais e contexto geoespacial.

Também pode ativar a fundamentação simultânea com o Google Maps, a Pesquisa Google e a fundamentação com as suas origens de dados.

Usos da fundamentação com o Google Maps

Pode usar a fundamentação com o Google Maps para várias aplicações, como:

  • Assistentes conversacionais que podem responder a perguntas sobre locais próximos, como "Onde fica o local mais próximo para beber um expresso italiano?"
  • Descrições personalizadas e estatísticas da comunidade, como"Podes dizer-me mais sobre restaurantes adequados para famílias que estejam a uma distância a pé?"
  • Resumos de áreas em torno de localizações específicas, como uma estação de carregamento de VE ou um hotel.

Isto pode ser benéfico para exemplos de utilização em imobiliário, viagens, mobilidade e apps de redes sociais.

Modelos suportados

Esta secção apresenta os modelos que suportam a fundamentação com o Google Maps.

Para mais informações sobre os modelos Gemini, consulte o artigo Modelos Gemini.

Use a fundamentação com o Google Maps para fundamentar as respostas do seu modelo

Este exemplo de código demonstra como usar a fundamentação com o Google Maps para fundamentar as respostas do seu modelo.

Os resultados da pesquisa podem ser personalizados para uma localização geográfica específica através das coordenadas de latitude e longitude. Para mais informações, consulte a API Grounding.

Consola

Para usar a fundamentação com o Google Maps com a Vertex AI, siga estes passos:

  1. Na Google Cloud consola, aceda à página Vertex AI Studio.

    Aceda ao Vertex AI Studio

  2. Na secção Ferramentas, clique em Fundamentação: Google. É apresentado um painel de configuração.

  3. Para usar o Google Maps, clique no botão Google Maps.

  4. Clique em Aplicar.

  5. Introduza o comando no campo e clique em Enviar. As suas respostas rápidas baseiam-se no Google Maps.

Python

Instalação

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA gen com o 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

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • LOCATION: a região para processar o pedido. Para usar o ponto final global, exclua a localização do nome do ponto final e configure a localização do recurso como global.
  • PROJECT_ID: o seu ID do projeto.
  • MODEL_ID: o ID do modelo multimodal.
  • PROMPT: o comando a enviar para o modelo.
  • LATITUDE: a latitude da localização. Por exemplo, uma latitude de 37.7749 representa Lisboa. Pode obter coordenadas de latitude e longitude através de serviços como o Google Maps ou outras ferramentas de geocodificação.
  • LONGITUDE: a longitude da localização. Por exemplo, uma longitude de -122.4194 representa Lisboa.
  • ENABLE_WIDGET: se deve devolver um token e ativar o widget do Google Maps (a predefinição é false).

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve receber uma resposta JSON semelhante à seguinte:

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

Propriedades do local

Esta secção apresenta as propriedades de locais usadas para descrever localizações e usadas pela fundamentação com o Google Maps para gerar respostas. Estas propriedades são usadas para determinar os tipos de perguntas que a fundamentação com o Google Maps pode responder.

Exemplo de propriedades de locais

Esta lista fornece uma amostragem alfabética de propriedades sobre locais que podem ser usadas pelo seu modelo para gerar respostas.

  • Endereço
  • Recolha no exterior
  • Cartão de débito
  • Distância
  • Parque de estacionamento gratuito
  • Música ao vivo
  • Menu infantil
  • Horário de funcionamento
  • Opções de pagamento (como dinheiro ou cartão de crédito)
  • Resposta sobre um local
  • Aceita animais de estimação
  • Serve cerveja
  • Serve comida vegetariana
  • Acessível a cadeiras de rodas
  • Wi-Fi

As respostas de locais são uma resposta da fundamentação com o Google Maps baseada em informações derivadas das críticas dos utilizadores.

Exemplos de utilização de propriedades de locais

Os exemplos seguintes usam propriedades de locais em perguntas sobre diferentes tipos de locais. A fundamentação com o Google Maps usa as propriedades para compreender a sua intenção e, em seguida, fornece respostas relevantes com base nos dados associados a locais no Google Maps.

  • Planeie um jantar em família: pode perguntar "O restaurante "The Italian Place" é bom para crianças e tem serviço de take-away?" Qual é a classificação?

    As respostas a estas perguntas ajudam a determinar se um restaurante é adequado para uma família e se oferece um serviço conveniente.

  • Verificar a acessibilidade para um amigo: pode perguntar: preciso de um restaurante que tenha uma entrada acessível a cadeiras de rodas.

    Uma resposta a este comando pode ajudar a determinar se a localização cumpre necessidades de acessibilidade específicas.

  • Encontrar um local para um snack tardio: pode perguntar "O Burger Joint está aberto agora?" Serve jantares? Qual é o horário de funcionamento para sexta-feira?

    As respostas a estas perguntas ajudam a encontrar um estabelecimento aberto que sirva uma refeição específica durante um determinado período.

  • Reunir-se com um cliente para tomar café: pode perguntar O "Café Central" tem Wi-Fi? Serve café? Qual é o nível de preço e aceitam cartões de crédito?

    As respostas a estas perguntas ajudam a avaliar a adequação de um café para uma reunião de negócios com base nas comodidades, nas ofertas e nas opções de pagamento.

As informações nos resultados fundamentados do Google Maps podem diferir das condições reais da estrada.

Compreenda a sua resposta

As origens do Google Maps são devolvidas em groundingMetadata no prazo de groundingChunks. São devolvidas fontes para locais e críticas de utilizadores, que foram usadas para ajudar a gerar o resultado fundamentado do Google Maps.

Este exemplo de código demonstra uma origem de local e uma origem de resposta de local na resposta:

"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 utilização do serviço

Esta secção descreve os requisitos de utilização do serviço para a fundamentação com o Google Maps.

Informar o utilizador sobre a utilização de origens do Google Maps

Com cada resultado fundamentado do Google Maps, recebe fontes em groundingChunks que fundamentam cada resposta. Os seguintes metadados também são devolvidos:

  • URI de origem
  • título
  • ID

Quando apresentar resultados da fundamentação com o Google Maps com a Vertex AI, tem de especificar as origens do Google Maps associadas e informar os seus utilizadores do seguinte:

  • As fontes do Google Maps têm de seguir imediatamente o conteúdo gerado que as fontes suportam. Este conteúdo gerado também é denominado resultado fundamentado do Google Maps.
  • As fontes do Google Maps têm de ser visíveis com uma interação do utilizador.

Para cada origem em groundingChunks e em grounding_chunks.maps.placeAnswerSources.reviewSnippets, tem de ser gerada uma pré-visualização do link de acordo com os seguintes requisitos:

Estas imagens mostram os requisitos mínimos para apresentar as fontes e os links do Google Maps.

Comando com resposta que mostra as fontes

Pode reduzir a vista das origens.

Comando com resposta e fontes reduzidas

Opcional: melhore a pré-visualização do link com conteúdo adicional, como:

  • É inserido um favicon do Google Maps antes da atribuição de texto do Google Maps.
  • Uma foto do URL de origem (og:image).

Para mais informações sobre alguns dos nossos fornecedores de dados do Google Maps e os respetivos termos de licença, consulte os avisos legais do Google Maps e Google Earth.

Diretrizes de atribuição de texto do Google Maps

Quando atribui fontes ao Google Maps em texto, siga estas diretrizes:

  • Não modifique o texto Google Maps de forma alguma:
    • Não altere a capitalização de Google Maps.
    • Não divida Google Maps em várias linhas.
    • Não localize o Google Maps para outro idioma.
    • Impeça que os navegadores traduzam o Google Maps através do atributo HTML translate="no".
  • Estilize o texto do Google Maps conforme descrito na tabela seguinte:
Propriedade Estilo
Família de tipos de letra Roboto. O carregamento do tipo de letra é opcional.
Família de tipos de letra alternativa Qualquer tipo de letra sem serifa já usado no seu produto ou "Sans-Serif" para invocar o tipo de letra do sistema predefinido
Estilo do tipo de letra Normal
Espessura do tipo de letra 400
Cor do tipo de letra Branco, preto (#1F1F1F) ou cinzento (#5E5E5E). Manter um contraste acessível (4,5:1) com o fundo.
Tamanho do tipo de letra Tamanho mínimo do tipo de letra: 12 sp
Tamanho máximo do tipo de letra: 16 sp
Para saber mais acerca dos sp, consulte as unidades de tamanho do tipo de letra no Website do Material Design.
Espaçamento entre letras Normal

Exemplo de CSS

O CSS seguinte renderiza o Google Maps com o estilo tipográfico e a cor adequados num fundo branco ou 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 do local e ID da crítica

Os dados do Google Maps incluem o token de contexto, o ID do local e o ID da crítica. Pode colocar em cache, armazenar e exportar os seguintes dados de resposta:

  • googleMapsWidgetContextToken
  • placeId
  • reviewId

As restrições contra o armazenamento em cache nos Termos de fundamentação com o Google Maps não se aplicam.

Território proibido

A fundamentação com o Google Maps tem restrições para determinados conteúdos e atividades para manter uma plataforma segura e fiável. O Cliente não irá distribuir nem comercializar uma Aplicação do Cliente que ofereça Fundamentação com o Google Maps num Território Proibido. Os territórios proibidos atuais são:

  • China
  • Crimeia
  • Cuba
  • República Popular de Donetsk
  • Irão
  • República Popular de Luhansk
  • Coreia do Norte
  • Síria
  • Vietname

Esta lista pode ser atualizada periodicamente.

Opcional: widget contextual do Google Maps

O widget contextual é uma Oferta de pré-GA do Google Maps que é um contentor visual usado para suportar ou complementar outro conteúdo do Google Maps. O widget contextual do Google Maps permite-lhe integrar a fundamentação com o Google Maps nas suas aplicações para criar uma experiência de chat conversacional baseada em MDIs. O widget contextual é renderizado através do token de contexto, googleMapsWidgetContextToken, que é devolvido na resposta da API Vertex AI e pode ser usado para renderizar conteúdo visual.

O widget contextual tem funções diferentes consoante o seu cenário:

  • Apresenta críticas e fotos dos utilizadores, que é conteúdo gerado pelo utilizador (UGC), no cenário em que os comandos do Google Maps são usados para gerar respostas.

  • Ajuda a enriquecer os resultados com visualizações de mapas e dados quando a Vertex AI gera apenas uma resposta de texto.

Para mais informações sobre o widget contextual, consulte o widget de fundamentação do Maps.

Renderize o widget contextual do Google Maps

Para renderizar e usar o widget contextual do Google Maps, use a versão alfa da API JavaScript do Google Maps na página que apresenta o widget. Para mais informações, consulte o artigo Carregue a API Maps JavaScript.

Os exemplos de código seguintes demonstram como usar um widget contextual:

  1. Crie um widget contextual.

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

  2. Em qualquer resposta fundamentada no Google Maps, existe um googleMapsWidgetContextToken correspondente que é usado para renderizar o widget contextual e colocado perto da resposta gerada.

    Para atualizar o token de contexto, defina o 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: especifique o esquema de lista. Os valores válidos incluem o seguinte:

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

    Este exemplo de código demonstra a alteração do esquema de lista para um esquema compacto.

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

  4. Opcional: altere o modo de mapa. Os valores válidos incluem o seguinte:

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

    Este exemplo de código demonstra como alterar o modo de mapa para um mapa 2D.

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

O que se segue?

  • Para saber como fundamentar os modelos Gemini nos seus dados, consulte o artigo Fundamentar com os seus dados.
  • Para saber mais sobre as práticas recomendadas de IA responsável e os filtros de segurança da Vertex AI, consulte o artigo IA responsável.