Guia do programador de agentes de comércio conversacional

Este guia detalha como fazer a integração com a API Conversacional para oferecer experiências de chat dinâmicas com tecnologia de IA aos seus clientes. Ao compreender os diferentes tipos de consultas e tirar partido das respostas da API, pode fornecer pesquisas de produtos relevantes, responder às perguntas dos clientes e orientar os utilizadores finais ao longo do respetivo percurso de compras.

O elemento conversationalFilteringMode na API Conversacional esclarece as diferenças entre o agente de comércio conversacional e a filtragem de produtos conversacional.

Configuração da API e fluxo de chamadas

A API Conversational suporta o agente de comércio conversacional:

A API Conversacional permite uma experiência de chat em que os seus utilizadores enviam consultas e o sistema devolve uma resposta de texto, tipos de consultas classificados e potenciais opções de pesquisa refinadas.

Esta API funciona como um serviço de streaming, o que permite a deteção antecipada da intenção da consulta. As interações subsequentes na conversa requerem a anexação de um conversation_id.

Para devolver resultados da pesquisa, a API Retail antiga tem de ser chamada em paralelo com a API Conversational.

Envie uma consulta do utilizador final

Esta secção descreve como iniciar uma experiência de agente de comércio conversacional. Por exemplo, o utilizador pode introduzir Ajuda-me a planear uma festa no campo de pesquisa.

Envie um pedido para o Vertex AI Search for commerce

Existem dois pontos finais da API diferentes:

  1. A API Conversacional tem de ser usada para obter a experiência conversacional.
  2. A API Search principal tem de ser usada para obter resultados da pesquisa.

Ponto final 1: pedido de API conversacional

  • Deve criar um pedido de agente de comércio conversacional definindo a entrada do utilizador como a consulta.
  • O pedido deve ser enviado como um pedido HTTP POST para o ponto final projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Método HTTP e ponto final

  POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

Pedido de API de conversação:

Consulta inicial

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your core Search API calls to ensure consistency between LLM answers and search results.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
    // Example: "userId": "user123", "userAgent": "Chrome/120.0"
  },
  "conversationalFilteringSpec": {
    // Optional: Controls conversational filtering behavior. Defaults to DISABLED if unset.
    // "conversational_filtering_mode": "DISABLED" - Otherwise you can also explicitly set to disabled.
}
  • placement: o nome do recurso do posicionamento (como projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Este é um parâmetro de caminho e é obrigatório.
  • query: a consulta de pesquisa não processada do utilizador. Este campo é obrigatório.
  • branch: o nome do recurso da ramificação, como projects/P/locations/L/catalogs/C/branches/B. Se não for definida, é usado default_branch. Este campo é obrigatório.
  • visitorId: um identificador exclusivo para acompanhar os visitantes. Este campo é obrigatório.
  • conversationId: um ID exclusivo para acompanhar as sessões de conversa. Para o pedido inicial numa nova conversa, este campo deve estar vazio. Para pedidos subsequentes na mesma conversa, tem de ser definido como o conversation_id recebido no ConversationalSearchResponse anterior.
  • searchParams: (Opcional) Parâmetros de pesquisa principais padrão, como filter, canonicalFilter, sortBy e boostSpec. É fundamental que estes parâmetros reflitam a configuração usada nas chamadas API Search principais para garantir a consistência entre as respostas do MDG e os resultados da pesquisa de produtos apresentados.
  • userInfo: (Opcional) Informações do utilizador para uma personalização melhorada. Pode incluir userId, user_agent e direct_user_request (booleano).
  • conversationalFilteringSpec: (Opcional) Especifica o modo de filtragem conversacional. Se não estiver definido, a predefinição é DISABLED.

    mode: integre a API Conversational através de um destes três modos para controlar a filtragem de produtos conversacional:

    • DISABLED: neste modo, o cliente implementa apenas a pesquisa de agentes de comércio conversacional. Este é o modo preferencial para este guia de implementação na pesquisa de agentes de comércio conversacional.

      • Exemplo de pedido de API

              placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: DISABLED
        }

      Exemplo de resposta da API

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
    • ENABLED: neste modo, o cliente implementa todas as capacidades de conversação, o que inclui a pesquisa de agentes de comércio conversacional e a filtragem de produtos conversacional.

      • Consulte o guia adicional sobre como integrar ambos os produtos de conversa.

      Exemplo de pedido de API

              placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: ENABLED
        }

      Exemplo de resposta da API

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
        conversational_filtering_result: {
            followup_question{
              followup_question: "What is the size?"
              suggested_answers {
                product_attribute_value {
                  name: "size",
                  value: "12oz"
                }
              }
        }
        }
    • CONVERSATIONAL_FILTER_ONLY: se for escolhida, o cliente implementa apenas a filtragem de produtos conversacional. Com este modo selecionado, o utilizador só tem acesso à filtragem de produtos conversacional, sem gerar uma resposta do MDG, uma classificação de consultas nem consultas de pesquisa sugeridas.

      • Consulte o guia do programador de filtros de produtos conversacionais para mais informações.

Ponto final 2: pedido da API Core Search

Existem duas abordagens principais para apresentar resultados da pesquisa na sua interface Web.

Opção 1: mostrar sempre os resultados da pesquisa

Se o design da experiência do utilizador determinar que os resultados da pesquisa devem ser sempre apresentados independentemente do resultado da conversa, como numa área de resultados da pesquisa dedicada junto ao chat, envie a consulta original do utilizador para a API Product Search principal com a sua chamada para a API Conversational. Isto ajuda a garantir que as fichas de produtos estão imediatamente disponíveis.

Opção 2: mostrar resultados da pesquisa com base na saída conversacional

Se o design da experiência do utilizador for mais dinâmico e quiser apresentar resultados da pesquisa apenas consoante a resposta da API Conversacional, como apenas para consultas SIMPLE_PRODUCT_SEARCH ou sempre que forem fornecidas sugestões refined_search, aguarde a resposta da API Conversacional antes de enviar quaisquer consultas para a API Product Search principal. Se houver uma resposta, use a consulta refined_search fornecida para obter resultados de produtos.

Independentemente da opção de interface do utilizador que escolher, quando precisar de obter resultados reais de produtos, pode fazer uma chamada à API Retail. Para mais informações, consulte o artigo Compreenda a classificação da intenção do utilizador e as ações do retalhista.

Método HTTP e ponto final

    POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search

Pedido de API de pesquisa do produto principal:

Consulta inicial

    {
      "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search",
        // Or if using legacy placements:
        // "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
      "query": "Help me plan a party", // This is the original user query
      "visitorId": "your_visitor_id",
      "branch": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch",
      "pageSize": 20, // Optional: Number of results to return per page
      "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")", // Mirroring the filter from the Conversational Commerce API
      "orderBy": "relevance DESC", // Optional
      "userInfo": {
        // Optional: User information for enhanced personalization, should mirror Conversational Commerce API
        // "userId": "user123", "userAgent": "Chrome/120.0"
      },
      "searchMode": "PRODUCT_SEARCH" // Typically for product searches
    }
  • placement (Obrigatório): o nome do recurso da configuração de publicação da pesquisa de retalho ou do posicionamento antigo. Exemplo: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
  • query: obrigatório. A consulta de pesquisa. Pode ser a entrada não processada do utilizador, como Ajuda-me a planear uma festa, ou uma entrada mais otimizada refinedSearch.query (como artigos de planeamento de festas, decorações) obtida a partir da resposta da API Conversational Commerce.
  • visitorId: obrigatório. Um identificador exclusivo para acompanhar os visitantes. Este valor deve ser consistente com o visitorId enviado para a API Conversational Commerce para o mesmo utilizador final.
  • branch (Obrigatório): o nome do recurso da ramificação, como projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
  • pageSize (Opcional): o número máximo de produtos a devolver.
  • filter (Opcional): usado para filtrar os resultados da pesquisa. É aqui que aplicaria todos os filtros que refletem o que envia em `searchParams` para a API Conversational Commerce para garantir a consistência.
  • orderBy (Opcional): especifica a ordem pela qual os produtos são devolvidos (por exemplo, por relevância ou por preço).
  • userInfo (Opcional): informações do utilizador para personalização, devem ser consistentes com a chamada da API Conversational Commerce.
  • searchMode (Opcional): define o comportamento de pesquisa. PRODUCT_SEARCH é comum para consultas gerais de produtos.

Compreenda a resposta

Este exemplo de código demonstra uma resposta da API Conversational Commerce.

A resposta da API (ConversationalSearchResponse) inclui query_types, conversational_text_response (se aplicável), opções de refined_search e, potencialmente, um followup_question ou um conversational_filtering_result. A autorização conversation_id é essencial para continuar a sessão.

Resposta do Vertex AI Search para comércio

Este exemplo de código demonstra uma resposta da API Conversacional:

Resposta inicial

    {
      "userQueryTypes": ["INTENT_REFINEMENT"],
      "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
      "followupQuestion": {
        "followupQuestion": "What kind of party are you planning?"
      },
      "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
      "refinedSearch": [
        { "query": "Decorations" },
        { "query": "Snacks" },
        { "query": "Party Supplies" },
        { "query": "Drinks" },
        { "query": "Cake" }
      ],
      "state": "SUCCEEDED"
    }

O que os retalhistas devem fazer com a resposta (geral)

Renderize estes campos a partir da resposta:

  • user_query_types: este campo fornece as classificações da intenção do utilizador. Para ver ações detalhadas com base nestes tipos, consulte o artigo Compreenda a classificação da intenção do utilizador e as ações do retalhista.
  • conversation_id: pode armazenar este ID exclusivo no armazenamento de sessão do navegador ou num armazenamento do lado do cliente semelhante para manter a sessão de conversa com o servidor. Isto é fundamental para distinguir entre várias conversas em curso para um único comprador. O seu modelo retém o contexto para um determinado conversation_id. O envio de um novo conversation_id inicia uma nova sessão. Recomendamos que defina a duração da sessão, como 30 minutos de inatividade.
  • refined_search: esta é uma lista de consultas de pesquisa refinadas propostas usadas para obter os resultados da pesquisa relevantes. Para o SIMPLE_PRODUCT_SEARCH, é sempre uma única consulta. Para outras consultas que procuram respostas de MDIs, é uma ou mais. As consultas refined_search podem ser usadas para chamadas à API Search principal (SearchService.Search) ou também podem ser apresentadas ao seu utilizador como sugestões.
  • conversational_text_response: apresenta este texto ao utilizador como a resposta principal gerada pela IA à respetiva consulta.
  • followup_question: opcional. É apresentado o followup_question.
  • state: este campo indica o estado da geração de respostas ("STREAMING" ou "SUCCEEDED"). Pode usá-lo para feedback da experiência do utilizador, como mostrar um indicador de carregamento até "SUCCEEDED". Mais detalhes sobre este assunto na secção seguinte.

Compreenda a API de streaming

A API Conversational Commerce funciona como um serviço de streaming. Isto significa que o utilizador recebe partes da resposta em vários blocos, em vez de uma única carga útil completa.

  • Porquê o streaming? A geração de texto por MDIs/CEs pode demorar algum tempo. O streaming permite-lhe agir mais rapidamente.
  • Primeiro bloco de resposta (instantâneo):
  • Contém consultas userQueryTypes e refinedSearch.
  • state: "STREAMING"
  • Blocos subsequentes:
  • Contêm partes do conversationalTextResponse à medida que está a ser gerado.
  • Último fragmento:
  • Contém o conversationalTextResponse completo.
  • state: "SUCCEEDED"
  • Estatísticas acionáveis: pode determinar a intenção do utilizador imediatamente a partir do primeiro bloco e começar a obter resultados de produtos em paralelo enquanto a resposta de texto da IA ainda está a ser carregada.

O primeiro bloco da resposta inclui as consultas query_types e refined_search, e o respetivo state é indicado como STREAMING. Esta deteção precoce da intenção e disponibilidade imediata de refinamentos de pesquisa permite que o seu modelo tome decisões rápidas sobre como processar a consulta do utilizador e como gerir a experiência do utilizador relativamente à latência das respostas do MDG:

  • Para tipos de consultas que não esperam uma resposta de texto conversacional, como SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT:
    • Como query_types estão no primeiro bloco, o sistema sabe imediatamente que não vai receber uma resposta do MDI/CE. Pode continuar com o processamento predefinido para estes tipos, como apresentar uma mensagem estática ou redirecionar para o apoio técnico, sem aguardar mais resultados da conversa.
    • Especificamente para SIMPLE_PRODUCT_SEARCH, o seu sistema pode fazer imediatamente uma chamada direta para a API Search principal através da consulta refined_search recebida no primeiro fragmento. Isto ajuda a garantir que os resultados da pesquisa são apresentados com um atraso mínimo, cumprindo os SLAs típicos da experiência de pesquisa.
  • Para tipos de consultas que esperam uma resposta de texto conversacional, como INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT:
    • Recebe as consultas query_types e refined_search no bloco inicial. Pode iniciar imediatamente uma chamada paralela à API Google Search Core usando estas consultas refined_search para começar a carregar os resultados dos produtos.
    • Os fragmentos subsequentes são transmitidos em fluxo contínuo, contendo diferentes secções da resposta de texto conversacional. Durante este período, o state permanece "STREAMING".
    • Por último, o último fragmento inclui a resposta de texto conversacional completa e o respetivo state muda para "COMPLETED".
    • Esta abordagem de streaming permite uma experiência do utilizador final fluida, em que os resultados da pesquisa podem começar a ser carregados enquanto o resumo de IA está a ser gerado. Pode optar por apresentar um indicador de carregamento para a resposta conversacional ou apresentar a resposta conversacional depois de ser totalmente transmitida.

Compreenda a classificação da intenção do utilizador e as ações do retalhista

O classificador de intenções decide como processar a consulta do utilizador e que modo de conversa iniciar.

O campo query_types na resposta é uma lista que indica as classificações da intenção do utilizador. O seu sistema deve processar estes elementos da seguinte forma. Tenha em atenção que conversational_text_response se refere à resposta de linguagem natural gerada pela IA da API.

O campo userQueryTypes (no primeiro fragmento de resposta) é o campo mais importante para determinar a próxima ação da sua aplicação:

  • SIMPLE_PRODUCT_SEARCH: vestido vermelho
    • Resposta da API: não.conversational_text_response Devolve uma única consulta refinedSearch.
    • A sua ação: chame imediatamente a API Google Search com o refinedSearch.query. Fazer a transição para uma página de resultados da pesquisa padrão ou apresentar resultados.
  • INTENT_REFINEMENT / PRODUCT_COMPARISON / BEST_PRODUCT: planear uma festa
    • Resposta da API: fornece consultas conversationalTextResponse, refinedSearch e, possivelmente, um followupQuestion.
    • Ação: apresentar a resposta de texto da IA. Use as consultas refinedSearch para preencher carrosséis de produtos ou sugestões. Apresentar o followupQuestion.
  • Consultas de apoio técnico: inclua ORDER_SUPPORT e STORE_RELEVANT.
    • Resposta da API: não.conversational_text_response
    • A sua ação: redirecione o utilizador para a página adequada, como o acompanhamento de encomendas, o localizador de lojas ou apresente uma resposta predefinida.

O agente de comércio conversacional usa categorias de consultas de pesquisa para determinar se é gerada uma resposta baseada em MDIs e como as consultas dos utilizadores finais são processadas pelas APIs Conversacionais e de Pesquisa nestes cenários:

Categorias Classificações de consultas
1.º Consultas irrelevantes que não requerem uma resposta do MDG
  • QUERY_TYPE_UNSPECIFIED: tipo de consulta não especificado.
  • RETAIL_IRRELEVANT: consultas irrelevantes para o domínio de retalho, por exemplo, uma consulta adversária (como como fazer uma bomba),uma consulta conversacional (como como está) ou uma consulta de jailbreak (como escrever um poema).
  • BLOCKLISTED: Consultas explicitamente bloqueadas pelos clientes de comércio (como Quais são os efeitos secundários do Advil?).
2.º Consultas de apoio técnico e informações
  • ORDER_SUPPORT: consulta auxiliar ou de apoio técnico (como Acompanhar a minha encomenda, estado da encomenda 12345).
  • DEALS_AND_COUPONS: consultas relevantes para ofertas, promoções, ofertas de produtos e descontos (como Existem ofertas para o Dia de Ação de Graças?).
  • STORE_RELEVANT: consultas relevantes para localizações de lojas, incluindo o horário de funcionamento e a disponibilidade de stock de produtos (como Temos leite em stock?).
  • RETAIL_SUPPORT: consultas relevantes para compras, incluindo métodos de pagamento (Que métodos de pagamento aceitam?).
3.º Pesquisas de palavras-chave que não requerem um MDG

Pedido de API conversacional:

Consulta inicial

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "show me some monster energy drinks",
  "visitorId": "test"
}

Resposta da API de conversação:

Resposta inicial

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9",
  "refinedSearch": [
    {
      "query": "monster energy drinks"
    }
  ]
}

Pedido da API Search:

Consulta de seguimento

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "monster energy drinks",
  "visitorId": "test"
}
  • SIMPLE_PRODUCT_SEARCH: pesquisa básica de produtos, como vestido vermelho ou mostra algumas bebidas Monster.
4.º Consultas de procura de respostas de MDI/CE

Pedido de API conversacional:

Consulta inicial

  {
    "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
    "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
    "query": "Compare 1% milk with 2% milk",
    "visitorId": "test"
  }

Resposta da API de conversação:

Resposta inicial

{
  "userQueryTypes": ["PRODUCT_COMPARISON"],
  "conversationalTextResponse": "1% milk contains 110 calories, 1.5 g of saturated fat, and 140 mg of sodium per cup. 2% milk is reduced fat with 37% less fat than regular milk and contains vitamins A & D.",
  "conversationId": "0e1cfdac-802f-422d-906e-9fc9f9d733ba",
  "refinedSearch": [
    {
      "query": "1% milk"
    },
    {
      "query": "2% milk"
    }
  ]
}

Pedido da API Search:

Consulta de seguimento

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "1% milk",
  "visitorId": "test"
}
  • PRODUCT_DETAILS: o utilizador está à procura de detalhes e especificações do produto, como mostra-me as especificações de [nome do produto], qual é o teor de proteína do leite com 2% de gordura?.
  • PRODUCT_COMPARISON: comparação de produtos, como compare [product name] and [product name], Compare 1% milk with 2% milk.
  • BEST_PRODUCT: consultas com o padrão mais correspondente, como Qual é o cookie mais saudável?, Qual é a melhor marca de leite?
5.º Refinamento de intenções

Pedido de API conversacional:

Consulta inicial

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch",
  "query": "Help me plan a party",
  "visitorId": "test"
}

Resposta da API de conversação:

Resposta inicial

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}
  • INTENT_REFINEMENT: O tipo não é claro e pode ser necessária uma conversa de seguimento ou um refinamento para esclarecer o tipo, como Ajuda-me a planear uma festa. Esta é, muitas vezes, a intenção mais popular nas conversas.

Categoria 1. Consultas irrelevantes que não requerem uma resposta do MDG

  • QUERY_TYPE_UNSPECIFIED:
    • Não é fornecido nenhum conversational_text_response.
    • Ação: processe como um caso predefinido ou de erro. Pode pedir ao utilizador esclarecimentos ou direcioná-lo para onde pode receber ajuda geral.
  • RETAIL_IRRELEVANT:
    • Não é fornecido nenhum conversational_text_response.
    • Ação: resolva esta situação mostrando uma mensagem adequada, como Não consigo responder a essa pergunta ou Sou um assistente de compras. Como posso ajudar?, conforme definido pelo design da sua aplicação.
  • BLOCKLISTED:
    • Não é fornecido nenhum conversational_text_response.
    • Ação: processe de acordo com a sua política de lista de bloqueio, normalmente mostrando uma mensagem genérica não é possível satisfazer este pedido.

Categoria 2. Consultas de apoio técnico e informações

Para estes tipos, a API não fornece um conversational_text_response direto por predefinição, mas tem opções para direcionar para os links ou recursos certos.

  • ORDER_SUPPORT:
    • Ação predefinida: não é fornecido nenhum conversational_text_response. A sua interface Web tem de apresentar alguma mensagem padrão, links relevantes ou redirecionar a consulta para a sua própria API de apoio técnico dedicada ou canal de serviço ao cliente.
  • DEALS_AND_COUPONS:
    • Ação predefinida: não é fornecido nenhum conversational_text_response. A sua interface Web tem de apresentar alguma mensagem padrão, links relevantes ou redirecionar a consulta para o seu sistema de promoções ou ofertas.
  • STORE_RELEVANT:
    • Ação predefinida: não é fornecido nenhum conversational_text_response. A sua interface Web tem de apresentar alguma mensagem padrão, links relevantes ou redirecionar a consulta para o seu próprio localizador de lojas ou sistema de informações.
  • RETAIL_SUPPORT:
    • Ação predefinida: não é fornecido nenhum conversational_text_response. A sua interface Web tem de apresentar alguma mensagem padrão, links relevantes ou redirecionar a consulta para o seu próprio sistema de informações e perguntas frequentes.

Categoria 3. Pesquisas por palavras-chave que não requerem respostas de MDIs

  • SIMPLE_PRODUCT_SEARCH:
    • Não é gerada nenhuma resposta de texto conversacional.
    • Ação: a resposta da API devolve sempre uma única consulta refined_search. Esta consulta refinada funciona como um termo de pesquisa sugerido. Faça uma chamada direta à API Search principal (SearchService.Search) e obtenha resultados de produtos relevantes com a consulta original ou a consulta refined_search. A refined_search.query pode não ser diretamente da entrada do utilizador final atual, mas também pode ser derivada do contexto do histórico do chat. Por exemplo, se um utilizador final tiver refinado anteriormente vestido de festa para vermelhos, a consulta refinada pode tornar-se vestido de festa vermelho.
      • Para interfaces conversacionais (como chatbots): é altamente recomendável usar o refined_search.query fornecido pela API. Num fluxo de conversa, as consultas em linguagem natural, como "podes ajudar-me a encontrar bananas", são automaticamente otimizadas pela API para um termo de pesquisa de produto preciso ("bananas"), o que leva a resultados de produtos mais relevantes.
      • Para experiências de pesquisa essenciais (como a página de resultados da pesquisa): tem a flexibilidade de usar o refined_search.query da API ou a consulta original fornecida pelo utilizador final, porque é mais provável que a consulta original já seja um termo de pesquisa de produtos preciso. Escolha a opção que melhor se adequa à sua interface Web e estratégia de apresentação de resultados da pesquisa.
    • Opções de experiência do utilizador: a conversa não tem de terminar para SIMPLE_PRODUCT_SEARCH consultas. O utilizador pode continuar a conversa transmitindo o conversation_id em pedidos subsequentes.
      • Opção A: terminar a interface Web conversacional: muitos retalhistas optam por fazer a transição do utilizador para uma página de resultados da pesquisa padrão assim que é detetado um SIMPLE_PRODUCT_SEARCH, fechando efetivamente a janela de chat. Neste cenário, se o utilizador final introduzir uma nova consulta na caixa de pesquisa padrão sem o conversation_id anterior, é tratada como uma conversa nova e separada, e é emitido um novo conversation_id.
      • Opção B: continuar com a interface Web de conversação: os retalhistas podem optar por manter a janela de chat aberta. Isto permite que o utilizador regresse a um modo de conversação. A decisão de implementar a opção A ou B depende inteiramente da experiência do utilizador preferida do retalhista.

    Para atribuir com precisão as consultas de pesquisa a interações conversacionais e usar as capacidades de análise completas na Vertex AI Search for commerce, a etiquetagem de eventos adequada é crucial:

    1. Recuperar conversation_id. Quando faz uma chamada API conversationalSearch, é devolvido o ConversationalSearchResponse.conversation_id.
    2. Etiquete eventos de utilizadores. Nos casos em que a resposta conversacional leva a uma consulta de pesquisa, como se o seu sistema executar automaticamente uma pesquisa com base na consulta refinada para SIMPLE_PRODUCT_SEARCH, tem de etiquetar esse evento de utilizador de pesquisa subsequente (UserEvent) com o mesmo conversation_id recebido no ConversationalSearchResponse.

Ao etiquetar corretamente UserEvent.conversation_id, a sua análise pode atribuir com precisão as consultas de pesquisa às interações de conversa anteriores, fornecendo estatísticas valiosas sobre o comportamento e os caminhos de conversão dos utilizadores.

Categoria 4. Consultas de procura de respostas de MDIs/CEs

Para estes tipos de consultas, a API gera uma conversational_text_response (resposta do MDI/CE) e também pode fornecer uma ou mais consultas refined_search. A conversa não termina e o utilizador final pode continuá-la.

  • PRODUCT_DETAILS:
    • Ação: o conversational_text_response fornece os detalhes do produto pedidos. O seu sistema deve apresentar estas informações de forma clara ao utilizador.
    • A resposta também inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para obter resultados da pesquisa através da API Search principal.
  • PRODUCT_COMPARISON:
    • Ação: o conversational_text_response apresenta uma comparação dos produtos especificados. O seu sistema deve apresentar estas informações de forma clara ao utilizador.
    • A resposta inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para obter resultados da pesquisa através da API Search principal.
  • BEST_PRODUCT:
    • Ação: o conversational_text_response fornece recomendações ou informações sobre os produtos que melhor correspondem à consulta. O seu sistema deve apresentar estas informações.
    • A resposta inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para obter resultados da pesquisa através da API Search principal.

Categoria 5. Refinamento de intenção

  • INTENT_REFINEMENT:
    • Ação: a resposta inclui conversational_text_response, um followup_question e refined_search (uma ou mais consultas de pesquisa sugeridas). A ordem de apresentação recomendada é a seguinte:
      1. conversational_text_response
      2. Sugestões refined_search: estas são ordenadas e classificadas, pelo que é importante apresentá-las na mesma ordem que a resposta.
      3. Followup_question
    • A resposta inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para obter resultados da pesquisa através da API Search principal.
    • Para interações subsequentes, envie a resposta do utilizador juntamente com o conversation_id.

Mostrar consultas sugeridas para produtos

Veja como configurar a Pesquisa Google para apresentar perguntas e sugestões de produtos no agente de comércio conversacional.

Quando a API Conversacional devolve consultas de refinedSearch, estas consultas representam excelentes oportunidades para orientar o utilizador final para produtos relevantes. Isto é particularmente valioso para a categoria 4 (consultas que procuram respostas de MDIs/CEs) e a categoria 5 (INTENT_REFINEMENT).

Recomendação

  • Apresentação: apresente as N principais (1 a 3, teste pendente sobre o número ideal para a sua interface Web) refinedSearch consultas ao utilizador.
  • Mecanismo: estas consultas sugeridas devem ser executadas através da API Search principal (SearchService.Search) em segundo plano ou após a interação do utilizador.
  • Apresentação: mostre os resultados como carrosséis interativos ou cartões clicáveis, permitindo que o utilizador explore categorias de produtos relacionadas ou itens específicos. Isto oferece valor imediato e ajuda a colmatar a lacuna entre a interação conversacional e a descoberta de produtos.

Pedido de API de pesquisa:

Consulta de seguimento

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Decorations",
  "visitorId": "test"
}

Eventos a enviar para o Vertex AI Search for commerce

É importante atribuir com precisão as consultas de pesquisa às interações conversacionais e usar as capacidades de análise completas na Vertex AI Search para comércio através da etiquetagem de eventos adequada:

  1. Recuperar conversation_id. Quando faz uma chamada API conversationalSearch, é devolvido o ConversationalSearchResponse.conversation_id.
  2. Etiquete eventos de utilizadores. Nos casos em que a resposta conversacional leva a uma consulta de pesquisa, como a apresentação de uma sugestão refined_search na qual o utilizador final clica, ou se o seu sistema executar automaticamente uma pesquisa com base na consulta refinada, tem de etiquetar esse evento de utilizador de pesquisa subsequente (UserEvent) com o mesmo conversation_id recebido no ConversationalSearchResponse.

Ao etiquetar corretamente UserEvent.conversation_id, a sua análise pode atribuir com precisão as consultas de pesquisa às interações de conversa anteriores, o que fornece estatísticas valiosas sobre o comportamento do utilizador e os caminhos de conversão.

Continue a conversa

Esta secção descreve como as sessões de agentes de comércio conversacional são mantidas pela API Conversational e continuam neste passo final.

A API de conversação usa um conversation_id para gerir conversas em curso. Para garantir a consistência entre as respostas do MDG e os resultados da pesquisa, os pedidos Conversational API subsequentes têm de incluir SearchParams que reflitam a configuração das chamadas API Search principais.

Processamento de sessões

  • Inicie uma nova conversa:
    • Descrição: para iniciar uma nova conversa, o cliente omite o conversationId do pedido da API.
    • Quando iniciar uma nova conversa: um cliente quer iniciar uma nova conversa, recebendo assim um novo conversationId da resposta da API, em vários cenários comuns da experiência do utilizador:
      • Novo separador ou sessão: quando um cliente abre o seu site num novo separador do navegador ou inicia uma sessão completamente nova.
      • Nova consulta original: em alguns designs de UX, se um cliente introduzir uma consulta nova e não relacionada, pode optar por reiniciar o fluxo de conversa para garantir o contexto mais relevante.
      • Botão Reiniciar conversa: se a sua interface Web fornecer um botão explícito Iniciar novo chat ou Repor conversa, clicar neste botão aciona uma nova sessão de conversa.
    • Integração da API de conversação: a resposta da API inclui um novo conversationId que é usado para pedidos subsequentes.
  • Continuar a conversa:
    • Descrição: o elemento Conversational API devolve um elemento conversation_id como parte da resposta da API. Este ID tem de ser enviado em pedidos de seguimento para continuar a mesma conversa. Isto ajuda a garantir que o agente de comércio conversacional responde às consultas do utilizador com base no histórico de conversas nessa sessão, abrangendo o utilizador final query, o conversational_text_response e o followup_question.
    • Integração da API de conversação: o cliente transmite o conversation_id da resposta anterior no ConversationalSearchRequest.
  • Garanta a consistência dos resultados da pesquisa:
    • Description: para ajudar a garantir que as respostas do MDG são consistentes com os resultados da pesquisa apresentados ao utilizador, o cliente tem de usar searchParams no pedido Conversational API. Estes parâmetros de pesquisa devem ter a mesma configuração, como filtros e ordem de ordenação, que as chamadas Search API feitas para obter resultados de produtos.
    • Integração da API de conversação: o objeto searchParams no ConversationalSearchRequest deve ser preenchido de forma idêntica ao SearchRequest usado para a pesquisa de produtos principal.

Envie um pedido para o Vertex AI Search for commerce

Pode obter o conversation_id do armazenamento da sessão. O pedido deve incluir o novo cliente query, que pode ser uma resposta à pergunta da resposta anterior. O pedido também deve incluir o refined_search.query mais recente da resposta anterior se o utilizador final estiver a agir com base numa consulta refinada. Caso contrário, deve incluir uma consulta completamente nova e não relacionada, bem como o conversationId. Lembre-se de incluir sempre searchParamsconsistentes.

  • Cenário 1: uma única barra de pesquisa e uma conversa persistente: se a sua interface de pesquisa tiver apenas uma barra de pesquisa principal ou uma janela de conversa persistente, não repõe o conversationId, mesmo que o utilizador final escreva uma consulta nova e aparentemente não relacionada. O sistema usa o histórico de conversas existente (associado ao conversationId) para fornecer respostas contextualmente relevantes.
  • Cenário 2: janela de conversa e janela de consulta separadas: se a sua interface de pesquisa fornecer uma janela de chat de conversa distinta e uma barra de consulta de pesquisa padrão separada (como uma caixa de pesquisa em todo o site), introduzir uma nova consulta na barra de pesquisa padrão pode sinalizar implicitamente uma intenção de iniciar uma nova pesquisa não relacionada, o que pode levar à reposição do conversationId para essa ação de pesquisa específica. No entanto, na janela de conversa dedicada, o conversationId deve ser sempre mantido para garantir a continuidade.

Em última análise, a decisão sobre quando reutilizar ou repor o conversationId é uma escolha de design para otimizar a experiência de conversa para os seus clientes.

Método HTTP e ponto final (igual à consulta inicial)

POST https://retail.googleapis.com/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch

Pedido de API de conversação:

Consulta de seguimento

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {
    "filter": "categories:(\"Birthday Party Supplies\")"
  }
}

Resposta da API de conversação:

Resposta de seguimento

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

Exemplos de um utilizador final que continua a receber perguntas:

  • Pergunta do utilizador: Ajuda-me a planear uma festa.
  • Resposta do sistema: Que tipo de festa está a planear?
  • Resposta do utilizador: Uma festa de aniversário.

O que os retalhistas devem fazer com a resposta

A forma de renderizar campos é semelhante à da resposta inicial, mas tenha em atenção as alterações que refletem a conversa contínua:

  • refined_search: este campo contém consultas atualizadas que incorporam a entrada mais recente do utilizador final. Deve atualizar a consola do cliente para a consulta atual em conformidade (por exemplo, mostrar que a consulta visível para o utilizador mudou de "decorações" para "decorações para festas de aniversário" ou "artigos para festas de aniversário"). As consultas refined_search podem ser usadas para chamadas à API Search principal (SearchService.Search) ou também podem ser apresentadas ao utilizador final como sugestões.
  • conversational_text_response: apresentar a nova resposta de texto gerada pela IA relevante para a interação mais recente.
  • followup_question: se a conversa precisar de continuar para um maior refinamento, é fornecido um novo followup_question.

Eventos a enviar para o Vertex AI Search for commerce

A etiquetagem de eventos é importante para atribuir com precisão as consultas de pesquisa a interações conversacionais e usar as capacidades de estatísticas na Vertex AI Search for commerce.

Existem dois passos no processo de etiquetagem de eventos:

  1. Recuperar conversation_id. Quando faz uma chamada API conversationalSearch, é devolvido o ConversationalSearchResponse.conversation_id.

  2. Etiquete eventos de utilizadores. Nos casos em que a resposta conversacional leva a uma consulta de pesquisa, como a apresentação de uma sugestão refined_search, ou se o seu sistema executar automaticamente uma pesquisa com base na consulta refinada, tem de etiquetar esse evento de utilizador de pesquisa subsequente (UserEvent) com o mesmo onversation_id recebido no ConversationalSearchResponse.

Ao etiquetar corretamente UserEvent.conversation_id, a sua análise pode atribuir com precisão as consultas de pesquisa às interações de conversa anteriores, fornecendo estatísticas valiosas sobre o comportamento do utilizador final e os caminhos de conversão.

Integre o agente com a filtragem de produtos conversacional

Este guia descreve como fazer a integração com a API Conversacional e a filtragem de produtos conversacional para oferecer uma experiência de compras com tecnologia de IA. Quando conversationalFilteringSpec.mode está definido como ENABLED, o seu sistema pode fazer a transição direta entre interações conversacionais abertas e filtragem de produtos guiada, oferecendo um percurso do utilizador altamente refinado.

Compreenda a interação

Quando o agente de comércio conversacional e a filtragem de produtos conversacional estão ativados, o sistema tira partido das vantagens de cada um. O agente de comércio conversacional processa consultas gerais, fornece respostas geradas pela IA e refina as intenções iniciais, enquanto a filtragem conversacional de produtos orienta os utilizadores através de seleções de atributos de produtos específicos com um modelo de interação simplificado baseado em chips ou mosaicos.

O ponto de interação e potencial transição entre estes dois modos ocorre quando a classificação da API Conversational Commerce leva a uma pesquisa orientada para produtos, especificamente SIMPLE_PRODUCT_SEARCH. Neste ponto, a API pode fornecer uma consulta de pesquisa direta ou, se a intenção do utilizador puder ser refinada, aciona um fluxo de filtragem guiada através da filtragem de produtos conversacional.

Um princípio fundamental desta integração é que toda a entrada de texto livre é processada pela API Conversational Commerce, enquanto os cliques em respostas sugeridas que aparecem como chips são processados pela filtragem de produtos conversacional.

Envie uma consulta do utilizador

Exemplo de entrada do utilizador: ajuda-me a planear uma festa

Para ativar o agente de comércio conversacional e a filtragem de produtos conversacional, certifique-se de que o seu ConversationalSearchRequest inclui esta configuração:

Pedido da API Conversational Commerce: consulta inicial

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query, or populate for ongoing conversation
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your Commerce Search API calls to ensure consistency.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
  },
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED" // Crucial for enabling product filtering
  }
}

As principais configurações são:

  • Conversational_filtering_mode: ENABLED: definir este campo como ENABLED no seu conversationalFilteringSpec informa a API de que o seu sistema pode processar a filtragem de produtos conversacional, o que permite à API fornecer respostas relevantes específicas da filtragem.

Resposta inicial: refinamento da intenção

O campo userQueryTypes continua a ser fundamental para compreender a intenção do utilizador. Para uma consulta ampla inicial, como Ajuda-me a planear uma festa, a API vai classificá-la como INTENT_REFINEMENT se não for imediatamente claro que se trata de uma pesquisa de produtos mais específica.

Resposta da Google

Resposta da API Conversational Commerce: consulta inicial

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}

Ação

  1. Apresentar o conversationalTextResponse.
  2. Apresentar as sugestões refinedSearch como chips clicáveis para Decorações, Snacks. Em alternativa, chame a API Commerce Search em paralelo usando as consultas refined_search para apresentar resultados de produtos relevantes, como Decorações, Snacks, como um carrossel, juntamente com a troca de mensagens conversacional.
  3. Apresentar o followupQuestion: que tipo de festa está a planear?
  4. Permitir a introdução de texto livre pelo utilizador para avançar na conversa.

Etiquetagem de eventos e estatísticas

Para garantir estatísticas e atribuição precisas para a interação de conversa inicial:

  • Recuperar conversation_id. Capture o conversation_id a partir do ConversationalSearchResponse. Este ID é fundamental para associar todas as ações subsequentes a esta sessão de conversa específica.
  • Etiquete eventos de utilizadores. Se a resposta conversacional originar uma consulta de pesquisa, como o seu sistema executar automaticamente uma pesquisa com base numa consulta refined_search, ou se o utilizador clicar numa sugestão refined_search, tem de etiquetar esse evento de utilizador de pesquisa subsequente (UserEvent) com o mesmo conversation_id.

Consulta de seguimento

Quando o utilizador responde ao followupQuestion, a conversa é refinada.

Exemplo de introdução do utilizador: Uma festa de aniversário

Refinamento da intenção | Fragmentos do código

Pedido de API Conversational Commerce: consulta de seguimento

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Resposta da API Conversational Commerce: consulta de seguimento

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

Ação

  1. Tal como na resposta inicial, atualize a interface Web com as novas sugestões conversationalTextResponse, refinedSearch e followupQuestion.
  2. Continuar o fluxo da conversa, pedindo mais detalhes.

Etiquetagem de eventos e estatísticas

Quando o utilizador continua a conversa:

  • Recuperar conversation_id. Certifique-se de que o conversation_id do ConversationalSearchResponse anterior é transmitido no ConversationalSearchRequest atual.
  • Etiquete eventos de utilizadores. Se a resposta conversacional originar uma nova consulta de pesquisa, por exemplo, devido a um utilizador clicar numa sugestão refined_search ou o seu sistema fazer uma chamada de pesquisa paralela, etiquete esse evento de utilizador de pesquisa subsequente (UserEvent) com o mesmo conversation_id. Isto ajuda a acompanhar o percurso conversacional de várias interações.

Transição para a filtragem de produtos conversacional

À medida que a conversa se torna mais específica, o sistema pode classificar a intenção como SIMPLE_PRODUCT_SEARCH e, se for adequado, acionar a filtragem de produtos conversacional.

Exemplo de entrada do utilizador: tema de princesas

Pedido de API Conversational Commerce: consulta de seguimento

{
  "query": "Princess theme",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Quando uma consulta é classificada como SIMPLE_PRODUCT_SEARCH, existem duas respostas possíveis da API, consoante o acionamento ou não da filtragem de produtos conversacional. A principal diferença reside na presença e no conteúdo do campo conversationalFilteringResult.

Resultado 1: a filtragem é acionada

Isto ocorre quando a consulta é suficientemente essencial para ser refinada ainda mais por atributos do produto. A resposta inclui conversationalFilteringResult, que a sua interface Web deve priorizar.

Resposta da API Conversational Commerce: transição para a filtragem de produtos: 

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday decorations" }
  ],
  "conversationalFilteringResult": {
    "followupQuestion": "What specific type of princess decoration are you looking for?",
    "suggestedAnswers": [
      { "answer": "Balloons", "query": "princess birthday balloons" },
      { "answer": "Streamers", "query": "princess birthday streamers" },
      { "answer": "Tablecloths", "query": "princess birthday tablecloths" }
    ]
  },
  "state": "SUCCEEDED"
}

Ação

A consulta foi classificada como SIMPLE_PRODUCT_SEARCH. Neste caso, aciona a filtragem de produtos conversacional. No entanto, pode não acionar a filtragem de produtos conversacional.

  • Dê prioridade à interface Web de filtragem de produtos conversacional:quando conversationalFilteringResult está preenchido, indica que entrou no modo de filtragem de produtos. A sua interface Web deve realçar o followupQuestion, que aparece na interface do utilizador como algo semelhante a Que tipo específico de decoração de princesa procura?, e o suggestedAnswers, como botões clicáveis para Balões, serpentinas e toalhas de mesa.
  • Apresentar resultados de produtos: chame imediatamente a API Retail Search com o termo de pesquisa refined_search.query (decorações de aniversário de princesa) para apresentar os resultados de produtos iniciais juntamente com as opções de filtragem.
  • Prática recomendada de experiência do utilizador: deve existir uma única barra de introdução de texto livre persistente para toda a experiência. Esta barra permanece ativa em todos os momentos, inclusive durante um fluxo de filtragem de produtos conversacional. Quando o conversationalFilteringResult está ativo e apresenta respostas sugeridas como chips clicáveis, os utilizadores têm duas opções claras:
    • Continue o fluxo de filtragem clicando numa resposta sugerida.
    • Inicie uma nova interação conversacional escrevendo uma nova consulta na barra de texto ativa. Esta nova entrada aciona sempre uma nova chamada para a API Conversational Commerce, terminando efetivamente o fluxo de filtragem atual.

Resultado 2: não é acionada qualquer filtragem

Se a consulta já for suficientemente específica ou não se adequar a uma filtragem adicional, a resposta não inclui o campo conversationalFilteringResult. Neste caso, deve continuar com uma pesquisa padrão.

Ação

  • Trate a interação como o fim do fluxo de conversa e use a consulta refined_search para chamar a API Retail Search e apresentar uma página de resultados de produtos padrão.

Etiquetagem de eventos e estatísticas

Quando a conversa passa para a filtragem de produtos:

  • Recuperar conversation_id. Continuar a usar o mesmo dispositivo conversation_id.
  • Etiquete eventos de utilizadores. Se a transição levar a uma pesquisa imediata, etiquete-a com UserEvent e conversation_id. É importante referir que, quando o utilizador interage com o suggestedAnswers, por exemplo, quando um utilizador final clica em Balões, esta ação também deve acionar um UserEvent, como um evento filter ou um novo evento search, que esteja etiquetado com o mesmo conversation_id. Isto permite a atribuição de ações de filtragem no fluxo de conversa.

Continue a filtragem de produtos conversacional

Quando o utilizador seleciona um suggestedAnswer, envie um novo ConversationalSearchRequest.

Exemplo de entrada do utilizador (clicar numa resposta sugerida): Balões

Pesquisa simples de produtos | Fragmentos do código

Pedido da API Conversational Commerce: continuar a filtrar 

{
  "query": "Balloons", // The selected answer
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // Maintain conversation ID
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Resposta da API Conversational Commerce: continuar a filtrar 

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday balloons" }
  ],
  "state": "SUCCEEDED"
}

Ação

A API responde com uma consulta SIMPLE_PRODUCT_SEARCH, mas sem o campo conversationalFilteringResult, o que indica que o fluxo de filtragem guiada foi concluído.

  • Use a refinedSearchconsultafinal(princess birthday balloons) para fazer uma chamada direta à API Retail Search.
  • Apresentar os resultados finais dos produtos ao utilizador. Neste ponto, a conversa pode terminar ou o utilizador pode introduzir uma nova consulta para iniciar uma nova interação.

Etiquetagem de eventos e estatísticas

Para cada passo no processo de filtragem de produtos:

  • Recuperar conversation_id. Use sempre o mesmo conversation_id para todos os pedidos na sessão de filtragem.
  • Etiquete eventos de utilizadores. Cada interação do utilizador com um suggestedAnswer, como um clique, deve acionar um UserEvent relevante, como um evento filter ou um novo evento search se for formulada uma nova consulta. Esta UserEvent tem de ser etiquetada com o conversation_id para acompanhar com precisão o percurso de filtragem e o respetivo impacto na conversão.

Arquitetura de referência

Este é o design arquitetónico de referência do Vertex AI Search for commerce no Google Cloud. Esta arquitetura de referência representa o fluxo de dados e serviços para um agente de comércio conversacional. O diagrama mostra como os eventos do utilizador, os dados do catálogo de produtos e os registos operacionais são processados, transformados e integrados num índice de IA generativa e num serviço de adaptador de retalho para processar operações de pesquisa e satisfazer as intenções do utilizador para devolver resultados da pesquisa. A arquitetura liga vários projetos para permitir uma funcionalidade de pesquisa de comércio abrangente baseada em IA.

Arquitetura de referência da IA de comércio

O que se segue?

Para recursos de apoio técnico adicionais, consulte as respostas a perguntas sobre as funcionalidades de conversação.