Ce document concerne Recommendations AI, Retail Search et la nouvelle console Retail. Pour utiliser Retail Search dans la phase en disponibilité limitée, contactez le service commercial Cloud.

Si vous n'utilisez que Recommendations AI, restez dans la console Recommendations AI et consultez la documentation sur Recommendations AI.

Catalogues et informations sur le catalogue

Cette page présente les bonnes pratiques à suivre pour créer vos informations de catalogue et les insérer.

Aperçu

Les données de catalogue que vous importez dans Retail ont un effet direct sur la qualité du modèle obtenu et, par conséquent, sur la qualité des résultats fournis par l'API Retail. En général, plus les informations du catalogue sont précises et spécifiques, plus la qualité du modèle est bonne.

Votre catalogue doit être à jour. Vous pouvez importer des modifications de catalogue aussi souvent que nécessaire (dans l'idéal, de façon quotidienne pour les catalogues dont le taux de variation est élevé). Vous pouvez importer (modifier) des produits existants, auquel cas seuls les champs modifiés sont mis à jour. L'importation des informations de catalogue est gratuite. Pour plus d'informations, consultez la section Maintenir votre catalogue à jour.

Branches de catalogue

Utilisez des branches de catalogue pour tester les nouvelles données que vous avez importées hors connexion avant de les rendre disponibles sur votre site.

Avec l'API Retail, vous pouvez utiliser jusqu'à trois branches, identifiées par 0, 1 et 2. Votre site en ligne pointe vers default_branch pour ses données de catalogue. Indiquez quelle branche est actuellement votre default_branch (définie par défaut sur la branche 0) en utilisant setDefaultBranch ou l'onglet "Data" (Données) de Cloud Console. Ensuite, comme votre site pointe vers default_branch pour ses données de catalogue, vous

Par exemple, supposons que default_branch est actuellement défini sur l'ID de branche 0. Votre site utilise donc les données de catalogue que vous avez importées vers cette branche. Vous pouvez importer de nouvelles données de catalogue vers la branche 1 et les prévisualiser. Une fois que vous avez vérifié que le catalogue a été importé correctement, vous pouvez passer à la branche 1 en tant que fichier default_branch en direct.

Produits

Le catalogue est une collection d'objets produit.

Informations produit requises

Les champs suivants sont obligatoires : vous devez les renseigner lorsque vous créez des produits dans votre catalogue. Ils doivent également correspondre aux valeurs utilisées dans votre base de données de produits internes et doivent refléter avec précision le produit représenté, car ils sont utilisés pour l'entraînement de vos modèles.

Dans certains cas, d'autres champs sont également requis. Consultez la liste complète de tous les champs de produit sur la page de référence Product.

Cependant, toutes les informations produit que vous fournissez peuvent servir à améliorer la qualité des recommandations et des résultats de recherche. Veillez à renseigner autant de champs que possible.

Champ Remarques
name Nom de ressource unique complet du produit. Obligatoire pour toutes les méthodes produit, à l'exception de import. Lors de l'importation, le nom est généré automatiquement et n'a pas besoin d'être fourni manuellement.
id ID produit utilisé par votre base de données de produits. Le champ d'ID doit être unique dans l'ensemble de votre catalogue. La même valeur est utilisée lorsque vous enregistrez un événement utilisateur. Elle est également renvoyée par les méthodes predict et search.
title Nom du produit dans votre base de données de produits. Chaîne encodée en UTF-8. 1250 caractères maximum.

Attributs du produit

Il est vivement recommandé de fournir des valeurs pour les attributs système prédéfinis de Product tels que la marque, la couleur et la taille. Vous pouvez également inclure des attributs personnalisés que vous définissez avec Product.attributes.

Si vous utilisez Retail Search, les attributs sont inclus avec un produit dans la réponse de recherche si vous les marquez comme récupérables dans Product.retrievableFields. Ils peuvent ensuite être utilisés pour d'autres fonctionnalités Retail Search comme le filtrage et les attributs.

Utiliser les niveaux de produits

Lorsque vous importez votre catalogue pour la première fois, vous devez spécifier si vous fournissez uniquement des articles principaux, ou des articles principaux ainsi que leurs variantes.

  • Les articles principaux sont ceux renvoyés par l'API Retail dans les résultats de prédiction ou de recherche. Il peut s'agir d'articles individuels (au niveau du SKU) ou de groupes d'articles similaires (groupes de SKU). Par défaut, l'API Retail est configurée pour n'importer que les articles principaux.
  • Les articles Variante sont des versions d'un produit principal. Les variantes ne peuvent être que des articles individuels (au niveau du code SKU). Par exemple, si le produit principal est "Chemise à col en V", les variantes peuvent être "Chemise à col en V, coloris marron, taille XL" et "Chemise à col en V, coloris blanc, taille S". Les produits principaux et leurs variantes sont parfois décrits comme des éléments "parents" et "enfants". L'importation de variantes est facultative.

Lors de l'importation du catalogue, définissez vos niveaux de produits à l'aide de la méthode Catalog.patch. Exemple :

curl -X PATCH 
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)"
-H "Content-Type: application/json; charset=utf-8"
--data '{ "productLevelConfig": { "ingestionProductType": "PRODUCT-TYPE", "merchantCenterProductIdField": "PRODUCT-ID-FIELD" } }'
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

Pour déterminer les meilleurs choix concernant le niveau de produit de votre mise en œuvre, vous devez examiner les données de votre catalogue et la logique de votre site Web. Quels ID de produit sont disponibles lorsque vous capturez des données d'événement utilisateur ? Quels ID de produit seraient les plus efficaces à renvoyer avec des prédictions ou des résultats de recherche ? En quoi ces ID sont associés ?

Suivez les étapes appropriées, selon que vous importez ou non depuis Merchant Center :

Déterminer les niveaux de vos produits pour l'importation à partir de Merchant Center

Lorsque vous importez des données de catalogue à partir de Merchant Center, l'API Retail utilise ingestionProductType pour déterminer s'il convient de les importer en tant que produits principaux ou variantes, et le champ merchantCenterProductIdField pour indiquer s'il faut utiliser la fonction offer_id ou item_group_id de Merchant Center en tant qu'ID de produit.

Examinez les données de votre catalogue et la logique de votre site Web pour répondre aux questions suivantes :

  • Ai-je des produits principaux et des variantes dans mon catalogue ?
  • Si oui, quel niveau d'article sera disponible lorsque je capture des données d'événements utilisateur ?
  • Quel type d'article dois-je renvoyer avec mes résultats ?

Déterminez si :

  1. Votre catalogue ne contient qu'un seul niveau d'article. Cela peut signifier que :

    • Tous vos produits et événements résident au niveau du code SKU, et vous souhaitez obtenir des prédictions au niveau du code SKU.
    • Tous vos produits et événements résident au niveau du groupe, et vous souhaitez obtenir des prédictions au niveau du groupe.

    Si tel est le cas, importez uniquement avec les articles principaux. Il s'agit du paramètre d'importation par défaut.

  2. Vous souhaitez obtenir des prédictions au niveau du groupe (principal), mais vos produits Merchant Center résident au niveau du code SKU. Dans ce cas, votre décision d'importation dépend de la manière dont vos événements sont capturés.

    1. Vos événements sont capturés au niveau du groupe. Si tel est le cas, utilisez les paramètres suivants pour l'importation :

      Lorsque plusieurs produits Merchant Center ont le même item_group_id Merchant Center, Retail n'importe qu'un seul de ces produits en tant que produit principal, et utilise item_group_id comme ID produit. Dans ce cas, les produits qui n'ont pas de item_group_id ne peuvent pas être importés. Les événements enregistrés doivent faire référence à l'ID de produit principal (au niveau du groupe).

    2. Vos événements sont capturés au niveau du code SKU. Si tel est le cas, utilisez les paramètres suivants pour l'importation :

      Retail importe vos produits en tant que variantes et utilise le offer_id de Merchant Center comme ID de produit. Les événements enregistrés doivent faire référence à l'ID de produit de variante (au niveau du SKU).

Déterminer les niveaux de vos produits pour l'importation sans Merchant Center

Tous vos produits doivent avoir une valeur pour primaryProductId, ou aucun d'entre eux ne peut en avoir. Vous ne pouvez pas importer de données de catalogue avec primaryProductId défini pour certains articles mais pas pour d'autres.

  1. Si votre catalogue ne comporte qu'un seul niveau d'article, cela peut signifier que :

    • Tous vos produits et événements résident au niveau du SKU, et vous souhaitez obtenir des résultats au niveau du SKU.
    • Tous vos produits et événements résident au niveau du groupe, et vous souhaitez obtenir des résultats au niveau du groupe.

    Si tel est le cas, importez uniquement avec les articles principaux. Il s'agit du paramètre recommandé par défaut.

  2. Si vos événements et produits résident au niveau du SKU, vous pouvez obtenir des résultats au niveau du groupe. Définissez ingestionProductType sur variant lors de l'importation.

La prédiction et la recherche au niveau des SKU ne sont pas disponibles si vous ne disposez que d'événements et de produits au niveau du groupe.

Si vous envisagez d'importer des données de catalogue à partir de Merchant Center dans le futur, examinez vos données comme décrit dans la section concernant les importations Merchant Center afin de vous assurer de faire le bon choix. Vous ne pouvez modifier cette configuration qu'en supprimant le catalogue et en l'important à nouveau (consultez la section Modifier la configuration au niveau du produit).

Métriques de qualité des données de catalogue

Pour vous aider à assurer le suivi de la qualité de recherche de vos données de catalogue, Retail évalue vos données produit par rapport à un ensemble de règles de qualité. Vous pouvez afficher le pourcentage des produits qui répond à chaque règle de qualité sur la page Données Retail.

Le tableau suivant décrit les métriques de qualité utilisées par Retail pour vous aider à évaluer vos données produit :

Métrique de qualité de catalogue Règle de qualité Remarques
L'URI est présent et accessible. Le produit possède un Product.uri valide. L'URI doit être accessible et correspondre à votre domaine. Cloud Retail Search utilise des signaux Web explorés via cet URI pour améliorer la qualité de recherche.
Respecte la continuité temporelle. Product.availableTime est antérieur à l'heure actuelle et Product.expireTime postérieur à l'heure actuelle. Seuls les produits respectant la continuité temporelle sont disponibles pour la recherche.
L'attribut d'inclusion dans l'index de recherche est présent. Le produit contient au moins un attribute inclus dans l'index de recherche. Les attributs personnalisés marqués comme inclus dans l'index de recherche peuvent faire l'objet d'une recherche par des requêtes de texte.
La description est présente Le produit comporte un champ Product.description non vide. Une description complète permet d'améliorer la qualité de recherche.
Le nom de produit contient au moins deux mots. Product.title comprend au moins deux mots. Un nom de produit complet contribue à améliorer la qualité de recherche.
Comporte une variante avec image. Le produit variant a au moins un élément Product.image. Vous pouvez ignorer cette métrique si tous vos produits sont au niveau primary. Cette métrique est fournie à titre informatif et n'a aucune incidence sur la qualité de recherche.
Comporte une variante avec des informations de prix. Le produit variant comporte un élément Product.priceInfo défini. Vous pouvez ignorer cette métrique si tous vos produits sont au niveau primary. Cette métrique est fournie à titre informatif et n'a aucune incidence sur la qualité de recherche.

Schéma Retail

Lorsque vous importez un catalogue à partir de BigQuery, utilisez le schéma Retail ci-dessous pour créer une table BigQuery au format adapté et y insérer vos données de catalogue. Ensuite, importez le catalogue.