"Retail" devient Vertex AI Search pour le commerce. Nous sommes en train de mettre à jour le contenu pour refléter le nouveau branding.

Cette page a été traduite par l'API Cloud Translation.

Filtrer les recommandations

Cette page décrit le filtrage des résultats pour les 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 réduite aux produits pour lesquels l'expression renvoie la valeur "true".

Il existe deux versions de filtrage des 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#39;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 les attributs de produit. Les expressions de filtre sont basées sur les 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 alors automatiquement utiliser ces attributs en tant que balises pour le filtrage des recommandations, ce qui vous évite d'avoir à ajouter manuellement des balises de filtre.

Lorsque vous utilisez des attributs pour filtrer des produits, la réponse de prédiction renvoie les produits principaux contenant 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 la section Niveaux de produit.

L'exemple d'expression de filtre suivant filtre également tous les produits rouges ou bleus définis sur "New-Arrival" (Nouvelle-arrivée), 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 que vous prévoyez de filtrer.
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 balises de filtre pour spécifier les produits marqués "Rouge" ou "Bleu", ainsi que le tag "New-Arrival", sans le marquage "promotional":

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

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

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 l'attribut stockState est défini sur OUT_OF_STOCK.

Vous pouvez combiner des filtres de tag et des filtres d'articles non disponibles afin que seuls les articles 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 ne renvoie que les articles en stock avec la balise spring-sale ou exclusive (ou les deux), et qui ne comportent pas non plus la balise items-to-exclude.

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

Compatibilité des filtres d'attributs et des filtres de tag

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 v1 et v2 dans la même requête de prédiction.

Limites de filtrage des recommandations

Chaque attribut filtrable consomme de la mémoire dans chacun de vos modèles. Les limites suivantes permettent d'éviter des 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.

Le nombre total de valeurs d'attributs dans votre catalogue peut être estimé en multipliant le nombre de produits de votre catalogue par le nombre d'attributs filtrables.

Par exemple, si votre catalogue contient 1 000 produits et 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 comptabilisé dans votre quota. Assurez-vous que le nombre de balises de filtre ajoutées au nombre total de valeurs d'attribut est inférieur à 100 000 000.

Si vous dépassez ces limites, vous ne pouvez pas 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é pendant 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 du modèle, seuls 10 d'entre eux sont utilisés.

Syntaxe de l'expression de filtre de recommandations

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

La syntaxe de l'expression de filtre de recommandations peut être résumée par le code 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 syntaxe des filtres

Les restrictions suivantes s'appliquent :

La profondeur des opérateurs AND et OR entre parenthèses est limitée. Les expressions logiques du filtre doivent être sous forme normale conjonctive (CNF). L'expression logique acceptée la plus complexe peut être une liste de clauses connectées par AND qui ne contiennent que des opérateurs OR, tels que: (... OR ... OR ...) AND (... OR ...) AND (... OR ...)
Les expressions peuvent être inversées à l'aide du mot clé NOT ou de -. Cela ne fonctionne qu'avec les expressions ANY() comportant un seul argument qui n'inclut pas d'attributs liés à l'inventaire.
Les restrictions basées sur availability doivent être définies au niveau le plus élevé. Elles ne peuvent pas être utilisées dans une clause OR ou une négation (NOT).
Étant donné que le filtrage de recommandations standard n'accepte que les champs textuels, les opérations "inférieur à", "supérieur à" et de vérification de la plage ne sont pas compatibles avec le filtrage des recommandations standards. Les opérations "inférieur à" et "supérieur à" ne peuvent être utilisées qu'avec des conditions de contrôle d'optimisation/rétrogradation des recommandations, qui sont compatibles avec certains champs numériques (consultez la section Champs compatibles avec le boosting/rétrogradation).
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(), leurs arguments sont tous comptabilisés dans cette limite. Par exemple, colors: ANY("red", "green") OR colors: ANY("blue") comporte trois arguments.

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	Annule une fonction `ANY()` contenant plusieurs arguments.
`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	Pas en forme normale conjonctive.
`(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 dont le produit principal ou une variante a la valeur de correspondance IN_STOCK. Pour en savoir plus sur les produits principaux et les variantes de produits, consultez la section Niveaux de produit. Nous ne prenons pas en charge les filtres Primary only ou Variant only.

IN_STOCK est la seule valeur d'attribut availability compatible avec la version 2 du filtrage des recommandations.

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

Champs pris en charge

Les champs textuels compatibles sont résumés dans le tableau suivant.

Le boosting/rétrogradation des recommandations accepte des champs supplémentaires qui ne sont pas compatibles avec le filtrage standard des recommandations. Pour obtenir la liste des champs supplémentaires compatibles avec le boosting/rétrogradation pour les recommandations, consultez la section Champs compatibles avec le boosting/rétrogradation.

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 compatibles avec le boosting/rétrogradation

La fonctionnalité Boost/rétrogradation accepte des champs supplémentaires qui ne sont pas compatibles avec le filtrage standard des recommandations, y compris les champs numériques.

En plus des champs répertoriés dans la section Champs acceptés, la fonctionnalité boost/bury pour les recommandations accepte les champs suivants:

Champs textuels

champ	description
"balises"	`Product.tags[]`. Balises personnalisées associées au produit.

Champs numériques

champ	description
"price"	`PriceInfo.price` : prix du produit
"discount"	Remise sur le produit. Ce champ est calculé à l'aide des valeurs des champs de prix et de prix d'origine de `PriceInfo`.
"rating"	`Product.rating`. Nombre total de notes pour le produit.
"ratingCount"	`rating.ratingCount`. Nombre total de notes pour le produit.

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

Vous pouvez activer le filtrage des recommandations à l'aide de la console Search for Retail ou de la ressource d'API Models.

À partir de la console, vous pouvez créer un modèle pour lequel le filtrage des recommandations est activé. Vous pouvez également mettre à jour cette option pour les modèles existants.

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

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

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

Dans la console Search for Retail, sélectionnez l'option Générer automatiquement des tags lors de la création du modèle afin de permettre le filtrage des recommandations pour ce modèle.

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

Par exemple, la combinaison de diversity-level et category attribute filtering basée sur des règles génère 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. (un résultat pour catégorie1, un résultat pour catégorie2, etc.).
- Le filtrage des attributs à l'aide des métadonnées de catégorie (Product.categories = ANY ("category2")) entraîne la suppression des éléments qui ne correspondent pas.
- La sortie finale a moins de trois résultats.
Pour le modèle similar-items, il contient déjà une amélioration supplémentaire de la pertinence de la catégorie avec la category-match-level = relaxed-category-match par défaut. 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.

Ce paramètre ne peut pas être modifié dans la console pour les modèles existants. Pour mettre à jour ce paramètre pour un modèle, utilisez la méthode API models.Patch.

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

Vous pouvez activer le filtrage des recommandations pour un modèle à l'aide de models.Create lorsque vous créez un modèle ou de models.Patch lors de la mise à jour d'un modèle existant.

Pour autoriser le filtrage, définissez le champ filteringOption pour votre modèle. Les valeurs autorisées de ce champ sont les suivantes:

RECOMMENDATIONS_FILTERING_DISABLED (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 dans 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 met à jour 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 les 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 mettre à jour ce paramètre à l'aide de la console Search for Retail ou de la ressource d'API Attributes.

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

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

Vous pouvez définir un attribut comme page Commandes filtrable dans la console Search for Retail.

Accédez à la page Paramètres de la console Search for Retail.

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

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

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

Définir les 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. Les valeurs autorisées de ce champ sont les suivantes:

RECOMMENDATIONS_FILTERING_DISABLED (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 mettez à jour un attribut existant, conservez ses valeurs d'origine pour indexableOption, dynamicFacetableOption et searchableOption telles qu'elles apparaissent à l'étape précédente. Si l'attribut que vous avez choisi n'apparaissait pas lors de l'affichage de 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 pouvez commencer à utiliser l'attribut pour le filtrage une fois le cycle d'entraînement suivant du modèle terminé. En général, cette opération prend 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 en 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 en utilisant l'une ou l'autre des versions de filtrage. Toutefois, il n'est pas possible d'inclure à la fois des expressions de filtrage v1 et v2 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.