Filtre recomendações

Esta página descreve a filtragem de resultados para recomendações através de atributos dos produtos.

Pode filtrar os resultados da previsão especificando uma expressão de filtro em pedidos de previsão. A expressão de filtro é uma expressão lógica que é avaliada para cada produto. A lista de produtos na resposta é restrita aos produtos em que a expressão é avaliada como verdadeira.

Existem duas versões de filtragem para recomendações:

  • Recomendamos a versão 2.
  • A versão 1 está descontinuada, mas ainda pode estar em utilização.

As secções deste guia de instruções aplicam-se apenas à versão 2 da filtragem, que filtra as recomendações através dos atributos dos produtos.

Filtragem de recomendações, versão 2

A versão 2 usa atributos de produtos. As expressões de filtro baseiam-se nos atributos dos produtos. Podem ser atributos do sistema predefinidos, como categories e colors, ou atributos personalizados que define, como attributes.styles. Quando define um atributo do produto como filtrável, as recomendações podem usar automaticamente esses atributos como etiquetas para a filtragem de recomendações, em vez de exigir que adicione manualmente etiquetas de filtro.

Quando usa atributos para filtrar produtos, a resposta de previsão devolve 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 acerca dos produtos principais e variantes, consulte o artigo Níveis de produtos.

O exemplo de expressão de filtro seguinte 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 apresentar recomendações filtradas.
  2. Ative a filtragem de recomendações para atributos dos produtos que planeia usar para filtragem.
  3. Use atributos de produtos filtráveis em pedidos de previsão.

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

A versão 1 usa etiquetas de filtro criadas manualmente. As expressões de filtro baseiam-se em etiquetas de filtro, que tem de adicionar manualmente a todos os produtos no seu catálogo que planeia filtrar.

O exemplo de expressão de filtro seguinte usa etiquetas de filtro para especificar produtos etiquetados como "Vermelho" ou "Azul", bem como a etiqueta "New-Arrival", e não estão etiquetados 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 etiquetas podem conter os operadores booleanos OR ou NOT, que têm de ser separados dos valores das etiquetas por um ou mais espaços. Também pode antepor imediatamente um traço (-) aos valores das etiquetas, o que é equivalente ao operador NOT. As expressões de etiquetas que usam os operadores booleanos têm de estar entre parênteses.

Além das etiquetas, pode filtrar por filterOutOfStockItems. A opção filterOutOfStockItems filtra todos os produtos com um stockState de OUT_OF_STOCK.

Pode combinar filtros de etiquetas e filtros de esgotado para que apenas sejam devolvidos os itens que satisfaçam todas as expressões de filtro especificadas.

Alguns exemplos de strings de filtro:

"filter": "tag=\"spring-sale\""

"filter": "filterOutOfStockItems"

"filter": "tag=\"spring-sale\" tag=\"exclusive\" filterOutOfStockItems"

O exemplo seguinte devolve apenas itens em stock que tenham a etiqueta spring-sale ou exclusive (ou ambas) e que também não tenham a etiqueta items-to-exclude.

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

Compatibilidade entre o filtro de atributos e o filtro de etiquetas

Se um modelo tiver etiquetas criadas manualmente e atributos dos produtos filtráveis, pode publicar pedidos 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 no mesmo pedido de previsão.

Limites de filtragem de recomendações

Adicione manualmente critérios de filtro para restringir o conjunto de recomendações devolvidas aos utilizadores finais. Use a Vertex AI Search for commerce para aplicar regras empresariais para otimizar o que os clientes veem, incluindo opções de filtragem por disponibilidade do produto, etiquetas personalizadas e outros critérios.

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

  • Pode definir até 10 atributos personalizados como filtráveis no seu catálogo.

  • Podem estar presentes até 100 000 000 de valores de atributos filtráveis no seu catálogo.

    Pode estimar o número total de valores de atributos no seu catálogo multiplicando o número de produtos no catálogo pelo número de atributos filtráveis.

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

    Se estiver a usar a filtragem de recomendações da versão 1 juntamente com a versão 2, o número de etiquetas de filtro conta para a sua quota. Certifique-se de que o número de etiquetas de filtro adicionadas ao número total de valores de atributos é inferior a 100 000 000.

Se exceder os limites, não pode definir atributos adicionais como filtráveis. Se precisar de exceder estes limites, peça um aumento da quota.

O número total de etiquetas é calculado durante a preparação do modelo. Se o número total exceder o limite, a preparação do modelo falha. Se forem encontrados mais de 10 atributos personalizados filtráveis durante a preparação do modelo, apenas são usados 10.

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

As sintaxes das expressões de filtro para a pesquisa e as 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 pela 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 filtros

Aplicam-se as seguintes restrições:

  • A profundidade da incorporação dos operadores AND e OR entre parênteses é limitada. As expressões lógicas no filtro têm de estar na forma normal conjuntiva (CNF). A expressão lógica mais complexa suportada pode ser uma lista de cláusulas ligadas por AND que contenham apenas operadores OR, como: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
  • As expressões podem ser negadas com a palavra-chave NOT ou com -. Isto só funciona com expressões ANY() com um único argumento que não incluem atributos relacionados com o inventário.
  • As restrições baseadas em availability têm de estar no nível superior. Não podem ser usados como parte de uma cláusula OR ou uma negação (NOT).
  • Uma vez que a filtragem de recomendações padrão só suporta campos de texto, as operações de verificação de intervalo, inferior a e superior a não são suportadas para a filtragem de recomendações padrão. As operações inferior a e superior a só podem ser usadas com condições de controlo de amplificação ou ocultação de recomendações, que suportam alguns campos numéricos (consulte Campos suportados de amplificaçã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 respetivos argumentos são contabilizados para este limite. Por exemplo, colors: ANY("red", "green") OR colors: ANY("blue") tem três argumentos. Para o exemplo de utilização do Vertex AI Search for commerce, pode considerar um argumento como o equivalente a um valor de atributo.

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

Expressão Válido Notas
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 numa expressão OR com outras condições.

Filtragem de atributos relacionados com o inventário

A filtragem com base em atributos relacionados com o inventário baseia-se no estado em tempo real dos seus produtos. Para a filtragem availability: ANY("IN_STOCK"), a resposta de previsão devolve produtos principais em que o produto principal ou uma variante tem o valor correspondente de IN_STOCK. Para saber mais acerca dos produtos principais e variantes, consulte o artigo Níveis de produtos. Não suportamos a filtragem Primary only nem Variant only.

IN_STOCK é o único valor do atributo availability suportado pela versão 2 da filtragem de recomendações.

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

Campos suportados

Os campos de texto suportados estão resumidos na tabela seguinte.

Aumentar ou ocultar para recomendações suporta campos adicionais que não são suportados pela filtragem de recomendações padrão. Para ver uma lista destes campos, consulte o artigo Campos suportados para aumentar/diminuir a visibilidade.

campo descrição
"productId" O ID do produto (o último segmento de Product.name).
"brands" O elemento Product.brands.
"categories" O elemento Product.categories.
"genders" The Audience.genders.
"ageGroups" O Audience.age_groups.
"colorFamilies" O ColorInfo.color_families.
"colors" The ColorInfo.colors.
"sizes" O elemento Product.sizes.
"materials" O Product.materials.
"patterns" O Product.patterns.
"condições" O elemento Product.conditions.
"attributes.key" O atributo personalizado textual no objeto Product. A chave pode ser qualquer chave no mapa Product.attributes, se os valores dos atributos forem textuais.

Campos suportados para aumentar/diminuir a visibilidade

A funcionalidade de aumentar/diminuir a prioridade suporta alguns campos adicionais que não são suportados pela filtragem de recomendações padrão, incluindo campos numéricos.

Além dos campos indicados em Campos suportados, o aumento/ocultação para recomendações suporta os seguintes campos:

Campos textuais

campo descrição
"tags" Product.tags[]. Etiquetas personalizadas associadas ao produto.

Campos numéricos

campo descrição
"price" PriceInfo.price. O preço do produto.
"discount" O desconto do produto. Este campo é calculado com base nos valores dos campos de preço e preço original de PriceInfo.
"rating" Product.rating. O número total de classificações do produto.
"ratingCount" rating.ratingCount. O número total de classificações do produto.

Defina a filtragem de recomendações para um modelo

Pode ativar a filtragem de recomendações através da consola de pesquisa para comércio ou do recurso da API Models.

Na consola, pode criar um novo modelo com a filtragem de recomendações ativada. Também pode atualizar esta opção para modelos existentes.

Através do recurso da API Models, pode criar um novo modelo com a filtragem de recomendações ativada ou atualizar esta definição para um modelo existente através de models.Patch.

Tenha em atenção que, se a configuração de publicação que devolve previsões tiver a correspondência de categorias ativada, a filtragem não funciona no atributo "categories" porque a resposta devolve apenas resultados de produtos que partilham uma categoria com o produto de contexto.

Defina a filtragem para um modelo através da consola

Na consola de pesquisa de comércio, selecione a opção Gerar etiquetas automaticamente durante a criação do modelo para permitir a filtragem de recomendações para esse modelo.

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

  • Por exemplo, a combinação de diversity-level com base em regras e category attribute filtering resulta frequentemente numa saída vazia.
    • diversity-level=high-diversity força o modelo a limitar os resultados máximos para as mesmas strings de categorias. Ou seja, 1 resultado para a categoria 1, 1 resultado para a categoria 2, etc.
    • A filtragem de atributos com metadados de categorias (Product.categories = ANY ("category2")) faz com que o modelo rejeite os artigos que não correspondem.
    • A saída final tem menos de três resultados.
  • Para o modelo similar-items, já contém um aumento da relevância da categoria adicional com o valor predefinido category-match-level = relaxed-category-match. Mude para category-match-level=no-category-match para desativar o comportamento e usar regras de filtragem personalizadas.

Consulte o artigo Crie modelos de recomendações para ver instruções sobre como criar um modelo de recomendações através da consola.

Não é possível atualizar esta definição na consola para modelos existentes. Para atualizar esta definição para um modelo, use o método da API models.Patch.

Defina a filtragem para um modelo através da API

Pode ativar a filtragem de recomendações para um modelo através de models.Create quando cria um novo modelo ou models.Patch quando atualiza um modelo existente.

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

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

O exemplo de curl seguinte 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 seguinte exemplo de curl atualiza a definiçã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"

Defina atributos como filtráveis

Para filtrar produtos recomendados, ative a filtragem para os atributos do produto que vai usar em expressões de filtro. Pode atualizar esta definição através da consola de pesquisa de comércio ou do recurso da API Attributes.

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

Defina atributos como filtráveis através da consola

Pode definir um atributo como filtrável na página de controlos na consola de pesquisa para comércio.

  1. Aceda à página Controlos na consola de pesquisa para comércio.

    Aceda à página Controlos

  2. Aceda ao separador Controlos de atributos.

    Este separador apresenta uma tabela de todos os atributos dos produtos para os quais pode definir controlos ao nível do site.

  3. Clique em Modificar controlos.

  4. Defina Filterable como True para o atributo do produto.

  5. Clique em Guardar controlos.

Pode começar a usar o atributo para filtragem após a conclusão do ciclo de preparação do modelo seguinte.

Defina atributos como filtráveis através da API

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

Defina o campo AttributesConfig.filteringOption para CatalogAttribute. Os valores permitidos deste campo são:

  • RECOMMENDATIONS_FILTERING_DISABLED (predefinição): a filtragem está desativada para o atributo.
  • RECOMMENDATIONS_FILTERING_ENABLED: a filtragem está ativada para o atributo.

O exemplo de curl seguinte consulta os atributos dos produtos 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 seguinte define o atributo do produto categories como filtrável.

Quando atualiza um atributo existente, mantenha os valores originais do atributo para indexableOption, dynamicFacetableOption e searchableOption, tal como aparecem no passo anterior. Se o atributo escolhido não aparecer quando visualizar attributesConfig, tal como no exemplo anterior, use as definições predefinidas, conforme mostrado no exemplo seguinte.

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"

Pode começar a usar o atributo para filtragem após a conclusão do ciclo de preparação do modelo seguinte. Normalmente, este processo demora, pelo menos, oito horas.

Use atributos filtráveis num pedido de previsão

Depois de voltar a formar o modelo, pode usar atributos de produtos filtráveis nos pedidos de previsão.

Defina o valor do parâmetro de pedido filterSyntaxV2 como verdadeiro para ativar a filtragem de recomendações da versão 2. Se o parâmetro não estiver definido, a filtragem da versão 1 permanece ativa. Se um modelo tiver etiquetas criadas manualmente e atributos de produtos filtráveis, pode publicar pedidos 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 no mesmo pedido de previsão.

O exemplo de curl parcial seguinte mostra filterSyntaxV2 definido como verdadeiro e uma expressão de filtro que usa os atributos do 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 seguinte mostra um pedido de previsão completo.

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 definição de diversificação da configuração de publicação também pode afetar o número de resultados devolvidos pela resposta.