Filtrer les recommandations

Cette page explique comment filtrer les résultats des recommandations à l'aide d'attributs de produit.

Vous pouvez filtrer les résultats de prédiction en spécifiant une expression de filtre dans les requêtes de prédiction. L'expression de filtre est une expression logique qui est évaluée pour chaque produit. La liste des produits dans la réponse est limitée aux produits pour lesquels l'expression est évaluée sur "true".

Remarque : Il peut s'écouler jusqu'à huit heures avant que les mises à jour d'expressions de tag ne soient utilisables pour filtrer les prédictions avec les versions 1 et 2, y compris pour les configurations d'attributs de filtrage et les modifications de métadonnées au niveau du produit. Seul le champ Availability est mis à jour en temps réel.

Il existe deux versions de filtrage pour les recommandations :

La version 2 est recommandée.
La version 1 est obsolète, mais peut encore être utilisée.

Les sections de ce guide d'utilisation ne s'appliquent qu'à la version 2 du filtrage, qui filtre les recommandations à l'aide d'attributs de produit.

Filtrage des recommandations, version 2

La version 2 utilise des attributs de produit. Les expressions de filtre sont basées sur des attributs de produit. Il peut s'agir d'attributs système prédéfinis, tels que categories et colors, ou d'attributs personnalisés que vous définissez, tels que attributes.styles. Lorsque vous définissez un attribut de produit comme filtrable, les recommandations peuvent ensuite utiliser automatiquement ces attributs comme tags pour le filtrage des recommandations, au lieu de vous obliger à ajouter manuellement des tags de filtre.

Lorsque vous utilisez des attributs pour filtrer des produits, la réponse de prédiction renvoie les produits principaux qui contiennent au moins un produit principal ou une variante dont la valeur d'attribut correspond à l'expression de filtre. Pour en savoir plus sur les produits principaux et les variantes de produits, consultez Niveaux de produit.

L'exemple d'expression de filtre suivant filtre également tous les produits rouges ou bleus définis comme "Nouveautés" et non définis comme promotionnels :

colors: ANY("red", "blue") AND attributes.status: ANY("New-Arrival") AND NOT attributes.is_promotional: ANY("true")

Pour utiliser la version 2 du filtrage pour les recommandations, suivez ces procédures. Chaque procédure est présentée plus loin sur cette page.

Activez le filtrage des recommandations pour un modèle qui diffusera des recommandations filtrées.
Activez le filtrage des recommandations pour les attributs de produit sur lesquels vous prévoyez d'appliquer un filtre.
Utilisez des attributs de produit filtrables dans les requêtes de prédiction.

Filtrage des recommandations, version 1 (obsolète)

La version 1 utilise des tags de filtre créés manuellement. Les expressions de filtre sont basées sur des tags de filtre, que vous devez ajouter manuellement à tous les produits de votre catalogue que vous prévoyez de filtrer.

L'exemple d'expression de filtre suivant utilise des tags de filtre pour spécifier les produits tagués comme "Rouge" ou "Bleu", ainsi que le tag "Nouveautés", et qui ne sont pas tagués comme "promotionnels" :

tag=("Red" OR "Blue") tag="New-Arrival" tag=(NOT "promotional")

Consultez la documentation de référence de l'API pour le Product.tags[] champ.

Les expressions de tag peuvent contenir les opérateurs booléens OR ou NOT, qui doivent être séparés des valeurs de tag par un ou plusieurs espaces. Les valeurs de tag peuvent également être immédiatement précédées d'un tiret (-), ce qui équivaut à l'opérateur NOT. Les expressions de tag qui utilisent les opérateurs booléens doivent être placées entre parenthèses.

En plus des tags, vous pouvez filtrer par filterOutOfStockItems. L'indicateur filterOutOfStockItems filtre tous les produits dont le champ stockState a la valeur OUT_OF_STOCK.

Vous pouvez combiner des filtres de tag et des filtres de produits en rupture de stock afin que seuls les éléments qui répondent à toutes les expressions de filtre spécifiées soient renvoyés.

Voici quelques exemples de chaînes de filtre :

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

"filter": "filterOutOfStockItems"

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

L'exemple suivant renvoie uniquement les articles en stock qui ont le tag spring-sale ou exclusive (ou les deux), mais pas le tag items-to-exclude.

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

Compatibilité entre les filtres d'attributs et les filtres de tags

Si un modèle comporte à la fois des tags créés manuellement et des attributs de produit filtrables, il peut diffuser des requêtes de prédiction à l'aide de l'une ou l'autre des versions de filtrage. Toutefois, il n'est pas possible d'inclure à la fois des expressions de filtrage de la version 1 et de la version 2 dans la même requête de prédiction.

Limites du filtrage des recommandations

Ajoutez manuellement des critères de filtre pour limiter l'ensemble des recommandations renvoyées aux utilisateurs finaux. Utilisez AI Commerce Search pour appliquer des règles métier afin d'ajuster ce que voient les clients, y compris des options permettant de filtrer par disponibilité du produit, balises personnalisées et autres critères.

Chaque attribut filtrable consomme de la mémoire dans chacun de vos modèles. Les limites suivantes permettent d'éviter les effets négatifs sur les performances de diffusion :

Vous pouvez définir jusqu'à 10 attributs personnalisés comme filtrables dans votre catalogue.
Votre catalogue peut contenir jusqu'à 100 000 000 de valeurs d'attributs filtrables.

Vous pouvez estimer le nombre total de valeurs d'attributs dans votre catalogue en multipliant le nombre de produits dans votre catalogue par le nombre d'attributs filtrables.

Par exemple, si vous disposez d'un catalogue de 1 000 produits et de 3 attributs définis comme filtrables, le nombre total de valeurs d'attributs peut être estimé à 3 x 1 000=3 000.

Si vous utilisez le filtrage des recommandations de la version 1 en même temps que la version 2, le nombre de tags de filtre est pris en compte dans votre quota. Assurez-vous que le nombre de tags de filtre ajoutés au nombre total de valeurs d'attributs est inférieur à 100 000 000.

Si vous dépassez les limites, vous ne pourrez plus définir d'attributs supplémentaires comme filtrables. Si vous devez dépasser ces limites, demandez une augmentation de quota.

Le nombre total de tags est calculé lors de l'entraînement du modèle. Si le nombre total dépasse la limite, l'entraînement du modèle échoue. Si plus de 10 attributs personnalisés filtrables sont trouvés lors de l'entraînement de modèle, seuls 10 sont utilisés.

Syntaxe des expressions de filtre des recommandations

Les syntaxes des expressions de filtre pour la recherche et les recommandations sont similaires. Toutefois, les recommandations présentent plusieurs limites.

La syntaxe de l'expression de filtre des recommandations peut être résumée par le EBNF suivant :

  # 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;

Restrictions de la syntaxe des filtres

Les restrictions suivantes s'appliquent :

La profondeur d'intégration des opérateurs AND et OR entre parenthèses est limitée. Les expressions logiques du filtre doivent être au format normal conjonctif (CNF). L'expression logique la plus complexe acceptée peut être une liste de clauses connectées par AND qui ne contiennent que des opérateurs OR, par exemple : (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
Les expressions peuvent être niées avec le mot clé NOT ou avec -. Cela ne fonctionne qu'avec les expressions ANY() avec un seul argument qui n'incluent pas d'attributs liés à l'inventaire.
Les restrictions basées sur availability doivent être au niveau supérieur. Elles ne peuvent pas être utilisées dans une clause OR ni dans une négation (NOT).
Étant donné que le filtrage des recommandations standards n'accepte que les champs textuels, les opérations de type "inférieur à", "supérieur à" et "vérification de plage" ne sont pas acceptées pour le filtrage des recommandations standards. Les opérations de type "inférieur à" et "supérieur à" peuvent être utilisées uniquement avec les conditions de contrôle de boost ou d'enfouissement des recommandations, qui acceptent certains champs numériques (voir Champs acceptés pour le boost/l'enfouissement).
Le nombre maximal de termes dans la clause AND de premier niveau est de 20.
Une clause OR peut comporter jusqu'à 100 arguments inclus dans les expressions ANY(). Si une clause OR comporte plusieurs expressions ANY(), tous leurs arguments sont pris en compte dans cette limite. Par exemple, colors: ANY("red", "green") OR colors: ANY("blue") comporte trois arguments. Pour le cas d'utilisation d'AI Commerce Search, vous pouvez considérer un argument comme l'équivalent d'une valeur d'attribut.

Le tableau suivant présente des exemples d'expressions de filtre valides, ainsi que des exemples non valides et les raisons pour lesquelles ils ne sont pas valides.

Expression	Valide	Remarques
`colors: ANY("red", "green")`	Oui
`NOT colors: ANY("red")`	Oui
`NOT colors: ANY("red", green")`	Non	Négation d'un `ANY()` avec plus d'un argument.
`colors: ANY("red", "green") OR categories: ANY(\"Phone > Android > Pixel\")`	Oui
`(colors: ANY("red") OR colors: ANY("green")) AND categories: ANY(\"Phone > Android > Pixel\")`	Oui
`(colors: ANY("red") AND colors: ANY("green")) OR categories: ANY(\"Phone > Android > Pixel\")`	Non	Ne respecte pas le format normal conjonctif.
`(colors: ANY("red")) AND (availability: ANY("IN_STOCK")`	Oui
`(colors: ANY("red")) OR (availability: ANY("IN_STOCK"))`	Non	Combine `availability` dans une expression `OR` avec d'autres conditions.

Filtrage des attributs liés à l'inventaire

Le filtrage des attributs liés à l'inventaire est basé sur l'état en temps réel de vos produits. Pour le filtrage availability: ANY("IN_STOCK"), la réponse de prédiction renvoie les produits principaux pour lesquels le produit principal ou une variante a la valeur correspondante IN_STOCK. Pour en savoir plus sur les produits principaux et les variantes de produits, consultez Niveaux de produit. Nous n'acceptons pas le filtrage Primary only ni Variant only.

IN_STOCK est la seule valeur de l'attribut availability acceptée par la version 2 du filtrage des recommandations.

Les attributs liés à l'inventaire peuvent être utilisés dans les clauses AND, mais pas dans les clauses OR.

Champs pris en charge

Le tableau suivant récapitule les champs textuels acceptés.

Le boost ou l'enfouissement pour les recommandations prend en charge des champs supplémentaires qui ne sont pas disponibles pour le filtrage des recommandations standards. Pour obtenir la liste de ces champs, consultez Champs acceptés pour le boost/l'enfouissement.

champ	description
"productId"	Identifiant du produit (dernier segment de Product.name).
"chaînes"	Champ Product.brands.
"categories"	Champ Product.categories.
"genders"	Champ Audience.genders.
"ageGroups"	Champ Audience.age_groups.
"colorFamilies"	Champ ColorInfo.color_families.
"colors"	Champ ColorInfo.colors.
"sizes"	Champ Product.sizes.
"materials"	Champ Product.materials.
"patterns"	Champ Product.patterns.
"conditions"	Champ Product.conditions.
"attributes.key"	Attribut de texte personnalisé dans l'objet Product. La clé peut être n'importe quelle clé du champ Product.attributes si les valeurs des attributs sont textuelles.

Champs acceptés pour le boost/l'enfouissement

Le boost/l'enfouissement accepte certains champs supplémentaires qui ne sont pas pris en charge par le filtrage des recommandations standards, y compris les champs numériques.

En plus des champs listés dans Champs pris en charge, le boost/l'enfouissement des recommandations accepte les champs suivants :

Champs textuels

champ	description
"tags"	`Product.tags[]`. Tags personnalisés associés au produit.

Champs numériques

champ	description
"price"	`PriceInfo.price`. Prix du produit.
"discount"	Réduction sur le produit. Ce champ est calculé à l'aide des valeurs des champs "prix d'origine" et "prix" de `PriceInfo`.
"rating"	`Product.rating`. Nombre total de notes données au produit.
"ratingCount"	`rating.ratingCount`. Nombre total de notes données au produit.

Définir le filtrage des recommandations pour un modèle

Vous pouvez activer le filtrage des recommandations à l'aide d'AI Commerce Search dans la console Gemini Enterprise for Customer Experience ou de la ressource d'API Models.

Dans la console, vous pouvez créer un modèle pour lequel le filtrage des recommandations est activé. Vous pouvez également modifier cette option pour les modèles existants.

À l'aide de la ressource d'API Models, vous pouvez créer un modèle pour lequel le filtrage des recommandations est activé ou modifier ce paramètre pour un modèle existant à l'aide de models.Patch.

Notez que si la configuration de diffusion qui renvoie des prédictions a la correspondance de catégorie activée, le filtrage ne fonctionne pas avec l'attribut "categories", car la réponse ne renvoie que les résultats de produits qui partagent une catégorie avec le produit contextuel.

Définir le filtrage pour un modèle à l'aide de la console

À l'aide d'AI Commerce Search dans la console Gemini Enterprise for Customer Experience, sélectionnez l'option Générer automatiquement des tags lors de la création du modèle pour autoriser le filtrage des recommandations pour ce modèle.

Vérifiez la compatibilité avec d'autres paramètres tels que diversity-level et category-match-level, car les effets totaux se combinent et le filtrage a lieu en dernier.

Par exemple, la combinaison de diversity-level basé sur des règles et de category attribute filtering entraîne souvent une sortie vide.
- diversity-level=high-diversity force le modèle à limiter le nombre maximal de résultats pour les mêmes chaînes de catégorie. Par exemple, un résultat pour la catégorie 1, un résultat pour la catégorie 2, etc.
- Le filtrage des attributs à l'aide de métadonnées de catégorie (Product.categories = ANY ("category2")) entraîne la suppression par le modèle des éléments qui ne correspondent pas.
- La sortie finale comporte moins de trois résultats.
Pour le modèle similar-items, il contient déjà un boost de pertinence de catégorie supplémentaire avec la valeur par défaut category-match-level = relaxed-category-match. Passez à category-match-level=no-category-match pour désactiver le comportement et utiliser des règles de filtrage personnalisées.

Pour savoir comment créer un modèle de recommandation à l'aide de la console, consultez Créer des modèles de recommandation.

Vous ne pouvez pas modifier ce paramètre dans la console pour les modèles existants. Pour modifier ce paramètre pour un modèle, utilisez la models.Patch méthode d'API.

Définir le filtrage pour un modèle à l'aide de l'API

Vous pouvez activer le filtrage des recommandations pour un modèle à l'aide de models.Create lors de la création d'un modèle ou de models.Patch lors de la modification d'un modèle existant.

Pour autoriser le filtrage, définissez le champ filteringOption pour votre modèle. Voici les valeurs acceptées pour ce champ :

RECOMMENDATIONS_FILTERING_DISABLED (valeur par défaut) : le filtrage est désactivé pour le modèle.
RECOMMENDATIONS_FILTERING_ENABLED: le filtrage est activé pour les produits principaux.

L'exemple curl suivant crée un modèle pour lequel le filtrage des recommandations est activé.

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"

L'exemple curl suivant modifie le paramètre d'option de filtrage pour un modèle existant.

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"

Définir des attributs comme filtrables

Pour filtrer les produits recommandés, activez le filtrage pour les attributs de produit que vous utiliserez dans les expressions de filtre. Vous pouvez modifier ce paramètre à l'aide d'AI Commerce Search dans la console Gemini Enterprise for Customer Experience ou à l'aide de la ressource d'API Attributes.

Ne définissez pas plus d'attributs comme filtrables que nécessaire. Le nombre d'attributs filtrables est limité.

Définir des attributs comme filtrables à l'aide de la console

Vous pouvez définir un attribut comme filtrable sur la page "Contrôles" dans la console AI Commerce Search in Gemini Enterprise for Customer Experience.

Accédez à la page Contrôles d'AI Commerce Search dans la console Gemini Enterprise for Customer Experience.

Accéder à la page "Contrôles"
Accédez à l'onglet Contrôles des attributs.

Cet onglet affiche un tableau de tous les attributs de produit pour lesquels vous pouvez définir des contrôles sur l'ensemble du site.
Cliquez sur Modifier les contrôles.
Définissez Filtrable sur True pour l'attribut de produit.
Cliquez sur Enregistrer les contrôles.

Vous pourrez commencer à utiliser l'attribut pour le filtrage une fois le prochain cycle d'entraînement du modèle terminé.

Définir des attributs comme filtrables à l'aide de l'API

AttributesConfig représente une liste d'attributs pour un catalogue.

Définissez le champ AttributesConfig.filteringOption pour CatalogAttribute. Voici les valeurs acceptées pour ce champ :

RECOMMENDATIONS_FILTERING_DISABLED (valeur par défaut) : le filtrage est désactivé pour l'attribut.
RECOMMENDATIONS_FILTERING_ENABLED : le filtrage est activé pour l'attribut.

L'exemple curl suivant interroge vos attributs de produit existants.

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"

L'exemple curl suivant définit l'attribut de produit categories comme filtrable.

Lorsque vous modifiez un attribut existant, conservez les valeurs d'origine de l'attribut pour indexableOption, dynamicFacetableOption et searchableOption telles qu'elles apparaissent à l'étape précédente. Si l'attribut que vous avez choisi n'apparaît pas lorsque vous affichez attributesConfig comme dans l'exemple précédent, utilisez les paramètres par défaut comme indiqué dans l'exemple suivant.

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"

Vous pourrez commencer à utiliser l'attribut pour le filtrage une fois le prochain cycle d'entraînement du modèle terminé. Cela prend généralement au moins huit heures.

Utiliser des attributs filtrables dans une requête de prédiction

Une fois votre modèle réentraîné, vous pouvez utiliser des attributs de produit filtrables dans vos requêtes de prédiction.

Définissez la valeur du paramètre de requête filterSyntaxV2 sur "true" pour activer le filtrage des recommandations de la version 2. Si le paramètre n'est pas défini, le filtrage de la version 1 reste actif. Si un modèle comporte à la fois des tags créés manuellement et des attributs de produit filtrables, il peut diffuser des requêtes de prédiction à l'aide de l'une ou l'autre des versions de filtrage. Toutefois, il n'est pas possible d'inclure à la fois des expressions de filtrage de la version 1 et de la version 2 dans la même requête de prédiction.

L'exemple curl partiel suivant montre filterSyntaxV2 défini sur "true" et une expression de filtre utilisant les attributs de produit colors et categories. Cet exemple suppose que colors et categories sont définis comme filtrables.

"params": {
  "filterSyntaxV2": true
},
"filter": "(categories: ANY(\"Phone > Android > Pixel\") OR colors: ANY(\"red\", \"green\")) AND (availability: ANY(\"IN_STOCK\"))"

L'exemple curl suivant montre une requête de prédiction complète.

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"

En plus des filtres, le paramètre de diversification de la configuration de diffusion peut également affecter le nombre de résultats renvoyés par la réponse.

Filtrer les recommandations Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Filtrage des recommandations, version 2

Filtrage des recommandations, version 1 (obsolète)

Compatibilité entre les filtres d'attributs et les filtres de tags

Limites du filtrage des recommandations

Syntaxe des expressions de filtre des recommandations

Restrictions de la syntaxe des filtres

Filtrage des attributs liés à l'inventaire

Champs pris en charge

Champs acceptés pour le boost/l'enfouissement

Champs textuels

Champs numériques

Définir le filtrage des recommandations pour un modèle

Définir le filtrage pour un modèle à l'aide de la console

Définir le filtrage pour un modèle à l'aide de l'API

Définir des attributs comme filtrables

Définir des attributs comme filtrables à l'aide de la console

Définir des attributs comme filtrables à l'aide de l'API

Utiliser des attributs filtrables dans une requête de prédiction

Filtrer les recommandations