Filtrar recomendações

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

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

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

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. As expressões de filtro são baseadas em 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 de produto como filtrável, as recomendações podem usar esses atributos automaticamente como tags para a filtragem de recomendações, em vez de exigir que você adicione manualmente as tags de filtro.

Quando você usa atributos para filtrar produtos, a resposta de previsão retorna produtos principais que contêm pelo menos um produto principal ou variante com um valor de atributo correspondente à expressão do filtro. 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 todos os produtos vermelhos ou azuis definidos como "New-Arrival" 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 estes procedimentos. Cada procedimento é apresentado mais adiante nesta página.

  1. Ative a filtragem de recomendações para um modelo que vai 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 do catálogo que você planeja filtrar.

O exemplo de expressão de filtro a seguir usa tags de filtro para especificar produtos com as tags "Vermelho" ou "Azul", além da tag "New-Arrival", e que não têm a tag "Promoção":

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 das tags, você pode 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 item esgotado para que apenas os itens que atendem a todas as expressões de filtro especificadas sejam retornados.

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 poderá enviar 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:

  • É possível definir até 10 atributos personalizados como filtráveis no seu catálogo.

  • Até 100 milhões 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 multiplicando o número de produtos no catálogo pelo número de atributos filtráveis.

    Por exemplo, se você tiver um catálogo com 1.000 produtos e três atributos definidos como filtráveis, o número total de valores de atributo poderá ser estimado como 3*1000=3000.

    Se você estiver usando a filtragem de recomendações da versão 1 com a versão 2, o número de tags de filtro será contabilizado na 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 será possível definir outros atributos 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 ultrapassar o limite, o treinamento de modelo vai falhar. Se mais de 10 atributos personalizados filtráveis forem encontrados durante treinamento de 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 de filtro de recomendações pode ser resumida pelo 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. As expressões lógicas no filtro precisam estar na forma normal conjuntiva (CNF). 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 inclui 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, operações de verificação de intervalo e "menor que" e "maior que" não são compatíveis com a 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(), todos os argumentos dela serão contabilizados 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álidas, bem como exemplos inválidos e os motivos de invalidez.

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 dos 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 aceito pela versão 2 da 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

O Boost/bury oferece suporte a alguns campos adicionais que não são compatíveis com a filtragem padrão de recomendações, incluindo campos numéricos.

Além dos campos listados em Campos aceitos, o boost/bury para recomendações aceita os seguintes campos:

Campos de texto

campo description
"tags" Product.tags[] 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 do 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 o filtro de recomendações ativado. Também é possível atualizar essa opção para modelos atuais.

Usando o recurso da API Models, é possível criar um novo modelo com a filtragem de recomendações ativada ou atualizar essa configuração para um modelo existente 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 e category-match-level, 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 os 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. Mude 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 um modelo de recomendação usando o console.

Não é possível atualizar essa configuração no console para modelos atuais. Para atualizar essa configuração em um modelo, use o método da 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 na página "Controles" no console da Pesquisa para varejo.

  1. Acesse a página Controles no console da Pesquisa para varejo.

    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 Filtrável como Verdadeiro 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 treinamento de 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 está desativada para o atributo.
  • RECOMMENDATIONS_FILTERING_ENABLED: a filtragem está ativada para o atributo.

O exemplo de curl a seguir consulta os atributos de produtos atuais.

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, mantenha os valores originais dele para indexableOption, dynamicFacetableOption e searchableOption conforme aparecem na etapa anterior. Se o atributo escolhido não aparecer ao visualizar attributesConfig, como no exemplo anterior, use as configurações padrão, conforme 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 treinamento de 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 vai permanecer ativa. Se um modelo tiver tags criadas manualmente e atributos de produto filtráveis, ele poderá enviar solicitações de previsão usando qualquer versão de filtragem. No entanto, não é possível incluir as expressões de filtragem v1 e 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 de 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 diversificação da configuração de veiculação também pode afetar o número de resultados retornados pela resposta.