Esta é a documentação do Recommendations AI, da Pesquisa de varejo e do novo Console do Retail.

Catálogos e informações de catálogo

Esta página informa as práticas recomendadas para criar informações do catálogo e preencher os dados do catálogo.

Visão geral

Os dados do catálogo importados para o varejo têm um efeito direto na qualidade do modelo resultante e, portanto, na qualidade dos resultados que a API Retail fornece. Em geral, quanto mais precisas e específicas forem as informações de catálogo que você fornecer, maior será a qualidade do seu modelo.

Seu catálogo precisa estar atualizado. É possível fazer upload das alterações do catálogo quantas vezes forem necessárias. Idealmente, todos os dias para catálogos com uma alta taxa de mudanças. É possível fazer upload (patch) de itens de produto existentes somente os campos alterados serão atualizados. Não há cobrança pelo upload das informações do catálogo. Para mais informações, consulte Como manter seu catálogo atualizado.

Ramificações do catálogo

Se você usa a Pesquisa de varejo, pode usar ramificações do catálogo para testar novos dados enviados off-line antes de disponibilizá-los no seu site.

Com a API Retail, é possível usar até três ramificações, identificadas como 0, 1 e 2. Seu site ativo aponta para default_branch para os dados do catálogo. Especifique qual ramificação é sua default_branch ativa atualmente (definida por padrão para a ramificação 0) usando setDefaultBranch ou a guia "Dados" no Console do Cloud. Em seguida, o site usa os dados de catálogo fornecidos pela ramificação a que a default_branch aponta.

Por exemplo, digamos que default_branch esteja definido atualmente com o ID da ramificação 0. Portanto, seu site está usando os dados do catálogo que você enviou para essa ramificação. Você pode fazer upload de novos dados de catálogo para a ramificação 1 e visualizá-los. Depois de confirmar que o catálogo foi enviado corretamente, alterne para a ramificação 1 como o default_branch ativo.

O cache do catálogo pode levar até 30 minutos para ser atualizado após a mudança do branch.

Se você usa a Recommendations AI, recomendamos usar apenas a ramificação padrão devido ao atraso de atualização durante a mudança da ramificação. Se a diferença de dados entre as ramificações for grande, o atraso na atualização poderá afetar negativamente os resultados da previsão.

Produtos

O catálogo é um conjunto de objetos de produto.

Informações obrigatórias do produto

Os campos a seguir são obrigatórios. É preciso fornecer valores a eles ao criar itens de produtos no catálogo. Eles também precisam corresponder aos valores usados no banco de dados interno do produto e refletir com precisão o produto representado, porque estão incluídos no treinamento dos modelos.

Em alguns casos, outros campos também são obrigatórios. Veja a lista completa de todos os campos de produtos na página de referência Product.

Todas as informações do produto que você fornece podem ser usadas para melhorar a qualidade das recomendações e dos resultados da pesquisa. Forneça o maior número possível de campos.

Campo Observações
name O nome exclusivo completo do recurso do produto. Obrigatório para todos os métodos de produto, exceto import. Durante a importação, o nome é gerado automaticamente e não precisa ser fornecido manualmente.
id O ID do produto usado pelo banco de dados do produto. O campo "ID" precisa ser exclusivo em todo o catálogo. O mesmo valor é usado quando você registra um evento de usuário e também é retornado pelos métodos predict e search.
title Título do produto do seu banco de dados de produtos. Uma string codificada em UTF-8. Limitado a 1.250 caracteres.

Atributos do produto

É altamente recomendável fornecer valores para atributos predefinidos do sistema em Product, como marca, cor e tamanho. Também é possível incluir atributos personalizados definidos com Product.attributes.

Se você estiver usando a pesquisa de varejo, os atributos serão incluídos em um produto na resposta da pesquisa se forem marcados como recuperáveis em Product.retrievableFields. Eles podem ser usados para outros recursos da Pesquisa de varejo, como filtros e atributos.

Níveis de produto

Se você importa seu catálogo vinculando sua conta do Merchant Center, é possível ingerir produtos de todos os tipos. Se você estiver importando seu catálogo pela primeira vez do BigQuery ou do Cloud Storage, especifique um dos seguintes níveis de produto:

  • Os itens primários são o que a API Retail retorna na previsão ou nos resultados da pesquisa. Eles podem ser itens individuais (nível da SKU) ou grupos de itens semelhantes (grupos SKU). Por padrão, se o nível do produto não for definido, a API Retail usará o nível principal do produto e processará produtos de todos os tipos.

  • Os itens variantes são versões de um produto principal. As variantes só podem ser itens individuais (nível SKU). Por exemplo, se o produto principal for "camisa com gola em V", as variantes poderão ser "camisa com gola marrom branca, tamanho X". e "camisa com gola branca v e tamanho P". Primários e variantes às vezes são descritos como itens "quoquo;parent" e "filhos.

Durante a importação de catálogo, defina seus níveis de produto usando o método Catalog.patch. Exemplo:

curl -X PATCH 
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
-H "Content-Type: application/json; charset=utf-8"
--data '{ "productLevelConfig": { "ingestionProductType": "PRODUCT-TYPE", "merchantCenterProductIdField": "PRODUCT-ID-FIELD" } }'
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

Para determinar as melhores opções de nível de produto para sua implementação, é necessário revisar os dados do catálogo e a lógica do seu site. Quais IDs de produtos estão disponíveis quando você captura dados de eventos do usuário? Quais IDs de produtos seriam mais eficazes para serem retornados com previsões ou resultados da pesquisa? Como esses IDs se comparam e se relacionam?

Use as etapas apropriadas, dependendo se você está importando do Merchant Center ou não:

Determinar os níveis de produto para importação do Merchant Center

Quando você importa dados de catálogo do Merchant Center, a API Retail usa ingestionProductType para ajudar a identificar se é necessário fazer o upload deles como itens primários ou variantes; e o campo merchantCenterProductIdField para especificar se é preciso usar offer_id ou item_group_id do Merchant Center como ID do produto.

Revise os dados do catálogo e a lógica do seu site para responder às seguintes perguntas:

  • Tenho primárias e variantes no meu catálogo?
  • Se sim, que nível de item terei ao capturar os dados de eventos do usuário?
  • Que tipo de itens preciso retornar com meus resultados?

Determine se:

  1. Seu catálogo tem apenas um nível de itens. Isso pode significar que:

    • Todos os seus produtos e eventos estão no nível de SKU, e você quer previsões no nível de SKU.
    • Todos os seus produtos e eventos estão no nível do grupo, e você quer previsões no nível do grupo.

    Se for o caso, importe somente com os itens principais. Esta é a configuração de importação padrão.

  2. Você quer previsões no nível do grupo (principal), mas seus produtos do Merchant Center estão no nível da SKU. Nesse caso, sua decisão de importação depende de como os eventos são capturados.

    1. Os eventos são capturados no nível do grupo. Nesse caso, use as configurações a seguir durante a importação:

      Em que vários produtos do Merchant Center têm o mesmo item_group_id do Merchant Center, o Recommendations AI importa apenas um deles como um produto principal, e usa item_group_id como o ID do produto. Os produtos que não têm um item_group_id não podem ser importados nesse caso. Os eventos gravados precisam se referir ao ID do produto principal (no nível do grupo).

    2. Seus eventos são capturados no nível de SKU. Nesse caso, use as configurações a seguir durante a importação:

      O Retail importa seus produtos como variantes e usa o Merchant Center offer_id como o ID do produto. Os eventos gravados precisam se referir ao ID da variante no nível da SKU.

Determinar os níveis de produto para importação sem o Merchant Center

É necessário que todos os seus produtos tenham um valor para primaryProductId ou nenhum deles. Não é possível importar dados de catálogo com primaryProductId definido para alguns itens, mas para outros não.

  1. Caso seu catálogo tenha somente um nível de itens, isso poderá significar que:

    • Todos os produtos e eventos estão no nível da SKU, e você quer resultados no nível da SKU.
    • Todos os seus produtos e eventos estão no nível do grupo, e você quer resultados no nível do grupo.

    Se for o caso, importe somente com os itens principais. Essa é a configuração de importação padrão e recomendada.

  2. Se os eventos e produtos estiverem no nível da SKU, será possível receber resultados no nível do grupo. Defina ingestionProductType como variant durante a importação.

A previsão e a pesquisa no nível de SKU não serão compatíveis se você tiver apenas produtos e eventos no nível do grupo.

Se você pretende importar dados do catálogo do Merchant Center no futuro, revise seus dados conforme descritos para importações do Merchant Center para garantir que esteja fazendo a escolha correta. A alteração dessa configuração só pode ser feita excluindo o catálogo e enviando-o novamente. Consulte Alterar configuração no nível do produto.

Métricas de qualidade de dados do catálogo

Para ajudar você a monitorar a qualidade da pesquisa dos dados do catálogo, o varejo avalia os dados do produto em relação a um conjunto de regras de qualidade. Veja a porcentagem de produtos que atendem a cada regra de qualidade na página Dados do varejo.

A tabela a seguir descreve as métricas de qualidade que o Retail usa para ajudar você a avaliar os dados do seu produto:

Métrica de qualidade do catálogo Regra de qualidade Observações
O URI está presente e acessível O produto tem um Product.uri válido. O URI precisa estar acessível e corresponder ao seu domínio. O Cloud Retail Search usa sinais da Web rastreados por meio desse URI para melhorar a qualidade da pesquisa.
Atende à conformidade de tempo Product.availableTime é anterior ao horário atual, e Product.expireTime é anterior ao horário atual. Somente produtos em conformidade com o horário estão disponíveis para pesquisa.
O atributo pesquisável está presente O produto tem pelo menos um attribute definido para pesquisa. Os atributos personalizados marcados como pesquisáveis podem ser pesquisados por consultas de texto.
A descrição está presente O produto não tem um Product.description vazio. Uma descrição abrangente ajuda a melhorar a qualidade da pesquisa.
O título consiste em pelo menos duas palavras Product.title consiste em pelo menos duas palavras. Um título abrangente ajuda a melhorar a qualidade da pesquisa.
Tem variante com imagem O produto variant tem pelo menos um Product.image. Você poderá ignorar essa métrica se todos os seus produtos estiverem no nível primary. Essa métrica é apenas informativa e não afeta a qualidade da pesquisa.
Tem variante com informações de preço O produto variant tem Product.priceInfo definido. Você poderá ignorar essa métrica se todos os seus produtos estiverem no nível primary. Essa métrica é apenas informativa e não afeta a qualidade da pesquisa.

Esquema de varejo

Ao importar um catálogo do BigQuery, use o esquema de varejo abaixo para criar uma tabela do BigQuery com o formato correto e carregá-la com os dados do catálogo. Em seguida, importe o catálogo.