A Vertex AI para Pesquisa no varejo está sendo renomeada como Vertex AI para Pesquisa no comércio. Estamos atualizando o conteúdo para refletir o novo branding.

Esta página foi traduzida pela API Cloud Translation.

Filtrar recomendações

Nesta página, descrevemos como filtrar resultados de recomendações usando atributos de 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 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 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 prático se aplicam apenas à versão 2 da filtragem, que filtra recomendações usando atributos de 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 de 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 automaticamente esses atributos como tags para filtragem, sem precisar 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 com um valor de atributo que corresponde à expressão de 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 produtos vermelhos ou azuis definidos como "Novidade" e não 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.

Ative a filtragem de recomendações para um modelo que vai fornecer recomendações filtradas.
Ative a filtragem de recomendações para atributos de produtos que você planeja usar.
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 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 marcados como "Vermelho" ou "Azul", além da tag "Novidade", e não são marcados 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 das tags, é possível filtrar por filterOutOfStockItems. A flag filterOutOfStockItems filtra todos os produtos com um stockState de OUT_OF_STOCK.

É possível combinar filtros de tag e de indisponibilidade para que apenas 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 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 entre filtros de atributos e de tags

Se um modelo tiver tags criadas manualmente e atributos de produto filtráveis, ele poderá atender a 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

Adicione manualmente critérios de filtro para restringir o conjunto de recomendações retornadas aos usuários finais. Use a Vertex AI para Pesquisa para Commerce e aplique regras de negócios para ajustar o que os clientes veem, incluindo opções de filtro por disponibilidade do produto, tags personalizadas e outros critérios.

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 catálogo.
Seu catálogo pode ter até 100 milhões de valores de atributos filtráveis.

Para estimar o número total de valores de atributos no seu catálogo, multiplique 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*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 adicionadas ao número total de valores de atributo é menor que 100.000.000.

Se você exceder os limites, não poderá definir mais 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 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 de filtro de recomendações

As sintaxes das expressões 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 de filtro

As seguintes restrições são aplicadas:

A profundidade de operadores de incorporação 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 compatível 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 aceita apenas campos de texto, as operações de menor que, maior que e verificação de intervalo não são compatíveis com ela. As operações de menor que e maior que só podem ser usadas com condições de controle de reforço ou ocultação de recomendações, que oferecem suporte a alguns campos numéricos. Consulte Campos compatíveis com reforç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 delas 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 e inválidas, além dos motivos pelos quais elas são inválidas.

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 se baseia no estado em tempo real dos seus produtos. Para a filtragem availability: ANY("IN_STOCK"), a resposta de 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 aceito pela 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 cláusulas OR.

Campos aceitos

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

O aumento ou a ocultação de recomendações é compatível com outros campos que não são aceitos pela filtragem padrão. Para conferir uma lista desses campos, consulte Campos compatíveis com aumentar/ocultar.

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 otimização/aumento

O aumento/ocultação é compatível com alguns campos extras que não são aceitos pela filtragem padrão de recomendações, incluindo campos numéricos.

Além dos campos listados em Campos aceitos, o aumento/ocultação de 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 no produto. Esse 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 a filtragem de recomendações para um modelo

É possível ativar a filtragem de recomendações usando o console de pesquisa para e-commerce ou o recurso da API Models.

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

Usando o recurso de API Models, é possível criar um 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 exibição que retorna previsões tiver a correspondência de categoria ativada, a filtragem não vai funcionar no atributo "categories" porque a resposta retorna apenas resultados de produtos que compartilham uma categoria com o produto de contexto.

Definir filtragem para um modelo usando o console

No console da Pesquisa para e-commerce, selecione a opção Gerar tags automaticamente durante a criação do modelo para permitir a filtragem de recomendações para ele.

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

Por exemplo, a combinação de diversity-level e category attribute filtering baseados em regras geralmente resulta em uma saída vazia.
- diversity-level=high-diversity força o modelo a limitar o número máximo de resultados 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.
No caso do modelo similar-items, ele 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 de um modelo, use o método da API models.Patch.

Definir a filtragem para um modelo usando a API

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

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

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

O exemplo de curl a seguir cria um 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 os produtos recomendados, ative a filtragem dos atributos que você vai usar nas expressões de filtro. É possível atualizar essa configuração usando o console da Pesquisa para e-commerce 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 filtrável na página "Controles" no console "Pesquisa para comércio".

Acesse a página Controles no console da Pesquisa para e-commerce.

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 Filtrável como Verdadeiro para o atributo do produto.
Clique em Salvar controles.

Você pode começar a usar o atributo para filtragem depois que o próximo ciclo de 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 seus atributos de produto 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ê pode começar a usar o atributo para filtragem depois que o próximo ciclo de 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 retreinado, 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 continuar ativa. Se um modelo tiver tags criadas manualmente e atributos de produto filtráveis, ele poderá atender a 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 parcial de curl a seguir mostra filterSyntaxV2 definido como "true" e uma expressão de filtro usando os atributos de produto colors e categories. Este exemplo pressupõe 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 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.