Filtrar recomendações

Nesta página, descrevemos os resultados de filtragem do Recommendations AI usando atributos de produto.

Filtre os resultados da previsão especificando uma expressão de filtro nas solicitações de previsão. A expressão de filtro é uma expressão lógica avaliada para cada produto. A lista de produtos na resposta é restringida aos produtos em que a expressão é avaliada como verdadeira.

Há duas versões de filtragem para o Recommendations AI:

As seções deste guia de instruções só se aplicam à 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 os atributos do produto. As expressões de filtro são baseadas nos atributos do produto. Podem ser atributos de 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, o Recommendations AI pode usar automaticamente esses atributos como tags para filtragem de recomendações, em vez de exigir que você adicione tags de filtro manualmente.

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 que tenha um valor de atributo correspondente à expressão de filtro. Para mais informações 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 em vermelho ou azul definidos como "Novos de 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 para o Recommendations AI, siga estes procedimentos. Cada procedimento é abordado mais adiante nesta página.

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

Filtragem de recomendações, versão 1 (obsoleta)

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 qualquer produto no seu catálogo que queira filtrar.

O exemplo de expressão de filtro a seguir usa tags de filtro para especificar produtos marcados como "Vermelho" ou "Azul", bem como a tag "Nova chegada" e não estão marcados como "promocionais":

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, é possível filtrar por filterOutOfStockItems. A sinalização filterOutOfStockItems filtra todos os produtos com um stockState de OUT_OF_STOCK.

É possível combinar filtros de tags e filtros de produtos esgotados para que somente itens que atendam a todas as expressões 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 apenas os itens que estão em estoque que têm a tag spring-sale ou exclusive (ou ambas) e também não têm a tag items-to-exclude.

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

Compatibilidade com filtros de atributos e tags

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

Limites de filtragem de recomendações

Cada atributo filtrável consome parte da memória em cada um dos modelos. Os limites a seguir ajudam a evitar efeitos adversos no desempenho da veiculação:

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

  • Até 100.000.000 de atributos filtráveis podem estar presentes em 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 3 atributos definidos como filtráveis, o número total de valores de atributos poderá ser estimado como 3*1.000=3.000.

    Se você estiver usando as recomendações da versão 1 e as versões 2, o número de tags de filtro será contabilizado na sua cota. Verifique se o número de tags de filtro adicionadas ao número total de valores de atributos é menor que 100.000.000.

Se você exceder os limites, a API Retail impedirá a definição de 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 exceder o limite, o treinamento de modelo falhará. Se forem encontrados mais de 10 atributos personalizados filtráveis durante o treinamento de modelo, apenas 10 serão usados.

Sintaxe da expressão do filtro do Recommendations AI

As sintaxes da expressão de filtro para a Retail Search e o Recommendations AI são semelhantes. No entanto, a Recommendations AI tem várias limitações.

A sintaxe da expressão de filtro do Recommendations AI pode ser resumida pelo EBNF a seguir:

  # 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 string. You must escape backslash (\) and
  # quote (") characters.
  literal = double-quoted string;

  textual_field = see the tables below;

Filtrar restrições de sintaxe

As seguintes restrições são aplicadas:

  • A profundidade de incorporação dos operadores AND e OR entre parênteses é limitada. As expressões lógicas no filtro precisam estar na forma normal conjuntiva (CNF, na sigla em inglês). A expressão lógica compatível mais complexa pode ser uma lista de cláusulas conectadas 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 funciona apenas com expressões ANY() com um único argumento que não inclua atributos relacionados ao inventário.
  • As restrições baseadas em availability precisam estar no nível superior. Eles não podem ser usados como parte de uma cláusula OR ou de uma negação (NOT).
  • Como a filtragem de recomendações padrão é compatível apenas com campos de texto, as operações de menos que, maior e de verificação de intervalo não são compatíveis com a filtragem de recomendações padrão. As operações "menor que" e "maior que" podem ser usadas apenas com condições de controle de otimização/ocultação de recomendações, que são compatíveis com alguns campos numéricos. Consulte Campos compatíveis com otimização/ocultação.
  • 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 nesse limite. Por exemplo, colors: ANY("red", "green") OR colors: ANY("blue") tem três argumentos.

A tabela a seguir mostra exemplos válidos de expressões de filtro, bem como exemplos inválidos e os motivos pelos quais eles são inválidos.

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 em 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 seus produtos.

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

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

Campos aceitos

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

O Boost/bury for Recommendations AI é compatível com campos adicionais que não são compatíveis com a filtragem de recomendações padrão. Para ver uma lista de campos adicionais compatíveis com o otimizado/otimizar para Recommendations AI, consulte Campos suportados do 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 Boost/bury

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

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

Campos textuais

campo Descrição
"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. Este campo é calculado usando os valores originais de preço e 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 filtragem de recomendações para um modelo

É possível ativar a filtragem para o Recommendations AI usando o Console do Retail ou o recurso da API Models.

No console, crie um novo modelo com a filtragem de recomendações ativada. Você também pode atualizar essa opção para modelos existentes.

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 disponibilização que retorna previsões tiver a correspondência de categoria ativada, a filtragem não funcionará no atributo "categories" porque a resposta retornará apenas os resultados do produto que compartilham uma categoria com o produto de contexto.

Definir a filtragem de um modelo usando o console

Usando o Console do Retail, selecione a opção Gerar tags automaticamente durante a criação do modelo para permitir a filtragem de recomendações para ele.

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 esta configuração no console para modelos existentes. Para atualizar essa configuração em 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 existente.

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

  • RECOMMENDATIONS_FILTERING_DISABLED (padrão): a filtragem está desativada para o modelo.
  • RECOMMENDATIONS_FILTERING_ENABLED: a filtragem está ativada para os 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 de um modelo atual.

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 do produto que você usará nas expressões de filtro. É possível atualizar essa configuração usando o Console do Retail ou o recurso da API Attributes.

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

Definir atributos como filtráveis usando o console

É possível definir um atributo como página de Controles filtrável no Console do Google Cloud.

  1. Acesse a página Controles de varejo no Console do Google Cloud.

    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.

Comece a usar o atributo para filtragem após a conclusão do próximo ciclo de treinamento de modelo.

Definir atributos como filtráveis usando a API

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

Defina o campo AttributesConfig.filteringOption para CatalogAttribute. Os valores permitidos desse 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 do 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 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"

Comece a usar o atributo para filtragem após a conclusão do próximo ciclo de treinamento de modelo.

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

Depois que seu modelo for treinado novamente, será possível usar atributos de produtos filtráveis nas solicitações de previsão.

Defina o valor do parâmetro de solicitação filterSyntaxV2 como verdadeiro 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 permanecerá ativa. Se um modelo tiver tags criadas manualmente e atributos de produto filtráveis, ele poderá exibir solicitações de previsão usando qualquer versão de filtragem. No entanto, não é possível incluir 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 estão 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 prediçã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\")',
        useMostRecentServingConfig: true
     }" \
     "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 exibição também pode afetar o número de resultados retornados pela resposta.