Embasamento com o Google Maps na Vertex AI

Este guia mostra como usar o Grounding com o Google Maps na Vertex AI para melhorar seus aplicativos de IA generativa fornecendo contexto geoespacial.

Neste documento, discutimos os seguintes tópicos:

O diagrama a seguir resume o fluxo de trabalho geral:

Visão geral

O embasamento com o Google Maps na Vertex AI é um serviço de pré-lançamento que conecta modelos do Gemini com dados geoespaciais do Google Maps. O Google Maps tem acesso a informações sobre mais de 250 milhões de lugares, incluindo empresas, pontos de referência e pontos de interesse. Você pode usar esses dados para fundamentar as respostas do modelo, o que permite que seus aplicativos e agentes de IA forneçam dados locais e contexto geoespacial.

Para receber suporte técnico com o embasamento com o Google Maps, envie um e-mail para maps-grounding-feedback-external@google.com.

Usos do embasamento com o Google Maps

Você pode usar o embasamento com o Google Maps para várias aplicações, como:

  • Agentes baseados em chat
  • Resumo das informações do lugar
  • Tradução de conteúdo
  • Assistentes de conversa que podem responder a perguntas sobre lugares próximos, como "Há algum parque por perto?"
  • Descrições personalizadas de lugares, como "Você pode me falar mais sobre os parques e restaurantes familiares que estão a uma distância caminhável?"

Esse recurso é útil para setores como imobiliário, viagens, mobilidade e aplicativos sociais.

Modelos compatíveis

Os seguintes modelos são compatíveis com o embasamento com o Google Maps.

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

Embasar as respostas do modelo

É possível embasar as respostas do modelo usando o Vertex AI Studio para testar comandos ou a API REST para integrar o embasamento aos seus aplicativos.

Método Descrição Caso de uso
Vertex AI Studio Uma UI da Web para testar comandos e configurações de embasamento sem escrever código. Ideal para prototipagem rápida, teste de comandos e exploração dos recursos.
API REST Uma interface programática para integrar o embasamento diretamente aos seus aplicativos. Ideal para ambientes de produção e criação de aplicativos automatizados e escalonáveis que usam o Grounding com o Google Maps.

Os exemplos a seguir mostram como usar o embasamento com o Google Maps para embasar as respostas do modelo.

Console

Para usar o Embasamento com o Google Maps no Vertex AI Studio, siga estas etapas:

  1. No console Google Cloud , acesse a página Vertex AI Studio.

    Acessar o Vertex AI Studio

  2. Clique na guia Formato livre.
  3. No painel lateral, clique no botão Embasar respostas do modelo.
  4. Clique em Personalizar e defina o Google Maps como a origem.
  5. Insira o comando na caixa de texto e clique em Enviar.

As respostas do modelo agora são embasadas no Google Maps.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • LOCATION: a região para processar a solicitação.
  • PROJECT_ID: o ID do projeto.
  • MODEL_ID: o ID do modelo multimodal.
  • TEXT: as instruções de texto a serem incluídas no comando.
  • LATITUDE: a latitude do local.
  • LONGITUDE: a longitude do local.

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 da solicitação:

{
  "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 a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante a esta:

{
  "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: usar o widget contextual do Google Maps

O widget contextual é uma oferta pré-GA do Google Maps que você pode usar para integrar o Grounding com o Google Maps aos seus aplicativos e criar uma experiência de chat conversacional com tecnologia LLM. Para renderizar o widget, use o googleMapsWidgetContextToken que a API Vertex AI retorna na resposta.

O widget contextual tem funções diferentes dependendo do seu cenário:

  • Ele mostra conteúdo gerado pelo usuário (CGU) subjetivo quando o Google Maps é usado para gerar respostas.
  • Ele enriquece os resultados com visualizações de mapa e dados quando a Vertex AI gera apenas uma resposta de texto.

Para mais informações, consulte Widget de embasamento do Maps.

Renderizar o widget contextual do Google Maps

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

Os exemplos de código a seguir demonstram como usar um widget contextual.

HTML

1. Crie um widget contextual.

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

2. Atualize o token de contexto.

Qualquer resposta com base no Google Maps inclui um googleMapsWidgetContextToken. Use esse token para renderizar o widget contextual definindo a propriedade widget.contextToken. Coloque o widget perto da resposta gerada.

"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: personalize o widget.

  • Especifique o layout da lista. Os valores válidos são compact (padrão) e vertical.

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

  • Mude o modo do mapa. Os valores válidos são roadmap (mapa 2D), hybrid (mapa 3D) e none.

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

JavaScript

1. Crie um 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. Atualize o token de contexto.

Qualquer resposta com base no Google Maps inclui um googleMapsWidgetContextToken. Use esse token para renderizar o widget contextual definindo a propriedade widget.contextToken. Coloque o widget perto da resposta gerada.

"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: personalize o widget.

  • Especifique o layout da lista. Os valores válidos são google.maps.places.PlaceContextualListLayout.COMPACT (padrão) e google.maps.places.PlaceContextualListLayout.VERTICAL.

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

  • Mude o modo do mapa. Os valores válidos são google.maps.places.PlaceContextualListMapMode.ROADMAP (mapa 2D), google.maps.places.PlaceContextualListMapMode.HYBRID (mapa 3D) e google.maps.places.PlaceContextualListMapMode.NONE.

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

Requisitos de atribuição de origem

Ao apresentar conteúdo gerado pela Vertex AI que faz referência a informações do recurso de embasamento com o Google Maps, especifique as fontes do Google Maps que embasam a resposta.

Esta imagem mostra as fontes do Google Maps usadas para apoiar a resposta do modelo.

Comando com resposta mostrando fontes

Informar ao usuário final sobre o uso de fontes de embasamento

Você precisa informar aos usuários que o conteúdo gerado por LLM é respaldado por fontes de fundamentação. Coloque essas informações perto do conteúdo e deixe-as visíveis em uma interação do usuário.

Mostrar URLs de origem do Google Maps

A resposta da API retorna fontes do Google Maps no campo groundingMetadata em groundingChunks e groundingSupports. As fontes são retornadas para lugares e para conteúdo de suporte, como avaliações de usuários.

Este exemplo de código mostra uma fonte de lugar e uma fonte de resposta de lugar na resposta:

  "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 fonte referenciada pelo LLM, gere uma prévia de link que atenda aos seguintes requisitos:

  • Atribuição ao Google Maps: siga as diretrizes de atribuição de texto.
  • Mostrar o título: use o título da página do Open Graph (og:title) ou o formato [Place Name] - Google Maps.
  • Link para a fonte: o link precisa navegar até o material de origem usando o URL da fonte.

Se groundingChunks contiver fontes de respostas de lugar, também será necessário fazer o seguinte:

  • Renderizar links de avaliação: use o URL de grounding_chunks.maps.placeAnswerSources.reviewSnippets.googleMapsUri.
  • Mostrar o título da avaliação: use o título do Open Graph ou o formato Google Review of [Place Name] by [Author Name]. Place Name está em grounding_chunks.maps.title e Author Name está em grounding_chunks.maps.placeAnswerSources.reviewSnippets.authorAttribution.displayName.

Você pode melhorar a prévia do link com conteúdo adicional, como:

  • Favicon do Google Maps (<link rel="icon" href="https://www.google.com/favicon.ico">) inserido antes da atribuição de texto do Google Maps.
  • Descrição (og:description)
  • Foto (og:image)

Essas imagens mostram o requisito mínimo, que é exibir os links de lugar. É possível recolher a visualização das fontes.

Comando com resposta mostrando fontes Comando com resposta e fontes recolhidas

Esta imagem mostra uma melhoria opcional, que inclui uma foto do lugar.

Comando com resposta e fontes

Territórios proibidos

A Plataforma Google Maps restringe determinados conteúdos e atividades para manter uma plataforma segura e confiável. Para conferir uma lista de territórios proibidos, consulte Territórios proibidos da Plataforma Google Maps.

Propriedades do lugar

Esta seção lista as propriedades de lugar que o Grounding com o Google Maps usa para gerar respostas. Essas propriedades determinam os tipos de perguntas que o Grounding com o Google Maps pode responder.

Exemplo de propriedades de lugar

Confira a seguir um exemplo em ordem alfabética de propriedades sobre lugares que seu modelo pode usar para gerar respostas.

  • Endereço
  • Retirada
  • Cartão de débito
  • Distância
  • 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 o lugar
  • Aceita animais de estimação
  • Serve cerveja
  • Serve comida vegetariana
  • Acessibilidade para cadeirantes
  • Wi-Fi

As respostas de lugar são respostas do embasamento com o Google Maps com base em informações de avaliações dos usuários. Se houver um problema com o conteúdo de uma resposta do Google Maps, use o link no campo flagContentUri dentro do objeto PlaceAnswerSources na resposta da API para informar o Google.

Exemplos de uso de propriedades de lugar

Os exemplos a seguir usam propriedades de lugar em perguntas sobre diferentes tipos de lugares. O embasamento com o Google Maps usa essas propriedades para entender sua intenção e fornecer respostas relevantes.

  • Planejar um jantar em família: faça perguntas como O restaurante "The Italian Place" é bom para crianças? Eles oferecem comida para viagem? Qual é a classificação deles? Isso ajuda você a determinar se um restaurante é adequado para uma família e oferece serviços convenientes.

  • Verificar a acessibilidade para um amigo: faça perguntas como Preciso de um restaurante com entrada acessível para cadeirantes. Isso ajuda a determinar se o local atende a necessidades específicas de acessibilidade.

  • Encontrar um lugar para comer algo tarde da noite: faça perguntas como O "Burger Joint" está aberto agora? Eles servem jantar? Qual é o horário de funcionamento na sexta-feira? Isso ajuda você a encontrar um estabelecimento aberto que sirva uma refeição específica em um determinado horário.

  • Tomar um café com um cliente: faça perguntas como O "Café Central" tem Wi-Fi? Eles servem café? Qual é o nível de preços e eles aceitam cartões de crédito? Isso ajuda você a avaliar a adequação de um café para uma reunião de negócios com base em comodidades, ofertas e opções de pagamento.

A seguir

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