Filtrar recomendações

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

É 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.

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

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

Filtragem de recomendações, versão 2

A versão 2 usa atributos do produto. Expressões de filtro são baseados nos atributos do produto. Eles podem ser atributos de sistema predefinidos, como categories e colors, ou atributos personalizados que você definir, 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ções, 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 você precisa adicionar manualmente a todos os produtos do catálogo que pretende 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 sinalização 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 os itens que estão em estoque com a tag spring-sale ou exclusive (ou ambas) e também não tem o tag items-to-exclude.

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

Compatibilidade dos filtros de atributos e 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 modelos. O os limites a seguir ajudam a evitar efeitos adversos no desempenho da 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 multiplicando o número de produtos no catálogo pelo número de atributos filtráveis.

    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. Certifique-se de que o número de as tags de filtro adicionadas ao número total de valores de atributo for menor que 100.000.000.

Se você exceder os limites, não será possível definir outros atributos como filtráveis. Se for preciso exceder esses limites, solicitar 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 modelos filtráveis atributos são encontrados durante treinamento de modelo, apenas 10 são usados.

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

As sintaxes das expressões de filtro para pesquisa e as recomendações são semelhantes. No entanto, das recomendações tem 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;

Filtrar restrições de sintaxe

As seguintes restrições são aplicadas:

  • A profundidade da incorporação dos 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). O mais complexo uma expressão lógica com suporte pode ser uma lista conectada ao AND de cláusulas 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. Eles não podem ser usada 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" podem ser usada apenas com condições de controle de otimização/ocultação de recomendações, que dão alguns campos numéricos (consulte Otimização/ocultação de campos compatíveis).
  • 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 ANY(). expressões idiomáticas. 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 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 availability: ANY("IN_STOCK"), a resposta da previsão retorna produtos principais em que o produto principal ou uma 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 OR.

Campos aceitos

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

A otimização/ocultação das recomendações oferece suporte a campos adicionais que não são compatíveis com a filtragem de recomendações padrão. Para uma lista de campos adicionais que são suportados por otimização/ocultação para recomendações, consulte Otimização/ocultação de campos compatíveis.

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.

Otimizar/ocultar campos compatíveis

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. Este campo é calculado com o uso do preço original e preços de PriceInfo.
"classificação" Product.rating O número total de classificações produto.
"ratingCount" rating.ratingCount O número total de classificações produto.

Definir filtragem de recomendações para um modelo

É possível ativar o filtro de recomendações usando o Pesquise o console do Retail ou o recurso de 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

No console do Search for Retail, 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, combinar diversity-level e category attribute filtering baseados em regras frequentemente 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, 1 resultado para categoria1, 1 resultado para categoria2 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. A os valores permitidos são:

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

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 de uma um modelo de machine learning.

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 os produtos recomendados, ative o filtro de atributos do produto que você usará em 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 permita que mais atributos sejam filtrados 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. Isso valores permitidos do 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 seu 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 do produto categories como filtráveis.

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 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"

O atributo pode ser usado para filtragem após o próximo treinamento de modelo tenha concluído. Isso geralmente leva pelo menos oito horas.

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

Depois de treinar o modelo de novo, é possível usar atributos de produto filtráveis nas solicitações de previsão.

Defina o valor do parâmetro de solicitação filterSyntaxV2 como verdadeiro para ativar a versão 2 filtragem de recomendações. 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 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.