Receber resultados da pesquisa

Esta página descreve as consultas básicas com a pesquisa, incluindo pesquisas de consulta de texto, pesquisas de navegação, paginação, otimização e resultados personalizados.

Identificadores de sessão de usuário único

O campo de string visitor_id obrigatório é usado para identificar exclusivamente um usuário em um único dispositivo. Ele funciona como um identificador de sessão persistente que permite que a Vertex AI para Pesquisa em E-commerce rastreie o comportamento de um usuário específico durante a jornada de compras.

A Vertex AI para Pesquisa em E-commerce usa o histórico associado a um visitor_id específico para treinar modelos e veicular resultados de pesquisa personalizados. O sistema gera resultados dinamicamente com base no visitor_id específico fornecido na solicitação. Por exemplo, se um visitante costuma visualizar vestidos verdes, o modelo usa visitor_id para reconhecê-lo mais tarde e priorizar itens semelhantes nos resultados da pesquisa. Por esse motivo, o ID do visitante precisa ser formatado de maneira idêntica no processamento de eventos do usuário (rastreamento) e nas solicitações de pesquisa ou recomendação (veiculação).

Relevância na pesquisa em e-commerce

A relevância é diferente da correspondência. A correspondência é encontrar produtos candidatos no índice que correspondam à consulta de pesquisa do usuário. A relevância, por outro lado, é um grau de correspondência. Ela envolve a classificação desses produtos de uma maneira que melhor satisfaça a intenção e as necessidades do usuário. A Vertex AI para Pesquisa em E-commerce usa técnicas para melhorar a correspondência e a relevância para uma experiência de pesquisa geral melhor para os usuários que atende às necessidades dos varejistas.

Pesquisa padrão

A pesquisa é definida como relevância. No entanto, alguns produtos não relevantes podem aparecer na parte de baixo das pesquisas padrão ou em solicitações explícitas de descoberta de produtos. Isso só se torna perceptível quando você define orderBy, porque ele reduz o tamanho dos resultados da pesquisa em geral. O tamanho do recall diminui porque os produtos menos relevantes, que antes eram retornados na parte de baixo da pesquisa padrão, são filtrados até certo ponto. Leia a próxima seção para saber como personalizar a pesquisa.

Pesquisa não padrão

A Vertex AI para Pesquisa em E-commerce é definida como relevância na pesquisa. No entanto, a pesquisa também é ajustada para mostrar itens marginalmente relevantes mais acima nos resultados da pesquisa para oferecer aos varejistas resultados de pesquisa mais segmentados para aumentar o potencial de conversão de eventos do usuário.

Esses recursos de pesquisa adicionados otimizam o algoritmo de relevância padrão, fornecendo recursos não padrão ajustados ao perfil de utilização de cada varejista, incluindo:

Opções para classificar os resultados, como por preço, mais bem avaliados ou mais vendidos. A pesquisa não padrão é personalizada para retornar resultados de pesquisa específicos com as variantes de produto corretas. Por exemplo, para mostrar a variante mais barata ou mais cara ao classificar por preço.
Aplicação automática de um filtro de relevância mais restrito para eventos de usuário não padrão.
Ativação de controles de aumento/diminuição de força ajustáveis para ajustar os resultados da pesquisa.

Pesquisa de texto e pesquisa de navegação

A pesquisa oferece recursos de pesquisa de consulta de texto e pesquisa de navegação.

No caso de uso de pesquisa de consulta de texto, um comprador pode inserir uma consulta baseada em texto no seu site. A pesquisa retorna uma resposta de pesquisa contendo produtos que se encaixam nos parâmetros dos controles configurados, classificados por relevância e maximização de receita.

No caso de uso de navegação, um comprador pode acessar o menu do seu site e navegar até uma categoria dos produtos específica. A pesquisa escolhe automaticamente a ordem de classificação que maximiza a receita, aprendendo com o comportamento e as tendências do usuário. Os resultados da navegação podem ser ainda mais refinados pelos controles configurados.

As solicitações de pesquisa de texto e de navegação usam o servingConfigs.search método.

Pesquisas de consulta de texto

Quando um usuário insere uma consulta de texto para pesquisar no seu site, a pesquisa classifica os possíveis resultados da pesquisa com base na relevância, popularidade, capacidade de compra e personalização.

A pesquisa considera uma solicitação servingConfigs.search como uma solicitação de pesquisa baseada em texto se ela tiver um campo query não vazio.

Ao fazer o upload de eventos do usuário, envie eventos de pesquisa de consulta de texto gerados pela pesquisa como eventos de usuário search. Se o evento tiver um campo userEvent.searchQuery não vazio e um campo userEvent.pageCategories vazio, a pesquisa o considerará um evento de pesquisa baseado em texto.

Como processar consultas e parâmetros de texto

As consultas padrão passam por uma análise linguística, que remove a pontuação padrão. As strings de filtro diferenciam maiúsculas de minúsculas. Entender como processar consultas e parâmetros de texto é fundamental para criar solicitações de API na Vertex AI para Pesquisa em E-commerce corretamente.

Tokenização e pontuação de consultas: o texto de linguagem natural transmitido para o campo query passa por análise linguística automática e correção ortográfica. Durante esse processo, a pontuação padrão (como vírgulas, pontos, + ou -) geralmente é removida ou ignorada para otimizar a compreensão da linguagem natural.
Sensibilidade a maiúsculas e minúsculas estrita em parâmetros: embora as consultas de texto padrão geralmente não diferenciem maiúsculas de minúsculas, os parâmetros programáticos diferenciam.
- Filtros: as expressões de filtro e os valores de string literal diferenciam maiúsculas de minúsculas.
- Classificação: a expressão orderBy diferencia maiúsculas de minúsculas. Se você classificar por um campo como products.title, o mecanismo vai classificar Apple antes de banana e artichoke. Uma solução alternativa é fazer o upload dos títulos dos produtos em letras maiúsculas para um atributo personalizado separado (como attributes.title_upper) e classificar esse atributo para conseguir uma classificação que não diferencia maiúsculas de minúsculas.
Caracteres especiais reservados:
- O caractere > é estritamente reservado como o delimitador para hierarquias de categorias (como Categories > Shoes). Se > ocorrer naturalmente no nome da categoria, substitua-o por outro caractere antes da ingestão e da consulta.
- O caractere / não é compatível com valores textuais em expressões de filtro de recomendação.

Pesquisas de navegação

A navegação usa a navegação do site para produzir resultados de pesquisa de relevância igual classificados por itens mais vendidos. A pesquisa aproveita a IA para otimizar a classificação dos resultados da navegação, considerando a popularidade, a capacidade de compra e a personalização.

Para receber os resultados de pesquisa de navegação corretos, considere o seguinte:

Os valores pageCategories e filter nas suas solicitações de pesquisa precisam corresponder exatamente aos valores pageCategories e filter nos eventos do usuário enviados. Se os parâmetros nas solicitações não corresponderem aos parâmetros nos eventos, o modelo de reclassificação baseado em cliques aprendido com os eventos não terá uma performance muito boa para essa consulta específica e afetará negativamente a qualidade do resultado.
A Vertex AI para Pesquisa em E-commerce categoriza um evento de usuário search como um evento baseado em navegação se ele tiver um campo userEvent.searchQuery vazio e um campo userEvent.pageCategories não vazio. É por isso que você precisa enviar eventos de navegação gerados pela Vertex AI para Pesquisa em E-commerce como eventos de usuário search ao fazer o upload deles.
Um filtro de navegação precisa ser válido e indicar para cada consulta de navegação quais produtos pertencem à categoria dos produtos em que o usuário está navegando. Para conseguir essa configuração, o ID da categoria precisa ser definido nos campos filter e page_category. Por exemplo, se você quiser que os resultados da pesquisa sejam segmentados para Casa e Jardim. Primeiro, ter apenas um valor filter de "in-stock" não refina a pesquisa o suficiente para fornecer resultados de navegação ideais. Para fornecer resultados de pesquisa restritos a Casa e Jardim, você não só precisa definir "Home \& Garden" na categoria de página, mas também no filtro com categories: ANY("Home & Garden"). Se você não definir a categoria na parte do filtro, os resultados da navegação provavelmente serão muito amplos e incluirão muitos itens que não são de Casa e Jardim.

As solicitações e eventos de veiculação com um campo de consulta vazio e campos page_categories preenchidos são considerados solicitações de navegação e eventos do usuário. O campo page_categories especifica a própria página Procurar. Quando o método servingConfigs.search envia uma solicitação, a pesquisa a considera uma solicitação de pesquisa de navegação se o campo query estiver vazio. Nesse caso, os resultados são baseados nos campos filter e pageCategories e, se disponível, mais otimização e personalização.

É possível definir a categoria nos dois, como neste exemplo:

JSON

page_category: "Home & Garden"
filter: "(availability: ANY("IN_STOCK")) AND (categories: ANY("Home & Garden"))"

Caso contrário, como a navegação funciona com consultas de string vazias, os produtos em uma determinada categoria não serão exibidos automaticamente nos resultados de uma determinada categoria de página. Em outras palavras, se o usuário final navegar sem especificar nada usando uma consulta de texto, o retorno da pesquisa poderá não gerar resultados segmentados de maneira eficaz, mesmo que o usuário navegue até uma página de categoria.

Usar solicitações de pesquisa

Use solicitações de pesquisa para receber resultados de pesquisas de texto e de navegação. Para fazer uma solicitação de pesquisa, use o servingConfigs.search método.

Todas as solicitações de pesquisa exigem placement, que identifica o nome completo do recurso da configuração de veiculação que será usada. A configuração de veiculação determina quais configurações e controles associados afetam os resultados da pesquisa.

As solicitações de pesquisa de consulta de texto exigem um campo query não vazio.

As solicitações de pesquisa de navegação exigem um campo pageCategories não vazio.

Java

import com.google.cloud.retail.v2.SearchRequest;
import com.google.cloud.retail.v2.SearchResponse;
import com.google.cloud.retail.v2.SearchServiceClient;

public static void searchProducts(String query) throws IOException, InterruptedException {
  SearchRequest searchRequest = SearchRequest.newBuilder()
      .setPlacement(DEFAULT_SEARCH_PLACEMENT_NAME)
      .setBranch(DEFAULT_BRANCH_NAME)
      .setVisitorId(VISITOR_ID)
      .setQuery(query)
      .build();

  try (SearchServiceClient searchClient = SearchServiceClient.create()) {
    SearchResponse response = searchClient.search(searchRequest).getPage().getResponse();
    System.out.println("Search response: " + searchResponse);
  }
}

Por padrão, um número razoável de resultados ordenados por relevância é retornado.

Para receber atributos de produto retornados com a resposta da pesquisa, forneça valores de atributo ao importar os dados do catálogo. O Product tem atributos de sistema predefinidos, como marca, cor e tamanho, para os quais você pode fornecer valores. Também é possível incluir atributos personalizados definidos com Product.attributes.

Tutorial de consultas

Este tutorial mostra como enviar uma consulta de pesquisa baseada em texto para o serviço da Vertex AI para Pesquisa em E-commerce e analisar a resposta.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientações:

Orientações

Filtrar resultados da pesquisa usando sugestões de preenchimento automático

Se você implementou sugestões de preenchimento automático enriquecidas no front-end (em que os usuários podem selecionar uma consulta combinada com uma marca ou categoria específica), é necessário traduzir essa seleção em um SearchRequest filtrado.

Para implementar isso, extraia a sugestão de texto e coloque-a no campo query e extraia o atributo selecionado (como uma marca) e formate-o como uma expressão no campo filter.

Exemplo de solicitação de pesquisa de uma sugestão filtrada

Se o usuário clicou na sugestão sapato em Nike, estruture o SearchRequest da seguinte maneira:

{
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "shoe",
  "filter": "brands: ANY(\"Nike\")",
  "visitorId": "user_session_123"
}

Adicionar contagens de produtos aos atributos de sugestão

Para melhorar ainda mais a experiência de filtragem, é possível mostrar o número de produtos disponíveis para cada filtro de sugestão antes que o usuário execute a pesquisa. Para usar atributos de sugestão com contagens de produtos, entre em contato com o suporte para ativar o recurso. Quando ativado, inclua a chave de atributo textual específica nos facetSpecs do seu SearchRequest por pelo menos sete dias para permitir que o sistema calcule as contagens de produtos com base nos dados do histórico de pesquisa.

Paginação

Use a paginação para diminuir o tempo de pesquisa e o tamanho das respostas enviadas.

Tutorial de paginação

Este tutorial mostra como controlar a paginação em uma solicitação de pesquisa baseada em texto. Quando um comprador procura produtos em uma loja, ele pode melhorar a navegação pelos resultados da pesquisa. Por exemplo, é possível limitar o número de itens na resposta da pesquisa usando o recurso de tamanho da página ou pular para a página preferida usando o recurso de deslocamento.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientações:

Orientações

Paginar

Para pular de uma página para outra, use page_token ou offset, de acordo com seu caso de uso.

Para acessar a próxima página, use page_token. Por exemplo, suponha que você envie a SearchRequest a seguir.

JSON

{
  placement: 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/placements/default_search'
  visitor_id: 'VISITOR_ID'
  query: 'shoes'
  page_size: 5
}

A partir de SearchResponse, é possível conseguir os produtos resultantes com cinco principais relevâncias, além de um next_page_token.

JSON

{
  results: [
    products{...}, products{...}, products{...}, products{...}, products{...}
  ]
  next_page_token: "wY4ETNkBDOlVjZ0YWLzUmM40SMhVjMtADMwATL5UGN5MGZlVDJaIQ5LaYsQUw9fC6lIwgE1EgC"
  total_size: 100
  search_token: "NtQKDAiXt4_3BRDCg_jnARABGiQ1ZWRjOTRlOC0wMDAwLTI1YTEtODJlMy1mNGY1ZTgwZDUxOGM"
}

Para conseguir os produtos de resultado com os próximos cinco valores (de 6º a 10º), você precisa definir page_token usando o mesmo placement, visitor_id, e query como next_page_token da SearchResponse anterior de dados.

Java

import com.google.cloud.retail.v2.SearchRequest;
import com.google.cloud.retail.v2.SearchResponse;
import com.google.cloud.retail.v2.SearchServiceClient;

public static void searchProducts_withNextPageToken(String query, int pageSize)
    throws IOException, InterruptedException {
  try (SearchServiceClient searchClient = SearchServiceClient.create()) {
    SearchRequest firstRequest = SearchRequest.newBuilder()
        .setPlacement(DEFAULT_SEARCH_PLACEMENT_NAME)
        .setBranch(DEFAULT_BRANCH_NAME)
        .setVisitorId(VISITOR_ID)
        .setQuery(query)
        .setPageSize(pageSize)
        .build();

    SearchResponse firstResponse = searchClient.search(firstRequest).getPage()
        .getResponse();
    System.out.println("First search response: " + firstResponse);

    SearchRequest secondRequest = SearchRequest.newBuilder()
        .setPlacement(DEFAULT_SEARCH_PLACEMENT_NAME)
        .setBranch(DEFAULT_BRANCH_NAME)
        .setVisitorId(VISITOR_ID)
        .setQuery(query)
        .setPageSize(pageSize)
        .setPageToken(firstResponse.getNextPageToken())
        .build();

    SearchResponse secondResponse = searchClient.search(secondRequest).getPage()
        .getResponse();
    System.out.println("Second search response: " + secondResponse);
  }
}

Neste exemplo, SearchRequest tem esta aparência:

JSON

{
  placement: 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/placements/default_search'
  visitor_id: 'VISITOR_ID'
  query: 'shoes'
  page_size: 5
  page_token: "wY4ETNkBDOlVjZ0YWLzUmM40SMhVjMtADMwATL5UGN5MGZlVDJaIQ5LaYsQUw9fC6lIwgE1EgC"
}

Em outros casos, em vez de navegar de uma página para outra ou de ver os resultados com maior relevância, você pode ir diretamente para uma posição específica com offset.

Java

import com.google.cloud.retail.v2.SearchRequest;
import com.google.cloud.retail.v2.SearchResponse;
import com.google.cloud.retail.v2.SearchServiceClient;

public static void searchProducts_withOffset(String query, int pageSize,
    int offset) throws IOException, InterruptedException {
  SearchRequest searchRequest = SearchRequest.newBuilder()
      .setPlacement(DEFAULT_SEARCH_PLACEMENT_NAME)
      .setBranch(DEFAULT_BRANCH_NAME)
      .setVisitorId(VISITOR_ID)
      .setQuery(query)
      .setPageSize(pageSize)
      .setOffset(offset)
      .build();

  try (SearchServiceClient searchClient = SearchServiceClient.create()) {
    SearchResponse response = searchClient.search(searchRequest).getPage().getResponse();
    System.out.println("Search response: " + searchResponse);
  }
}

Por exemplo, se quiser a 10ª página dos resultados, quando o tamanho da página for 5, defina o offset como 45, que é calculado por (10 - 1) * 5.

JSON

{
  placement: 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/placements/default_search'
  visitor_id: 'VISITOR_ID'
  query: 'shoes'
  page_size: 5
  offset: 45
}

Níveis de desempenho de pesquisa

A pesquisa oferece vários níveis de desempenho de pesquisa que melhoram cada vez mais os resultados. Por exemplo, para casos de uso de pesquisa de consulta de texto, os resultados podem ser baseados apenas na relevância. À medida que você desbloqueia níveis de desempenho mais avançados, a pesquisa pode retornar resultados baseados em relevância, popularidade, otimização de receita e personalização.

A pesquisa desbloqueia automaticamente níveis de desempenho mais altos quando você faz o upload de dados de eventos do catálogo e do usuário que atendem aos requisitos mínimos de cada nível.

Para mais informações sobre como usar essa página para conferir a qualidade de dados e os níveis de desempenho da pesquisa, consulte Desbloquear níveis de desempenho da pesquisa. A página Qualidade de dados no console da Pesquisa em E-commerce fornece uma avaliação de quais requisitos você atendeu para cada nível.

Avaliar resultados de pesquisa de texto e navegação

Antes de atualizar o código do site para solicitar resultados de pesquisa de texto ou de navegação, você pode visualizar os resultados para confirmar se a configuração de veiculação está funcionando conforme o esperado.

Para mais informações sobre configurações de veiculação, consulte Sobre configurações de veiculação.

É possível visualizar os resultados da configuração de veiculação na página Avaliar ou acessando a página Detalhes de uma configuração de veiculação no console e clicando na guia Avaliar. As etapas a seguir mostram como visualizar na página Avaliar.

Para visualizar os resultados retornados pela configuração de veiculação:

Pesquisa de texto

Acesse a página Avaliar no console da Pesquisa em E-commerce.

Acessar a página "Avaliar"
Clique na guia Pesquisar.

Observação: a guia Pesquisar só está disponível se você tiver a pesquisa ativada. Para instruções sobre como ativá-la, acesse Antes de começar.
Selecione a configuração de veiculação que você quer visualizar.
Selecione a ramificação do catálogo que contém o catálogo que você quer visualizar.
Opcional: insira um ID de visitante para visualizar os resultados da pesquisa desse usuário.
Opcional: insira um ID do usuário para visualizar os resultados da pesquisa desse usuário.
Opcional: insira um horário de pesquisa para visualizar os resultados da pesquisa que apareceriam no horário especificado.

Por exemplo, se você promoveu determinados produtos para uma venda especial, é possível conferir os resultados como eles apareceriam naquele dia.
Opcional: selecione os atributos a serem exibidos ao lado dos resultados da pesquisa e clique em OK para aplicá-los.

Os atributos selecionados são usados para gerar uma lista de filtros de atributos que aparecem em Adicionar atributos depois que você realiza a pesquisa inicial. Esses filtros de atributos podem incluir atributos diferentes dos selecionados nesta etapa, como atributos dinâmicos.
Insira uma consulta de pesquisa baseada em texto para visualizar os resultados da pesquisa dessa consulta.
Clique em Visualização da pesquisa ou pressione Enter em qualquer campo de entrada para conferir os resultados.

Os resultados da pesquisa são mostrados com as imagens em miniatura disponíveis.

Se a pesquisa acionar um controle de redirecionamento, uma notificação vai aparecer mostrando o URI de redirecionamento.
Opcional: clique no ícone Grade ou Lista para mudar a forma como os resultados da pesquisa são mostrados na visualização.
Opcional: se você selecionou atributos para aparecerem ao lado dos resultados, selecione um ou mais valores de atributo na lista de atributos para filtrar os resultados por esses valores. Os resultados são atualizados automaticamente após a seleção.

Quando você seleciona vários valores do mesmo atributo, eles são aplicados como um operador OR, e os valores em atributos diferentes são aplicados como um operador AND. Por exemplo, depois de selecionar os atributos cor e os valores "azul" e "dourado", e os valores de material "algodão" e "poliéster". Os resultados da pesquisa precisam ter "azul" ou "dourado" como um atributo e também "algodão" ou "poliéster" como um atributo.

Procurar

Acesse a página Avaliar no console da Pesquisa em E-commerce.

Acessar a página "Avaliar"
Clique na guia Procurar.

Selecione a configuração de veiculação que você quer visualizar.
Selecione a ramificação do catálogo que contém o catálogo que você quer visualizar.
Opcional: insira um ID de visitante para visualizar os resultados.
Opcional: insira um ID do usuário para visualizar os resultados.
Para visualizar como os resultados seriam mostrados com um filtro específico adicionado, insira uma string de filtro. Use a sintaxe da expressão de filtro especificada na documentação do filtro.
Opcional: insira um horário de navegação para visualizar os resultados que apareceriam no horário especificado.

Por exemplo, se você promoveu determinados produtos para uma ação promocional de pico, é possível conferir os resultados como eles apareceriam naquele dia.
Insira a categoria de página para a qual você está testando os resultados da navegação.
Opcional: selecione os atributos a serem exibidos ao lado dos resultados e clique em OK para aplicá-los.

Os atributos selecionados são usados para gerar uma lista de filtros de atributos que aparecem em Adicionar atributos depois que você realiza a pesquisa inicial. Esses filtros de atributos podem incluir atributos diferentes dos selecionados nesta etapa, como atributos dinâmicos.
Clique em Visualização da navegação ou pressione Enter em qualquer campo de entrada para conferir os resultados.

Os resultados são mostrados com as imagens em miniatura disponíveis.
Opcional: clique no ícone Grade ou Lista para mudar a forma como os resultados são mostrados na visualização.
Opcional: se você selecionou atributos para aparecerem ao lado dos resultados, selecione um ou mais valores de atributo na lista de atributos para filtrar os resultados por esses valores. Os resultados são atualizados automaticamente após a seleção.

Quando você seleciona vários valores do mesmo atributo, eles são aplicados como um operador OR, e os valores em atributos diferentes são aplicados como um operador AND. Por exemplo, depois de selecionar os atributos cor e material, você pode filtrar os resultados da pesquisa selecionando os valores de cor "azul" e "dourado" e os valores de material "algodão" e "poliéster". Os resultados precisam ter "azul" ou "dourado" como um atributo e também "algodão" ou "poliéster" como um atributo.

Para conferir a página Detalhes da configuração de veiculação que você está visualizando, clique em Conferir configuração de veiculação no campo Selecionar configuração de veiculação.

Receber resultados da pesquisa Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Identificadores de sessão de usuário único

Relevância na pesquisa em e-commerce

Pesquisa padrão

Pesquisa não padrão

Pesquisa de texto e pesquisa de navegação

Pesquisas de consulta de texto

Como processar consultas e parâmetros de texto

Pesquisas de navegação

JSON

Usar solicitações de pesquisa

Java

Tutorial de consultas

Filtrar resultados da pesquisa usando sugestões de preenchimento automático

Exemplo de solicitação de pesquisa de uma sugestão filtrada

Adicionar contagens de produtos aos atributos de sugestão

Paginação

Tutorial de paginação

Paginar

JSON

JSON

Java

JSON

Java

JSON

Níveis de desempenho de pesquisa

Avaliar resultados de pesquisa de texto e navegação

Pesquisa de texto

Procurar

Receber resultados da pesquisa