Filtrar recomendações

Esta página descreve a filtragem de resultados de recomendações usando atributos do produto.

É possível filtrar os resultados da previsão especificando uma expressão de filtro na previsão. solicitações. A expressão de filtro é uma expressão lógica avaliada para cada produto. A lista de produtos na resposta está restrita a produtos em que a expressão é avaliada como verdadeira.

Observação :as atualizações da expressão de tag podem levar até oito horas para ficarem disponíveis usar na filtragem de previsões com a v1 e a v2, incluindo as configurações de atributos para filtragem e as alterações de metadados no nível do produto. Apenas o campo Availability tem atualizações em tempo real.

Há duas versões de filtragem para recomendações:

• Recomendamos a versão 2.
• A versão 1 foi descontinuada, mas ainda pode estar em uso.

As seções deste guia de instruções se aplicam apenas à versão 2 da filtragem, que filtra recomendações usando atributos do produto.

Filtragem de recomendações, versão 2

A versão 2 usa atributos de produto. Expressões de filtro são baseados nos atributos do produto. Eles podem ser atributos do sistema predefinidos, como categories e colors, ou atributos personalizados definidos por você, como attributes.styles. Quando você define um atributo do produto como filtrável, as recomendações podem usar esses atributos tags para filtrar recomendações, em vez de exigir que você adicionar tags de filtro.

Quando você usa atributos para filtrar produtos, a resposta da previsão retorna produtos principais que contêm pelo menos um produto principal ou variante que tenha um valor de atributo correspondente ao filtro expressão. Para saber mais sobre produtos principais e variantes, consulte Níveis de produto.

O exemplo de expressão de filtro a seguir também filtra por quaisquer valores vermelhos ou azuis produtos definidos como "Chegada". e não definidos como promocionais:

colors: ANY("red", "blue") AND attributes.status: ANY("New-Arrival") AND NOT attributes.is_promotional: ANY("true")

Para usar a versão 2 da filtragem de recomendações, siga estas procedimentos. Cada procedimento é apresentado mais adiante nesta página.

1. Ativar a filtragem de recomendações para um modelo que vai e exibir recomendações filtradas.
2. Ative a filtragem de recomendações para os atributos de produtos que você planeja filtrar.
3. Use atributos de produto filtráveis em solicitações de previsão.

Filtragem de recomendação, versão 1 (descontinuada)

A versão 1 usa tags de filtro criadas manualmente. As expressões de filtro são baseadas em tags de filtro, que precisam ser adicionadas manualmente a todos os produtos da sua no catálogo que você planeja filtrar.

O exemplo de expressão de filtro a seguir usa tags de filtro para especificar produtos marcado como "vermelho" ou "Blue", assim como a tag "New-Arrival", e não precisam marcado como "promocional":

tag=("Red" OR "Blue") tag="New-Arrival" tag=(NOT "promotional")

Consulte a documentação de referência da API para o campo Product.tags[].

As expressões de tag podem conter os operadores booleanos OR ou NOT, que precisam ser separados dos valores de tag por um ou mais espaços. Os valores de tag também podem ser precedidos por um traço (-) imediatamente, o que equivale ao operador NOT. As expressões de tag que usam os operadores booleanos precisam ser colocadas entre parênteses.

Além de tags, é possível filtrar por filterOutOfStockItems. A flag filterOutOfStockItems filtra todos os produtos com stockState de OUT_OF_STOCK.

É possível combinar filtros de tag e filtros de itens em falta para que apenas os itens que satisfazem todas as expressões de filtro especificadas.

Alguns exemplos de strings de filtro:

"filter": "tag=\"spring-sale\""

"filter": "filterOutOfStockItems"

"filter": "tag=\"spring-sale\" tag=\"exclusive\" filterOutOfStockItems"

O exemplo a seguir retorna somente itens que estão em estoque com a tag spring-sale ou exclusive (ou ambas) e não têm a tag items-to-exclude.

"filter": "tag=(\"spring-sale\" OR \"exclusive\") tag=(-\"items-to-exclude\") filterOutOfStockItems"

Compatibilidade do filtro de atributos e do filtro de tags

Se um modelo tiver tags criadas manualmente e atributos de produto filtráveis, ele pode atender a solicitações de previsão usando qualquer versão da filtragem. No entanto, não é possível incluir as expressões de filtragem da v1 e da v2 na mesma solicitação de previsão.

Limites de filtragem de recomendações

Cada atributo filtrável consome um pouco de memória em cada um dos seus modelos. Os limites a seguir ajudam a evitar efeitos adversos na performance de veiculação:

• Até 10 atributos personalizados podem ser definidos como filtráveis no seu catálogo.

• Até 100.000.000 de valores de atributos filtráveis podem estar presentes no seu catálogo.

  O número total de valores de atributos no seu catálogo pode ser estimado por multiplicando o número de produtos no seu catálogo pelo número de itens filtráveis atributos.

  Por exemplo, se você tem um catálogo com 1.000 produtos e 3 atributos definidos como filtráveis, o número total de valores dos atributos pode ser estimado como 3*1.000=3.000.

  Se você estiver usando a filtragem de recomendações da versão 1 junto com a versão 2, os de tags de filtro são contabilizadas em sua cota. Verifique se o número de tags de filtro adicionado ao número total de valores de atributo é menor que 100.000.000.

Se você exceder os limites, não poderá definir atributos adicionais como filtráveis. Se você precisar exceder esses limites, solicite um aumento de cota.

O número total de tags é calculado durante treinamento de modelo. Se o número total exceder o limite, treinamento de modelo vai falhar. Se mais de 10 atributos personalizados filtráveis forem encontrados durante o treinamento do modelo, apenas 10 serão usados.

Sintaxe da expressão do filtro de recomendações

As sintaxes de expressão de filtro para pesquisa e recomendações são semelhantes. No entanto, as recomendações têm várias limitações.

A sintaxe da expressão do filtro de recomendações pode ser resumida em: o seguinte EBNF:

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };

  # An expression can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
                    # A parenthesized expression
                    | "(", expression, ")"
                    # A simple expression applying to a textual field.
                    # Function "ANY" returns true if the field contains any of the literals.
                    ( textual_field, ":", "ANY", "(", literal, { ",", literal }, ")"

  # A literal is any double-quoted case sensitive string. You must escape backslash (\) and
  # quote (") characters. We do not support textual values containing `/` characters, or partial string matches.

  # The literal must be an exact match for products in the catalog. The Predict
  # API returns empty results when no possible matches exist.

  literal = double-quoted string;

  textual_field = see the tables below;

Restrições de sintaxe do filtro

As seguintes restrições são aplicadas:

• A profundidade de inserção de operadores AND e OR entre parênteses é limitada. O as expressões lógicas do filtro devem estar forma normal conjuntiva (CNF, na sigla em inglês). A expressão lógica mais complexa com suporte pode ser uma lista de cláusulas conectadas por AND que contém apenas operadores OR, como: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
• As expressões podem ser negadas com a palavra-chave NOT ou com -. Isso só funciona com expressões ANY() com um único argumento que não incluem atributos relacionados ao inventário.
• As restrições baseadas em availability precisam estar no nível superior. Elas não podem ser usadas como parte de uma cláusula OR ou uma negação (NOT).
• Como a filtragem de recomendações padrão oferece suporte apenas a campos de texto, As operações de menor que, maior que e verificação de intervalo não são suportadas para filtragem de recomendações padrão. As operações "menor que" e "maior que" só podem ser usadas com as condições de controle de aumento/ocultamento de recomendações, que oferecem suporte a alguns campos numéricos (consulte Campos com suporte a aumento/ocultamento).
• O número máximo de termos na cláusula AND de nível superior é 20.
• Uma cláusula OR pode ter até 100 argumentos incluídos em expressões ANY(). Se uma cláusula OR tiver várias expressões ANY(), as todos os argumentos contam para esse limite. Por exemplo, colors: ANY("red", "green") OR colors: ANY("blue") tem três argumentos.

A tabela a seguir mostra exemplos de expressões de filtro válidos e inválidos exemplos e os motivos da invalidação.

Expressão	Válido	Observações
colors: ANY("red", "green")	Sim
NOT colors: ANY("red")	Sim
NOT colors: ANY("red", green")	Não	Nega um "ANY()" com mais de um argumento.
colors: ANY("red", "green") OR categories: ANY(\"Phone > Android > Pixel\")	Sim
(colors: ANY("red") OR colors: ANY("green")) AND categories: ANY(\"Phone > Android > Pixel\")	Sim
(colors: ANY("red") AND colors: ANY("green")) OR categories: ANY(\"Phone > Android > Pixel\")	Não	Não está na forma normal conjuntiva.
(colors: ANY("red")) AND (availability: ANY("IN_STOCK")	Sim
(colors: ANY("red")) OR (availability: ANY("IN_STOCK"))	Não	Combina availability em uma expressão OR com outras condições.

Filtragem de atributos relacionados ao inventário

A filtragem de atributos relacionados ao inventário é baseada no estado em tempo real da seus produtos. Para a filtragem de availability: ANY("IN_STOCK"), a resposta de previsão retorna produtos principais em que o principal ou um produto variante tem o valor correspondente de IN_STOCK. Para saber mais sobre produtos principais e variantes, consulte Níveis de produto. Não oferecemos suporte à filtragem Primary only ou Variant only.

IN_STOCK é o único valor de atributo availability compatível com a versão 2 do filtragem de recomendações.

Atributos relacionados ao inventário podem ser usados em cláusulas AND, mas não em cláusulas OR.

Campos aceitos

Os campos de texto compatíveis estão resumidos na tabela a seguir.

O boost/bury para recomendações oferece suporte a outros campos que não são compatíveis com a filtragem de recomendações padrão. Para conferir uma lista de outros campos com suporte para boost/bury para recomendações, consulte Campos com suporte para boost/bury.

campo	descrição
"productId"	O ID do produto (o último segmento em Product.name).
"brands"	Product.brands
"categorias"	Product.categories
"gêneros"	Audience.genders
"ageGroups"	Audiences.age_groups
"colorFamilies"	ColorInfo.color_families
"cores"	ColorInfo.colors
"tamanhos"	Product.sizes
"materiais"	Product.materials
"padrões"	Product.patterns
"condições"	Product.conditions
"attributes.key"	O atributo personalizado textual no objeto "Produto". A chave pode ser qualquer chave no mapa Product.attributes se os valores do atributo forem textuais.

Campos compatíveis com a otimização/aumento

A otimização/ocultação suporta alguns campos adicionais que não são suportados pelo padrão filtragem de recomendações, incluindo campos numéricos.

Além dos campos listados nos Campos compatíveis, O boost/bury para recomendações é compatível com os seguintes campos:

Campos textuais

campo	description
"tags"	Product.tags[] As tags personalizadas associadas ao produto.

Campos numéricos

campo	descrição
"preço"	PriceInfo.price: O preço do produto.
"desconto":	O desconto do produto. Esse campo é calculado usando o preço original e os valores do campo de preço de PriceInfo.
"classificação"	Product.rating O número total de classificações do produto.
"ratingCount"	rating.ratingCount O número total de classificações produto.

Definir a filtragem de recomendações para um modelo

É possível ativar a filtragem de recomendações usando o console de Pesquisa para varejo ou o recurso da API Models.

No console, é possível criar um novo modelo com filtragem de recomendações ativado. Também é possível atualizar essa opção para modelos atuais.

Usando o recurso de API Models, é possível criar um novo modelo com recomendações com a filtragem ativada ou atualize essa configuração para um modelo atual usando models.Patch.

Se a configuração de veiculação que retorna previsões tiver a correspondência de categoria ativada, a filtragem não vai funcionar no atributo "categorias", porque a resposta retorna apenas resultados de produtos que compartilham uma categoria com o produto de contexto.

Definir a filtragem de um modelo usando o console

Usando o console de Pesquisa para varejo, selecione a opção Gerar tags automaticamente durante a criação do modelo para permitir a filtragem de recomendações para esse modelo.

Verifique a compatibilidade com outras configurações, como diversity-level, category-match-level etc., porque os efeitos totais são combinados e a filtragem acontece por último.

• Por exemplo, a combinação de diversity-level e category attribute filtering com base em regras geralmente resulta em uma saída vazia.
  • diversity-level=high-diversity força o modelo a limitar os resultados máximos para as mesmas strings de categoria. Ou seja, um resultado para a categoria 1, um resultado para a categoria 2 etc.
  • A filtragem de atributos usando metadados de categoria (Product.categories = ANY ("category2")) faz com que o modelo descarte itens que não correspondem.
  • A saída final tem menos de três resultados.
• O modelo similar-items já contém um aumento extra na relevância da categoria com o category-match-level = relaxed-category-match padrão. Alterne para category-match-level=no-category-match para desativar o comportamento e usar regras de filtragem personalizadas.

Consulte Criar modelos de recomendação para instruções sobre como criar usando o console do Cloud.

Essa configuração não pode ser atualizada no console para modelos existentes. Para atualizar isto para um modelo, use o método de API models.Patch.

Definir a filtragem de um modelo usando a API

É possível ativar a filtragem de recomendações para um modelo usando models.Create ao criar um novo modelo ou models.Patch ao atualizar um modelo atual.

Para permitir a filtragem, defina o campo filteringOption para o modelo. Os valores permitidos para este campo são:

• RECOMMENDATIONS_FILTERING_DISABLED (padrão): a filtragem é desativada para o modelo.
• RECOMMENDATIONS_FILTERING_ENABLED: a filtragem está ativada para produtos principais.

O exemplo de curl a seguir cria um novo modelo com a filtragem de recomendações ativada.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'name': 'MODEL_NAME',
       'displayName': 'MODEL_DISPLAY_NAME',
       'type': 'home-page',
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models"

O exemplo de curl a seguir atualiza a configuração da opção de filtragem para um modelo existente.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
       'filteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED',
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/models/MODEL_ID?updateMask=filteringOption"

Definir atributos como filtráveis

Para filtrar produtos recomendados, ative a filtragem para os atributos de produto que você vai usar nas expressões de filtro. É possível atualizar essa configuração usando o console de Pesquisa para varejo ou o recurso da API Attributes.

Não torne mais atributos filtráveis do que o necessário. Há um limite no número de atributos filtráveis.

Definir atributos como filtráveis usando o console

É possível definir um atributo como filtrável Controles de segurança na Pesquise o console de varejo.

1. Acesse a página Controles no console do Search for Retail.
   
   Acessar a página "Controles"

2. Acesse a guia Controles de atributo.

   Essa guia exibe uma tabela de todos os atributos de produtos que você pode definir em todo o site.

3. Clique em Modificar controles.

4. Defina Filterable como True para o atributo do produto.

5. Clique em Salvar controles.

Você poderá começar a usar o atributo para filtrar depois que o próximo ciclo de treinamento do modelo for concluído.

Definir atributos como filtráveis usando a API

AttributesConfig representa uma lista de atributos de um catálogo.

Defina o campo AttributesConfig.filteringOption para CatalogAttribute. Os valores permitidos para esse campo são:

• RECOMMENDATIONS_FILTERING_DISABLED (padrão): a filtragem é desativada para o atributo.
• RECOMMENDATIONS_FILTERING_ENABLED: a filtragem está ativada para o atributo.

O exemplo de curl a seguir consulta seus atributos de produto existentes.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \ "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

O exemplo de curl a seguir define o atributo de produto categories como filtrável.

Ao atualizar um atributo existente, mantenha os valores originais do atributo para indexableOption, dynamicFacetableOption e searchableOption conforme eles aparecem na etapa anterior. Se o atributo escolhido não aparecer quando visualizando attributesConfig como no exemplo anterior e, em seguida, use o padrão de configuração, como mostrado no exemplo a seguir.

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'name': 'projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/attributesConfig',
        'catalogAttributes': {
          'categories': {
            'key': 'categories',
            'indexableOption': 'INDEXABLE_ENABLED',
            'dynamicFacetableOption': 'DYNAMIC_FACETABLE_DISABLED',
            'searchableOption': 'SEARCHABLE_DISABLED',
            'recommendationsFilteringOption': 'RECOMMENDATIONS_FILTERING_ENABLED'
          }
        },
        'attributeConfigLevel': 'CATALOG_LEVEL_ATTRIBUTE_CONFIG'
     }" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/attributesConfig"

Você poderá começar a usar o atributo para filtrar depois que o próximo ciclo de treinamento do modelo for concluído. Isso geralmente leva pelo menos oito horas.

Usar atributos filtráveis em uma solicitação de previsão

Depois que o modelo for treinado novamente, você poderá usar atributos de produto filtráveis nas solicitações de previsão.

Defina o valor do parâmetro de solicitação filterSyntaxV2 como "true" para ativar a filtragem de recomendações da versão 2. Se o parâmetro não for definido, a filtragem da versão 1 permanece ativa. Se um modelo tiver tags criadas manualmente e produtos filtráveis ele pode disponibilizar solicitações de previsão usando qualquer versão da filtragem. No entanto, não é possível incluir a filtragem v1 e a filtragem v2. na mesma solicitação de previsão.

O exemplo de curl parcial a seguir mostra filterSyntaxV2 definido como verdadeiro e uma expressão de filtro usando os atributos do produto colors e categories. Neste exemplo, presumimos que colors e categories estejam definidos como filtráveis.

"params": {
  "filterSyntaxV2": true
},
"filter": "(categories: ANY(\"Phone > Android > Pixel\") OR colors: ANY(\"red\", \"green\")) AND (availability: ANY(\"IN_STOCK\"))"

O exemplo de curl a seguir mostra uma solicitação de previsão completa.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -H "X-Goog-User-Project: PROJECT_NUMBER" \
     --data "{
        'userEvent': {
          'eventType': 'detail-page-view',
          'visitorId': 'VISITOR_ID',
          'productDetails': {
            'product': {
              'id': 'PRODUCT_ID'
            }
          }
        },
        'params': {
          'returnProduct': true,
          'filterSyntaxV2': true,
          'strictFiltering': true,
        },
        'filter': 'categories: ANY(\"xyz\")'
     }" \
     "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/SERVING_CONFIG:predict"

Além dos filtros, a configuração de exibição A configuração de diversificação também pode afetar o número de resultados retornados pela resposta.