Exigences de données - Topsort Documentation

T-Brain apprend à partir des informations de vos produits et de l’activité des acheteurs. Vous pouvez téléverser des données depuis vos systèmes existants ou, si vous êtes client Topsort, utiliser des jeux de données déjà synchronisés depuis Topsort. Pour commencer, fournissez votre catalogue et au moins un mois d’historique d’événements, y compris tous les achats ainsi que les clics et impressions de produits payants.

Types de jeux de données

Un jeu de données est une collection nommée utilisée pour entraîner un modèle. T-Brain prend en charge trois types de jeux de données :

Type de jeu de données	Contenu
Categories	Noms de catégories et leur place dans la hiérarchie du catalogue.
Products	Informations produit, y compris les identifiants, les descriptions, les marques et les associations de catégories.
Events	Activité des acheteurs, y compris les impressions, les clics et les achats.

Vous pouvez nommer les jeux de données pour distinguer leur objet ou leur source, par exemple products-main-store ou events-september.

Téléverser des données

Allez dans Data.
Cliquez sur Add dataset.
Sélectionnez Categories, Products ou Events.
Donnez un nom au jeu de données.
Téléversez vos fichiers Parquet et suivez les instructions.

T-Brain affiche la structure requise pour chaque type de jeu de données et vérifie que vos fichiers s’y conforment. Les tableaux ci-dessous expliquent les colonnes indiquées dans les exigences de téléversement. Les champs marqués Required doivent être renseignés. Les autres fournissent des informations produit, des relations ou le contexte nécessaire à votre cas d’usage.

Colonne	Type	Exigence	Description
`category_id`	String	Required	Identifiant unique de la catégorie. Les produits référencent cette valeur via `category_ids`.
`name`	String	Required	Nom d’affichage de la catégorie.
`path`	String	Optional	Hiérarchie de catégories séparée par des points, la catégorie la plus générale en premier.

Products

Les téléversements de produits sont des instantanés. Chaque téléversement doit contenir l’ensemble complet des produits.

Colonne	Type	Exigence	Description
`product_id`	String	Required	Identifiant unique du produit. Doit correspondre exactement au `product_id` correspondant dans les enregistrements d’événements.
`name`	String	Optional	Nom d’affichage du produit, utilisé pour aider le modèle à comprendre le produit.
`description`	String	Optional	Description du produit. Le HTML est accepté et retiré pendant le traitement.
`image_url`	String	Optional	URL de l’image du produit, utilisée pour générer des embeddings d’image.
`brand_id`	String	Optional	Identifiant de la marque.
`brand_name`	String	Optional	Nom d’affichage de la marque.
`category_ids`	List of strings	Optional	Identifiants de catégorie correspondant aux enregistrements du jeu de données de catégories.
`price`	Decimal	Optional	Prix dans les unités monétaires de votre marketplace. Zéro est un prix valide ; null signifie inconnu.
`active`	Boolean	Optional	Indique si le produit peut être sélectionné par le modèle.
`parent_product_id`	String	Optional	Identifiant du produit parent d’une variante.

Bien que seul product_id soit structurellement obligatoire, incluez des informations descriptives lorsqu’elles sont disponibles afin que le modèle dispose d’informations utiles sur vos produits.

Events

Fournissez au moins un mois d’historique d’événements. Incluez tous les achats, et pas seulement les achats attribués à la publicité, ainsi que les clics et impressions de produits payants. Les événements doivent inclure un identifiant d’acheteur cohérent afin de relier les interactions et les achats. Dans le jeu de données, cet identifiant est stocké dans user_id et doit rester stable d’une session et d’un jour à l’autre. Les téléversements d’événements sont additifs : vous pouvez ajouter l’activité de périodes supplémentaires.

Colonne	Type	Exigence	Description
`event_id`	String	Required	Identifiant unique de la ligne d’événement. Chaque ligne d’achat a son propre identifiant.
`event_type`	String	Required	Type d’activité. Voir les valeurs prises en charge ci-dessous.
`ts`	Datetime	Required	Moment où l’activité s’est produite, et non le moment du téléversement du fichier.
`user_id`	String	Needed to connect shopper activity	Identifiant d’acheteur cohérent d’une session et d’un jour à l’autre.
`product_id`	String	Where applicable	Produit concerné par l’événement. Peut être null pour les événements de page et de request.
`request_id`	String	Where applicable	Identifiant de request ou d’enchère associé à l’événement.
`source`	String	Where applicable	`sponsored` ou `organic`.
`placement`	String	Optional	Endroit de la page où l’interaction s’est produite.
`search_term`	String	Optional	Requête de recherche de l’acheteur, décodée et nettoyée.
`page_type`	String	Optional	`home`, `category`, `search`, `pdp` ou `other`. `pdp` signifie page de détail produit.
`device`	String	Optional	`mobile` ou `desktop`.
`category`	String	Where applicable	Identifiant de catégorie associé à la request ou à la page.
`order_id`	String	For purchase rows	Regroupe les lignes de produit appartenant à la même commande.
`quantity`	Integer	For purchase rows	Nombre d’unités achetées sur cette ligne.
`unit_price`	Decimal	For purchase rows	Prix payé par unité, dans les unités monétaires de votre marketplace.
`product_ids`	List of strings	For request rows	Produits affichés ou considérés dans la request.

Types d’événements pris en charge

Valeur	Signification
`impression`	Un acheteur a vu un emplacement de produit.
`click`	Un acheteur a cliqué sur un produit.
`add_to_cart`	Un acheteur a ajouté un produit à son panier.
`page_view`	Un acheteur a consulté une page.
`purchase`	Un acheteur a acheté un produit.

Gardez des identifiants cohérents

Utilisez des identifiants exacts et cohérents entre les jeux de données :

Le product_id d’un événement doit correspondre au product_id du jeu de données produits.
Les valeurs de category_ids d’un produit doivent correspondre au category_id des enregistrements de catégorie.
Utilisez le même user_id pour le même acheteur dans les interactions et les achats.
Donnez à chaque ligne d’achat un event_id unique, et utilisez order_id pour regrouper les lignes d’une même commande.

Actualiser un jeu de données téléversé

Dans Data, cliquez sur Add Files à côté du jeu de données à mettre à jour. Pour les produits et les catégories, fournissez un instantané complet. Pour les événements, ajoutez les nouveaux enregistrements. Une fois le jeu de données mis à jour, réentraînez tout modèle qui doit apprendre des informations actualisées. Ajouter des fichiers n’actualise pas automatiquement un modèle déjà entraîné.

Utiliser les jeux de données Topsort synchronisés

Si vous êtes client Topsort, trois jeux de données sont déjà disponibles :

Topsort-categories
Topsort-products
Topsort-events

Ces jeux de données se mettent à jour en temps réel. Vous pouvez les sélectionner lors de la création d’une tâche au lieu de téléverser vous-même les mêmes informations. Les mises à jour en temps réel des jeux de données ne réentraînent pas automatiquement les modèles déployés.

Entraîner avec vos jeux de données

Allez dans Tasks, choisissez ce que le modèle doit faire et sélectionnez les jeux de données pertinents. Par exemple, une tâche de classement de produits utilise les produits et les événements. Lancez l’entraînement, suivez la progression dans Training et examinez la qualité du modèle dans Evals avant le déploiement.

Confidentialité et accès aux données

Vos données téléversées et vos modèles fine-tunés sont isolés par détaillant. Les politiques de conservation et de suppression peuvent être configurées selon vos exigences. Parlez à un représentant commercial Topsort pour organiser l’accès. La documentation API est disponible sur demande, y compris l’authentification, les formats de requête et de réponse, la latence et les limites de débit.

​Types de jeux de données

​Téléverser des données

​Categories

​Products

​Events

​Types d’événements pris en charge

​Gardez des identifiants cohérents

​Actualiser un jeu de données téléversé

​Utiliser les jeux de données Topsort synchronisés

​Entraîner avec vos jeux de données

​Confidentialité et accès aux données