Embasamento com o Google Maps na Vertex AI

Esta página descreve como o embasamento com o Google Maps na Vertex AI pode ajudar a melhorar seus aplicativos de IA generativa fornecendo contexto geoespacial.

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 milhões de locais, incluindo empresas, pontos de referência e pontos de interesse. Esses dados dão acesso a informações sobre mais de 250 milhões de lugares que podem ser usados para fundamentar as respostas do modelo, permitindo que seus aplicativos e agentes de IA forneçam dados locais e contexto geoespacial.

Usos do embasamento com o Google Maps

Você pode usar o embasamento com o Google Maps para vários aplicativos, 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 contar mais sobre os parques e restaurantes familiares que estão a uma distância caminhável?"

Isso pode ser útil para setores como imobiliário, viagens, mobilidade e aplicativos sociais.

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

Modelos compatíveis

Esta seção lista os modelos que oferecem suporte ao embasamento com o Google Maps.

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

Usar o embasamento com o Google Maps para embasar as respostas do modelo

Este exemplo de código demonstra como usar o embasamento com o Google Maps para embasar as respostas do seu modelo.

Os resultados da pesquisa podem ser personalizados para um local geográfico específico usando as coordenadas de latitude e longitude. Para mais informações, consulte a API Grounding.

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.

Suas respostas aos comandos serão embasadas com o 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. Por exemplo, uma latitude de 37.7749 representa São Francisco. Você pode usar serviços como o Google Maps ou outras ferramentas de geocodificação para obter coordenadas de latitude e longitude.
  • LONGITUDE: a longitude do local. Por exemplo, uma longitude de -122.4194 representa São Francisco.

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: widget contextual do Google Maps

O widget contextual é uma oferta de pré-GA do Google Maps, um contêiner visual usado para apoiar ou complementar outros conteúdos do Google Maps. O widget contextual do Google Maps permite integrar o Grounding com o Google Maps aos seus aplicativos para criar uma experiência de chat com tecnologia de LLM. O widget contextual é renderizado usando o token de contexto, googleMapsWidgetContextToken, que é retornado na resposta da API Vertex AI e pode ser usado para renderizar conteúdo visual.

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

  • Ele mostra conteúdo gerado pelo usuário (CGU) subjetivo no cenário em que o Google Maps usa solicitações para gerar respostas.

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

Para mais informações sobre o widget contextual, 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. Em qualquer resposta baseada no Google Maps, há um googleMapsWidgetContextToken correspondente 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 layout da lista. Os valores válidos incluem:

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

    Este exemplo de código demonstra como mudar o layout da lista para um layout compacto.

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

  4. Opcional: mude o modo do mapa. Os valores válidos incluem:

    • 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 mudar 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>

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. Em qualquer resposta baseada no Google Maps, há um googleMapsWidgetContextToken correspondente usado para renderizar o widget contextual e colocado perto da resposta gerada.

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

    • Layout compacto: layout: google.maps.places.PlaceContextualListLayout.COMPACT
    • Layout vertical: layout: google.maps.places.PlaceContextualListLayout.VERTICAL

    Este exemplo de código demonstra como mudar o layout da lista para um layout compacto.

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

  4. Opcional: mude o modo do mapa. Os valores válidos incluem:

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

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

      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 direta a informações disponibilizadas usando o recurso de embasamento com o Google Maps, você precisa especificar as fontes do Google Maps usadas para embasar 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

É necessário informar aos usuários sobre o seguinte:

  • As fontes de embasamento usadas para apoiar o conteúdo gerado pelo LLM próximo ao conteúdo.
  • As fontes de embasamento precisam estar visíveis em uma interação do usuário.

Mostrar URLs de origem do Google Maps

As fontes do Google Maps são retornadas em groundingMetadata dentro de groundingChunks e groundingSupports. As fontes do Google Maps são retornadas para lugares e para conteúdo de resposta de lugares, como avaliações de usuários, que foram usadas para gerar a resposta.

Este exemplo de código demonstra 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, uma prévia de link precisa ser gerada seguindo estes requisitos:

  • Atribua cada fonte ao Google Maps seguindo as diretrizes de atribuição de texto.
  • Mostrar o título da página do Open Graph (og:title) ou o título com o formato:

    [Place Name] - Google Maps

  • Navegue até o material de origem usando o URL de origem.

Se houver fontes de respostas sobre o lugar em groundingChunks, faça o seguinte:

  • Renderizar links de avaliação em grounding_chunks.maps.placeAnswerSources.reviewSnippets.googleMapsUri.
  • Mostrar o título do Open Graph ou um título com o formato:

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

    Place Name pode ser encontrado em grounding_chunks.maps.title e Author Name pode ser encontrado em grounding_chunks.maps.placeAnswerSources.reviewSnippets.authorAttribution.displayName.

  • Opcional: melhore 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 os requisitos mínimos, que são exibir os links de lugar.

Comando com resposta mostrando fontes

É possível recolher a visualização das origens.

Comando com resposta e fontes recolhidas

Esta imagem mostra a foto do lugar, que é um link opcional para visualizar os atributos das fontes.

Comando com resposta e fontes

Territórios proibidos

O 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 usadas para descrever locais e usadas pelo Grounding com o Google Maps para gerar respostas. Essas propriedades são usadas para determinar os tipos de perguntas que o Grounding com o Google Maps pode responder.

Exemplo de propriedades de lugar

Esta lista fornece uma amostragem em ordem alfabética de propriedades sobre lugares que podem ser usadas pelo seu modelo 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 uma resposta do embasamento com o Google Maps com base em informações derivadas das avaliações dos usuários. Se houver um problema com o conteúdo da resposta do lugar fornecida nos metadados, informe ao Google usando um link no campo flagContentUri dentro do objeto PlaceAnswerSources na resposta da API.

Exemplos de uso de propriedades de lugar

Os exemplos a seguir usam propriedades de lugar em perguntas sobre diferentes tipos de lugares. A fundamentação com o Google Maps usa as propriedades para entender sua intenção e fornece respostas relevantes com base nos dados associados a lugares no Google Maps.

  • Planejar um jantar em família: você pode perguntar: O restaurante "The Italian Place" é bom para crianças? Eles oferecem comida para viagem? Qual é a classificação deles?

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

  • Verificar a acessibilidade para um amigo: você pode perguntar: Preciso de um restaurante que tenha uma entrada acessível para cadeirantes.

    Uma resposta a esse comando pode ajudar você a determinar se o local atende a necessidades específicas de acessibilidade.

  • Encontrar um lugar para comer um lanche tarde da noite: você pode perguntar: O "Burger Joint" está aberto agora? Eles servem jantar? Qual é o horário de funcionamento na sexta-feira?

    As respostas a essas perguntas ajudam você a encontrar um estabelecimento aberto que sirva uma refeição específica em um determinado horário.

  • Encontrar um cliente para tomar um café: você pode perguntar: O "Café Central" tem Wi-Fi? Eles servem café? Qual é o nível de preços e eles aceitam cartões de crédito?

    As respostas a essas perguntas ajudam você 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.

A seguir

  • Para saber mais sobre como embasar 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.