O "Varejo" será renomeado como Vertex AI para Pesquisa para varejo. Estamos atualizando o conteúdo para refletir o novo branding.

Filtrar recomendações

Nesta página, descrevemos os resultados da filtragem de recomendações usando atributos do 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 é restrita aos produtos em que a expressão é avaliada como verdadeira.

Há duas versões de filtragem de 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 as recomendações usando atributos do produto.

Filtragem de recomendações, versão 2

A versão 2 usa atributos do produto. As expressões de filtro são baseadas nos atributos do produto. Eles podem ser atributos predefinidos do sistema, 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 automaticamente como tags para filtrar recomendações, em vez de exigir que você adicione manualmente tags de filtro.

Quando você usa atributos para filtrar produtos, a resposta da previsão retorna os produtos principais que contêm pelo menos um produto principal ou uma variante com um valor de atributo correspondente à expressão do filtro. Para saber mais sobre produtos primários 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 "Nova 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 recomendações, siga estes procedimentos. Cada procedimento será fornecido posteriormente nesta página.

Ative a filtragem de recomendações para um modelo que exibirá as recomendações filtradas.
Ative a filtragem de recomendações para os atributos do produto que você planeja filtrar.
Use atributos de produto filtráveis em solicitações de previsão.

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

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 aos produtos no seu catálogo que planeja 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 saber mais sobre 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 stockState de OUT_OF_STOCK.

É possível combinar filtros de tags e filtros esgotados para que somente itens que atendam 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 apenas itens que estão em estoque e 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 de filtros de atributos e tags

Se um modelo tiver tags criadas manualmente e atributos de produto filtráveis, ele poderá exibir solicitações de previsão usando qualquer uma das versões 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 um pouco de 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 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 ao multiplicar 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 atributos poderá ser estimado como 3*1.000=3.000.

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 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, 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, o treinamento de modelo falhará. Se mais de 10 atributos personalizados filtráveis forem encontrados durante treinamento de modelo, apenas 10 serão usados.

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

As sintaxes da 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 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 da 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 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. 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 textuais, as operações "menor que", "maior que" 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, que são compatíveis com alguns campos numéricos. Consulte Otimizar/ocultar 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 expressões ANY(). Se uma cláusula OR tiver várias expressões ANY(), todos os argumentos 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ão de filtro, além de exemplos inválidos e os motivos da sua 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 dos seus produtos.

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

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

A otimização/ocultação para recomendações oferece suporte a campos adicionais que não são compatíveis com a filtragem de recomendações padrão. Para ver uma lista de outros campos compatíveis com a otimização/ocultação de recomendações, consulte Otimizar/ocultar 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
"conditions"	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 aceita alguns campos extras que não são aceitos pela filtragem de recomendações padrão, incluindo campos numéricos.

Além dos campos listados em Campos compatíveis, a otimização/ocultação para recomendações aceita os seguintes campos:

Campos textuais

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

Campos numéricos

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

Definir filtros de recomendações para um modelo

É possível ativar o filtro para recomendações usando o console do Search for Retail ou o recurso da API Models.

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

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

Se a configuração de exibiçã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 do contexto.

Definir o filtro para 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.

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 dos modelos atuais. Para atualizar essa configuração em um modelo, use o método de API models.Patch.

Definir o filtro para 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 atual.

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 é 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 o filtro de recomendações ativado.

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 os produtos recomendados, ative o filtro para os atributos do produto que você vai usar nas expressões de filtro. É possível atualizar essa configuração usando o console do Search for Retail ou o recurso de 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 página "Controles" filtrável no console da Pesquisa for Retail.

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

Acessar a página "Controles"
Acesse a guia Controles de atributos.

Essa guia exibe uma tabela de todos os atributos de produtos que você pode definir em todo o site.
Clique em Modificar controles.
Defina Filterable como True para o atributo do produto.
Clique em Salvar controles.

É possível começar 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 do produto categories como filtrável.

Ao atualizar um atributo existente, mantenha os valores originais dele para indexableOption, dynamicFacetableOption e searchableOption como 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 abaixo.

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"

É possível começar 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 o modelo for treinado outra vez, será 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 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á veicular solicitações de previsão usando qualquer uma das versões 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. Este exemplo pressupõe 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\")',
        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 veiculação também pode afetar o número de resultados retornados pela resposta.