Travail final
- Après les études de cas
- environ 3 h
Où nous en sommes
Chaque module a ajouté une partie d'un système de recommandation et l'a mesurée : découpage, dispositif de test, méthodes, modèle de classement, règles et service. Dans ce travail, vous les utilisez toutes pour la nouvelle catégorie et le courriel hebdomadaire de Larkfield.
Ce que vous saurez faire
Appliquez chaque module du cours à une nouvelle situation. Livrez un dossier de recommandation qu’Omar, Hana, Rafael et Amira pourront utiliser. La nouvelle catégorie n’a aucun historique, beaucoup de clients sont nouveaux et personne n’a encore reçu le courriel. Mesurez donc chaque choix à nouveau, sur ces données, au lieu de le reprendre des leçons.
Avant de commencerCe qu’il faut savoir et avoir sous la main
- Vous avez terminé les modules 1 à 9. Chaque partie ci-dessous nomme les leçons qu’elle utilise.
- Vous n’avez pas besoin des études de cas du module 10 pour ce travail. Le certificat en exige au moins une : Recommander des produits pour un détaillant en ligne, L’article suivant à partir des sessions de navigation ou Des livres pour les lecteurs. Elles constituent un bon exercice pour ce travail.
- Votre dossier
larkfield-recsfonctionne à la fin du module 9 :python -m pytest -qaffiche33 passed, 1 warning, comme dans Vie privée et suggestions sensibles. Les données du cours sont danslarkfield-recs/data. Le dossiernextia-learning-labsse trouve à côté delarkfield-recs, comme dans Découvrir le journal du magasin. - Environ 3 à 4 heures. Vous passerez surtout ce temps à lire les résultats et à écrire vos décisions. L’étape la plus lente est le traitement en lot nocturne avec le modèle de classement en deux étapes. Sur le portable très sollicité de l’équipe du cours, il a pris environ 4 minutes pour les clients fidèles seulement. Il a pris environ 21 minutes quand le modèle de classement servait tous les clients.
- Testé sur macOS avec Python 3.12.13 et les versions de paquets fixées par le projet. Les commandes Windows sont fournies, mais elles n’ont pas été exécutées.
La situation : Home office et un courriel hebdomadaire
Section intitulée « La situation : Home office et un courriel hebdomadaire »Larkfield fait deux nouvelles choses en même temps :
- Une nouvelle catégorie. Le 20 juillet 2026, Larkfield lance Home office : 150 produits dans 6 sous-catégories. Le premier jour, ils n’ont aucune consultation et aucune commande. C’est le démarrage à froid de Démarrage à froid pour les nouveaux produits et les nouveaux clients, pour une catégorie entière.
- Un courriel hebdomadaire. Chaque semaine, chaque client reçoit un courriel contenant 10 produits. Personne ne l’a encore reçu, donc il n’existe aucun journal des courriels.
Beaucoup de clients sont nouveaux aussi. 5 000 personnes ont ouvert un compte du 6 juillet au 16 août. La plupart ont fait une seule visite, ou aucune.
L’équipe a des questions, comme dans le cours :
- Omar, le gestionnaire de produit, demande ce que le courriel rapporte. Sa mesure principale est le revenu supplémentaire par courriel : l’argent provenant des produits suggérés que le client n’aurait pas achetés autrement. Sa limite du module 6 tient toujours : un changement de démarrage à froid peut réduire le recall@10 des clients connus d’au plus 2 % de sa valeur.
- Hana, la responsable du marchandisage, veut que la nouvelle catégorie soit visible dès la première semaine.
- Rafael, le gestionnaire des courriels et des relations clients, surveille les désabonnements. Il rappelle à tous que certains clients partagent une adresse courriel avec leur famille. Certains clients ont aussi refusé les suggestions personnelles.
- Amira, la développeuse, est responsable du service. Elle a besoin d’une solution de repli, d’un traitement en lot nocturne et d’une demande de suppression testée.
- Tomás, l’ingénieur en IA, a déjà une réponse : « Le système en deux étapes a gagné dans le tableau du cours. Livrons-le pour tout. »
Priya vous demande de répondre à tous avec des preuves.
Soyez honnête au sujet des données. Le journal du magasin, les nouveaux produits et les nouveaux clients sont synthétiques. Le code du cours les a créés avec un modèle de comportement des clients. Un modèle de langage a écrit les titres à partir de nos attributs. Les données contiennent des problèmes d’exercice que nous avons créés exprès. L’équipe du cours les connaît, mais pas vous. Le courriel n’a jamais été envoyé. Tout chiffre à son sujet représente donc un plan ou une simulation, jamais une mesure auprès de personnes. Présentez vos chiffres « sur le journal synthétique de Larkfield », avec leurs intervalles.
Les données
Section intitulée « Les données »Les données se trouvent dans le dépôt des laboratoires, dans C37/final/. Les données du cours, dans C37/data/, restent inchangées.
| Fichier | Lignes | Ce que représente une ligne |
|---|---|---|
products_new.csv |
150 | Un produit Home office, avec les mêmes 17 colonnes que le fichier products.csv du cours. Tous ont été ajoutés le 20 juillet 2026. |
customers_new.csv |
5 000 | Un nouveau client, avec les mêmes 5 colonnes que customers.csv. first_seen est vide quand le client n’a encore aucun événement dans les fichiers. |
events_final.csv.gz |
37 140 | Un événement (consultation, ajout au panier ou commande) du 20 juillet au 2 août 2026, d’un ancien ou nouveau client. |
embeddings/products_new.npy |
150 × 384 | Les vecteurs des nouveaux produits, créés avec le modèle du cours, dans l’ordre du fichier. |
make_data.py |
Crée un dossier de données que la commande recs peut lire. |
|
export_lists.py |
Écrit les listes que vous remettrez, à partir de recs batch. |
Le dossier contient aussi embeddings/model.json, README.md, dataset-card.md et SHA256SUMS. Il occupe environ 0,6 Mo.
Deux périodes ne sont pas dans les fichiers. L’image montre où elles se trouvent :
Description textuelle du diagramme
Cinq encadrés de gauche à droite. Le journal du cours, du 1er février 2025 au 5 juillet 2026, se trouve dans votre dossier de données. Ses deux dernières semaines, du 22 juin au 5 juillet, forment la période de validation par défaut. Ensuite, un encadré gris à bordure pointillée : du 6 au 19 juillet, période manquante que l’équipe du cours conserve. Puis du 20 au 26 juillet : la première semaine de Home office. Puis du 27 juillet au 2 août : la semaine de test par défaut, que vous utilisez une seule fois. Enfin, un encadré rouge : du 3 au 16 août, les semaines notées, absentes des fichiers.
- La période manquante, du 6 au 19 juillet. Vos données ne contiennent aucun événement pour cette période. Juste après, « les 28 derniers jours » de la méthode des tendances ne contiennent que deux semaines d’événements. Les deux semaines d’entraînement du modèle de classement contiennent une semaine d’événements, ou aucune. Gardez cela en tête quand vous choisissez vos périodes.
- Les semaines notées, du 3 au 16 août. L’équipe du cours évalue les listes que vous remettez sur les commandes de ces deux semaines. Vous ne pouvez pas faire de réglages sur elles, et vous n’en avez pas besoin.
Vérifiez les fichiers, créez le dossier de données et indiquez-le au projet. Exécutez ceci dans votre dossier larkfield-recs, avec .venv actif :
git -C ../nextia-learning-labs pullF=../nextia-learning-labs/C37/final(cd "$F" && shasum -a 256 -c SHA256SUMS | grep -vc ': OK$')python "$F/make_data.py"export LARKFIELD_DATA=final-data LARKFIELD_OUTPUTS=outputs-finalrecs checkrecs infogit -C ..\nextia-learning-labs pull$F = "..\nextia-learning-labs\C37\final"python "$F\make_data.py"$env:LARKFIELD_DATA = "final-data"; $env:LARKFIELD_OUTPUTS = "outputs-final"recs checkrecs infomake_data.py vérifie lui-même chaque fichier avec SHA256SUMS et s’arrête si l’un d’eux est incorrect.
Le nombre que shasum affiche est le nombre de fichiers incorrects. Il doit être 0. Vous voyez ensuite :
Wrote final-data/: 3,144 products (150 new in Home office), 45,000 customers (5,000 new, 2,088 of them with events), 842,456 events to 2026-08-02Periods: launch 2026-07-20 to 2026-08-02, validation 2026-06-22 to 2026-07-05, test 2026-07-27 to 2026-08-02No events from 2026-07-06 to 2026-07-19; the files stop on 2026-08-02.Data: 8 files, all right (final-data)popular on the validation period (quick): recall@10 0.106 (expected 0.106)Setup check passed.Products: 3,144 in 21 categories and 107 subcategories (synthetic)Customers: 45,000; 24,902 ordered at least once, 54% of them only onceEvents: 842,456 (598,678 views, 156,615 basket adds, 87,163 order lines in 60,035 orders), 2025-02-01 to 2026-08-02Periods: validation 2026-06-22 to 2026-07-05, test 2026-07-27 to 2026-08-02Customer-product pairs with any event: 510,773 of 141,480,000 (0.36% filled)Ce qui s’est passé :
make_data.pya écrit un nouveau dossier,final-data/. Votre dossierdata/n’a pas changé. Le nouveau dossier contient le journal du cours, les nouveaux produits, les nouveaux clients et les nouveaux événements, avec de nouvelles sommes de contrôle.- Il a défini trois périodes dans
final-data/splits.json, avec les noms que les commandesrecsconnaissent.launchcouvre les deux premières semaines de Home office, avec un entraînement sur les événements d’avant le lancement. C’est la même réexécution que pour la gamme d’été du module 6.validationest l’ancienne période de test du cours. Vous faites donc les réglages sur deux semaines complètes, sans période manquante avant elles.testest la dernière semaine disponible : Home office a une semaine d’historique avant celle-ci. LARKFIELD_DATAindique le dossier à chaque commanderecs.LARKFIELD_OUTPUTSsépare les nouveaux modèles et exécutions de ceux du cours. Fermez le terminal, ou retirez ces deux variables, pour revenir aux données du cours.
Votre propre découpage. Les périodes par défaut sont un choix, pas une règle. La période de validation ne contient aucun produit Home office. Vous pouvez plutôt faire les réglages sur la première semaine de Home office :
python "$F/make_data.py" --validation 2026-07-20 2026-07-26 --test 2026-07-27 2026-08-02Lisez d’abord Le modèle de classement n’a rien pour apprendre : juste après la période manquante, certaines méthodes n’apprennent presque rien.
Une période doit se terminer au plus tard le 2 août et ne peut pas chevaucher la période manquante. recs check connaît la valeur attendue seulement pour les périodes par défaut. Avec les semaines ci-dessus, il vérifie les fichiers, puis affiche :
popular on the validation period (quick): recall@10 0.088 (no expected value for this validation period)Data check passed. The result check needs the default periods: use `recs info` to see yours.Écrivez votre découpage et votre raison dans votre rapport.
Créez un dossier recs-pack/ dans votre dossier larkfield-recs. Placez-y tous les fichiers du travail. Quoi remettre présente la liste des fichiers.
Les cinq parties
Section intitulée « Les cinq parties »Le dossier suit les règles de réussite du cours : une partie pour chaque élément obligatoire.
Description textuelle du diagramme
Un encadré en haut : le dossier recs-pack, avec REPORT.md et les commandes qui produisent chaque chiffre. En dessous, cinq encadrés. 1 Énoncés du problème : PROBLEM.md, pour la page produit et le courriel, avec la mesure d’affaires, les garde-fous et le coût d’une mauvaise suggestion. 2 Comparaison : comparison.csv, avec popular, trending et au moins quatre familles de méthodes, par segment. 3 Système choisi : rules.csv avec l’effet de chaque règle, et OMAR.md, qui explique ce choix de conception et son coût. 4 Démarrage à froid : COLD-START.md, avec des preuves que les nouveaux produits sont affichés et que les nouveaux clients sont servis. 5 Service et test du courriel : email.csv et similar.csv, service.md et EMAIL-TEST.md, un plan décidé à l’avance.
Partie 1 : un énoncé du problème pour chaque emplacement
Section intitulée « Partie 1 : un énoncé du problème pour chaque emplacement »Cette partie utilise Un bon vendeur en magasin et Ce que signifie la réussite.
Écrivez recs-pack/PROBLEM.md, une demi-page pour chaque emplacement : la page produit d’un produit Home office et le courriel hebdomadaire. Pour chaque emplacement, écrivez :
- Qui le voit, et quand. Par exemple : les personnes qui voient la page produit regardent déjà un produit. Le courriel rejoint chaque client, même ceux qui n’ont pas visité le magasin depuis des mois.
- La mesure d’affaires. Pour le courriel, le revenu supplémentaire par courriel d’Omar. Pour la page produit, choisissez-en une et expliquez pourquoi.
- Le substitut hors ligne. Vous pouvez le calculer à partir du journal, par exemple le recall@10 sur les commandes d’une semaine ultérieure. Expliquez pourquoi ce n’est qu’un substitut.
- Les garde-fous. Au moins deux par emplacement. Par exemple : retours, désabonnements, nouveaux produits affichés, produits déjà achetés par un client, produits sensibles dans une boîte de réception partagée et les 100 ms d’Amira.
- Le coût d’une mauvaise suggestion, en dollars, avec les hypothèses du cours dans
final-data/costs.json. Un retour coûte 12 $ à traiter. Un abonné vaut 18 $ par année. Calculez un exemple, comme dans Le coût de deux erreurs. Dites « selon ces hypothèses ».
Partie 2 : une comparaison par découpage temporel
Section intitulée « Partie 2 : une comparaison par découpage temporel »Cette partie utilise Découper selon le temps, Les références de base à battre, Mesures de classement, Au-delà de l’exactitude, Évaluer par segment et les leçons des modules 4 à 7. L’étude de cas Recommander des produits pour un détaillant en ligne fait le même type de comparaison sur de vraies transactions.
-
Fixez d’abord votre découpage, et ne le changez pas après avoir vu les résultats. Écrivez dans
REPORT.mdquelle semaine sert aux réglages et quelle semaine sert au rapport. Expliquez pourquoi les données d’entraînement ne contiennent aucun événement d’un jour ultérieur. -
Les références de base. Exécutez
popularettrending. Comparez tous les autres systèmes avec elles.Fenêtre de terminal recs evaluate popular --period validation --by segmentrecs evaluate trending --period validation --by segment -
Au moins quatre familles de méthodes. Une famille représente une idée : voisins (
cooc,lift,item-cf,user-user), factorisation (als,bpr), contenu (content), hybrides (hybrid-blend,hybrid-switch,als+new) et deux étapes (two-stage). Deux réglages d’une même famille comptent comme une seule famille.Fenêtre de terminal recs evaluate item-cf --period validation --by segmentrecs evaluate als --period validation --by segment --set factors=32 --set regularization=0.1 --set alpha=1recs evaluate content --period validation --by segmentrecs evaluate two-stage --period validation --by segmentLe modèle de classement apprend sur les 14 jours juste avant la période. Avec les périodes par défaut, ces jours contiennent des commandes. Avant votre semaine de test, ils contiennent une semaine d’événements et une semaine de la période manquante.
-
Faites les réglages sur la validation seulement. Si vous réglez une méthode, comme dans Régler sans vous tromper vous-même, choisissez ses paramètres sur la semaine de validation. Exécutez ensuite chaque système présenté une seule fois sur la semaine de test, sans changement.
-
Présentez les colonnes du cours pour chaque système dans
recs-pack/comparison.csv: recall@10 avec son intervalle à 95 %, NDCG@10, MAP@10, couverture, nouveauté, diversité, proportion de nouveaux produits dans les listes, recall@10 par segment (nouveaux, occasionnels, fidèles) avec la taille de chaque segment, et temps d’ajustement. La sortie derecs evaluateles contient toutes, et les exécutions sont enregistrées dansoutputs-final/runs/. -
Comparez sur les mêmes clients. Utilisez
recs comparepour chaque différence que vous affirmez, comme dans Comparer sur les mêmes clients :Fenêtre de terminal recs compare trending two-stage --period test --by segment -
Regardez les produits autant que les clients. Comptez combien de fois les produits Home office apparaissent dans les listes de chaque système. La ligne
new products in the lists(nouveaux produits dans les listes) derecs evaluatedonne ce nombre. Un système qui apprend seulement de l’historique n’en affiche presque aucun la première semaine.
Partie 3 : démarrage à froid pour la nouvelle catégorie et les nouveaux clients
Section intitulée « Partie 3 : démarrage à froid pour la nouvelle catégorie et les nouveaux clients »Cette partie utilise Recommandations par le contenu, Démarrage à froid pour les nouveaux produits et les nouveaux clients, Hybrides et Les clients ont aussi acheté.
-
Réexécutez le lancement. La période
launchentraîne sur les événements d’avant le 20 juillet. Home office n’a donc aucun historique. Mesurez combien de nouveaux produits chaque système affiche :Fenêtre de terminal recs evaluate als --period launch --by segmentrecs evaluate content --period launch --by segmentrecs evaluate als+new --period launch --by segment --set slots=1Présentez
new products in the listsetrecall@10 on them(recall@10 sur ces produits). Vérifiez ensuite la limite d’Omar : le recall@10 des clients connus peut baisser d’au plus 2 % de sa valeur. Utilisezrecs comparesur la période de lancement. -
Les nouveaux clients. Déterminez comment votre système sert un client sans commande et un client sans aucun événement. Le segment
new(nouveaux) derecs evaluateregroupe les clients sans commande avant la période. Un client sans événement reçoit la solution de repli du service. Dites quelle est cette solution et si elle lui convient. L’article suivant à partir des sessions de navigation montre jusqu’où une seule visite peut mener quand un visiteur n’a aucun historique. -
La page produit d’un nouveau produit. Un produit Home office a deux semaines d’historique au début des semaines notées. Regardez ses voisins avec chaque méthode :
Fenêtre de terminal recs similar P20001 --method item-cfrecs similar P20001 --method liftrecs similar P20001 --method contentrecs similarentraîne sur les événements d’avant votre semaine de test. Déterminez quels voisins sont des solutions de remplacement (un autre produit du même genre) et lesquels sont des compléments (un produit que les gens achètent ensuite). Le module 4 a montré que les deux apparaissent, pour des clients différents. Décidez ce que la page doit afficher et mesurez ce que vous pouvez. -
Écrivez
recs-pack/COLD-START.md: le plan pour la première semaine, le plan pour les semaines suivantes et les preuves. « Les nouveaux produits sont affichés » exige des chiffres. Donnez la proportion de listes (ou de places dans les listes) contenant un produit Home office. Donnez aussi le nombre de produits Home office affichés au moins une fois.
Partie 4 : le système choisi, ses règles et son service
Section intitulée « Partie 4 : le système choisi, ses règles et son service »Cette partie utilise Pourquoi deux étapes, Un modèle de classement appris, Règles d’affaires et reclassement, En lot ou en temps réel, Surveiller et réentraîner et Vie privée et suggestions sensibles.
-
Choisissez un système pour le courriel à partir de votre semaine de validation : une seule méthode, un hybride ou deux étapes. Votre conception peut être différente des méthodes du projet. Ajoutez-la alors comme fichier dans
larkfield_recs/methods/, comme les méthodes du cours.recs evaluateetrecs batchpourront ensuite l’utiliser. -
Mesurez l’effet de chaque règle sur votre conception, comme dans Le coût de chaque règle :
Fenêtre de terminal recs rules two-stage --period validationÉcrivez une ligne par règle dans
recs-pack/rules.csv: le rappel à 10 (recall@10) avant et après, et la proportion de listes modifiées. Dites ensuite quelles règles vous gardez, et pourquoi. Une règle peut être justifiée même si elle réduit le rappel. -
Écrivez
recs-pack/OMAR.md, une page sans code. Dites ce que votre conception améliore, pour quels segments, et quel segment obtient de moins bons résultats, avec votre commentaire. Répondez à Tomás : le système à deux étapes est-il le bon choix ici, pour chaque emplacement? -
Mesurez le coût du service. Construisez le lot pour chaque client, mesurez sa durée et démarrez le service :
Fenêtre de terminal recs batch two-stagerecs bench --requests 200Donnez la durée du traitement en lot et les p50 et p95 d’une consultation. (La moitié des consultations sont plus rapides que le p50, et 95 % sont plus rapides que le p95.) Donnez le coût du traitement en lot nocturne au prix du serveur du cours : 0,17 $ US l’heure pour 4 vCPU. Cette hypothèse se trouve dans
costs.json. Vérifiez le budget de 100 ms d’Amira. -
Exportez les listes à remettre :
Fenêtre de terminal python "$F/export_lists.py" --out recs-packWrote recs-pack/email.csv: 45,000 customers, 40,786 personal lists and 4,214 fallback lists (two-stage, trained on the events before 2026-08-03)Wrote recs-pack/similar.csv: 3,144 product pages (batch)email.csvcontient 10 produits pour chaque client : la liste du lot avec les règles de votrerules.toml. Elle ne contient aucun produit sensible pour une boîte de réception familiale partagée. Un client sans liste dans le lot, un client qui a refusé la personnalisation ou un client effacé reçoit la solution de repli.similar.csvcontient 10 produits pour chaque page produit.--similar lift(oucooc,item-cf,content) calcule les pages avec une autre méthode. Si votre page produit repose sur votre propre conception, écrivez vous-mêmesimilar.csv, avec les trois mêmes colonnes. -
Testez la solution de repli et une demande de suppression dans un dossier de sorties distinct, pour ne pas modifier votre lot. Choisissez un client qui se trouve dans votre lot :
Fenêtre de terminal LARKFIELD_OUTPUTS=outputs-forget recs forget C100123Fenêtre de terminal $env:LARKFIELD_OUTPUTS = "outputs-forget"; recs forget C100123$env:LARKFIELD_OUTPUTS = "outputs-final"Démarrez ensuite le service sur ce dossier et demandez la liste du client, comme dans Appliquer une demande de suppression. Demandez aussi la liste d’un client sans événement, puis une liste de courriel pour une boîte de réception familiale partagée. Arrêtez le service avec Ctrl+C. Collez les réponses dans
recs-pack/service.md, et dites ce que chacune montre.
Partie 5 : un plan de test pour le courriel hebdomadaire
Section intitulée « Partie 5 : un plan de test pour le courriel hebdomadaire »Cette partie utilise Les gains hors ligne ne sont pas des gains en ligne, Tests en ligne et garde-fous et Boucles de rétroaction et biais de popularité.
Votre test hors ligne indique quelles listes retrouvent davantage de commandes de la semaine suivante. Il ne dit pas ce que le courriel rapporte. Écrivez le plan du test en ligne dans recs-pack/EMAIL-TEST.md, avant le début de tout test :
- La question et les deux versions. Par exemple : vos listes de courriel comparées à un courriel avec la liste des tendances. Les clients sont répartis au hasard.
- La mesure principale qui détermine la décision, par exemple le revenu supplémentaire par courriel.
- Les garde-fous, au moins deux : par exemple les désabonnements, les retours, les produits nouveaux montrés et les boîtes partagées avec un produit sensible. La proportion de ces boîtes doit être de 0.
- La taille, décidée à l’avance. Utilisez le test A/B simulé du cours pour déterminer la taille :
recs online, exécuté avec les données du cours (sans les deux variables d’environnement). Utilisez ensuite la règle approximative de À vous : décider quelle liste mettre en production. Un intervalle rétrécit selon la racine carrée du nombre de clients. Convertissez la taille en semaines de courriels. - La règle d’arrêt. Examinez les résultats une seule fois, à la taille prévue. Arrêtez plus tôt seulement si un garde-fou est dépassé, par exemple si les désabonnements sont nettement plus élevés. N’arrêtez pas parce que votre version « semble bonne » après quelques jours.
- La règle de décision et le retour en arrière : ce que vous faites pour chaque résultat. Précisez aussi comment le courriel revient aux tendances en une seule étape.
Ce cours n’enseigne pas en profondeur la conception de tests; un cours prévu sur les expériences couvrira ce sujet.
Quoi remettre
Section intitulée « Quoi remettre »Le dossier recs-pack/ dans votre dossier larkfield-recs :
recs-pack/ PROBLEM.md Part 1: the two surfaces, measures, guardrails, cost of a bad suggestion comparison.csv Part 2: one row per design and period, the course's columns, by segment COLD-START.md Part 3: new products and new customers, with the evidence rules.csv Part 4: one row per rule, recall before and after, lists changed OMAR.md Part 4: one page for Omar, no code email.csv Part 4: the email lists, from export_lists.py similar.csv Part 4: the product pages lists.json Part 4: what made the lists (written by export_lists.py) service.md Part 4: the fallback, the deletion request, the shared inbox, the timings EMAIL-TEST.md Part 5: the online test plan methods/ any method file that you added, and any other script REPORT.md Parts 1 to 5, with the commands that make every number requirements.txt exact versions (pip freeze)REPORT.md contient ces sections :
# Recommendation pack: Home office and the weekly email
## Data checks (files, checksums, the gap, what you see in the new category)## Split (your periods, and why there is no leak)## Problem statements (Part 1: a summary of PROBLEM.md)## Comparison (Part 2: the table, the segments, the differences with intervals)## Cold start (Part 3: the launch replay, new customers, the product page)## The choice (Part 4: rules, cost, the segment that got worse, the test-week run)## Service (Part 4: fallback, deletion, latency)## Email test plan (Part 5: a summary of EMAIL-TEST.md)## Limits (what your offline test cannot see)## How to reproduce (commands, versions, run times, a fresh environment)Vérifiez votre travail
Section intitulée « Vérifiez votre travail »Un réviseur marque chaque élément démontré, partiellement démontré ou pas encore démontré, avec une raison concrète. Sans réviseur, utilisez le tableau pour évaluer votre propre dossier, ou demandez à un collègue. Le cours est terminé seulement quand les cinq éléments sont démontrés. Vous pouvez améliorer un élément et le remettre à nouveau.
| Élément requis | Démontré quand | Partiellement démontré, par exemple | Pas encore démontré, par exemple |
|---|---|---|---|
| 1. Énoncés des problèmes (module 1) | Pour les deux emplacements : qui les voit, la mesure d’affaires, son substitut hors ligne et au moins deux garde-fous. Le coût d’une mauvaise suggestion est calculé en dollars, avec les hypothèses précisées. | Un seul emplacement, ou un coût sans hypothèse. | « Maximiser les clics » comme mesure d’affaires, sans garde-fou. |
| 2. Comparaison (modules 2 à 7) | Un découpage temporel sans événement ultérieur dans l’entraînement, écrit avant les résultats. popular, trending et au moins quatre familles sur les mêmes clients. Le recall@10 avec intervalles, le NDCG, la couverture et la nouveauté, par segment avec les tailles, et des nouveaux produits dans les listes. Les différences affirmées sont établies avec recs compare. |
Aucun intervalle, ou aucun segment. Ou des paramètres réglés sur la semaine de test, puis des résultats présentés sur cette même semaine. | Un découpage aléatoire. Ou aucune référence de base de popularité. Ou moins de quatre familles. |
| 3. Système choisi (module 7) | Une conception choisie sur la validation, exécutée une seule fois sur la semaine de test. L’effet de chaque règle est mesuré, et chaque règle gardée est expliquée. Le segment qui obtient de moins bons résultats est nommé, avec un commentaire. | Des règles appliquées, mais pas mesurées une par une. | Le choix repose uniquement sur la moyenne, alors qu’un segment obtient de moins bons résultats sans commentaire. |
| 4. Démarrage à froid (module 6) | La réexécution du lancement avec la proportion de nouveaux produits montrés et la vérification de la limite de 2 % d’Omar. Un plan pour les nouveaux clients, avec ce que montre la solution de repli. Une page produit pour un nouveau produit, avec ce qu’elle montre et pourquoi. | Des nouveaux produits montrés, mais le coût pour les clients connus n’est pas mesuré. | Aucune preuve que des nouveaux produits sont montrés. |
| 5. Service et test du courriel (modules 8 et 9) | Le lot est construit et chronométré, le service répond, la solution de repli est montrée. Une demande de suppression est testée sur les listes, et une boîte partagée ne contient aucun produit sensible. Le plan de test du courriel contient une mesure principale, au moins deux garde-fous, une taille décidée à l’avance avec sa source, une règle d’arrêt et un retour en arrière. | Aucun test de suppression, ou un plan sans taille. | « Envoyer et voir ce qui arrive. » Ou aucune règle d’arrêt. |
Non accepté, peu importe ce que montre le reste (l’élément est « pas encore démontré ») :
- Un découpage avec fuite de données : un découpage aléatoire, ou des données d’entraînement contenant des événements de la période évaluée. (Élément 2.)
- La semaine de test utilisée pour le réglage : paramètres, poids ou règles modifiés après l’exécution sur la semaine de test. Ou des exécutions répétées sur cette semaine jusqu’à obtenir de bons résultats. (Éléments 2 et 3.)
- Aucune référence de base de popularité dans la comparaison. (Élément 2.)
- Une conception choisie uniquement sur la moyenne. Un segment enseigné dans le cours obtient de moins bons résultats, et le dossier n’en dit rien. Cela comprend les clients nouveaux, occasionnels ou fidèles, ou les nouveaux produits. (Élément 3.)
- Des listes qui enfreignent les règles du magasin : un produit sensible dans une boîte de réception familiale partagée. Ou une liste personnalisée pour un client qui a refusé la personnalisation. (Élément 5.)
À quoi ressemble un bon dossier
Section intitulée « À quoi ressemble un bon dossier »Un bon dossier est honnête avant d’être impressionnant. Il contient trois choses :
- Des chiffres avec leurs tailles. Chaque rappel a son intervalle. Le dossier indique aussi combien de clients il représente, et de quelle période il provient.
- Une référence de base simple dans chaque comparaison. Pour le courriel, la référence de base est la liste des tendances. Pour la page produit, ce sont les voisins du cours. Si votre conception ne bat pas la référence de base, le dossier le dit.
- Une décision avec son coût. Par exemple : « Sur la semaine de test, cette conception retrouve davantage de commandes de la semaine suivante pour les clients fidèles. Elle montre la nouvelle catégorie à cette proportion de clients. Elle coûte ce montant par nuit. Elle est moins bonne pour les clients occasionnels, et nous l’acceptons parce que… »
Les résultats de l’équipe du cours
Section intitulée « Les résultats de l’équipe du cours »L’équipe du cours a réalisé le travail une fois, uniquement à partir des fichiers publics, avec le code du cours. Elle a ensuite évalué ces listes sur les semaines notées et les a envoyées dans le courriel simulé. Les résultats ci-dessous proviennent de cette exécution. Votre conception et votre découpage peuvent être différents. Comparez la méthode et l’ampleur de chaque résultat, pas le chiffre exact.
Les études de cas du module 10 ont obtenu plusieurs résultats semblables sur des données réelles. Lisez-les en parallèle avec cette liste : Recommander des produits pour un détaillant en ligne, L’article suivant à partir des sessions de navigation et Des livres pour les lecteurs.
La comparaison
Section intitulée « La comparaison »- La semaine de test est petite. 1 234 clients y ont passé commande. Les intervalles du recall@10 étaient d’environ ±0,02. Un segment d’environ 300 clients prouve peu de choses.
- Les tendances étaient encore difficiles à battre. Sur la semaine de test, les tendances avaient un recall@10 d’environ 0,16, et d’environ 0,14 avec les règles. Chaque méthode utilisée seule se situait sous les tendances. Des livres pour les lecteurs a obtenu le même résultat sur des données réelles.
- Le modèle de classement à deux étapes a gagné hors ligne. Avec les règles, il dépassait les tendances d’environ 0,04 sur la semaine de test. La différence était nette pour chaque segment.
Une semaine de validation peut mener au mauvais choix
Section intitulée « Une semaine de validation peut mener au mauvais choix »L’équipe du cours a fait le réglage sur la période du 20 au 26 juillet, la première semaine après la période manquante. Cette semaine-là, le modèle de classement pouvait apprendre uniquement à partir d’anciennes semaines. Les tendances battaient donc le modèle de classement pour les clients nouveaux et occasionnels.
L’équipe du cours a donc choisi une bascule : les tendances pour les clients ayant moins de 3 commandes. Pour les autres, elle utilisait le modèle de classement. Sur la semaine de test, le modèle de classement seul était meilleur.
L’équipe du cours a gardé la bascule. Modifier la conception après le test aurait transformé la semaine de test en deuxième période de validation. Voilà pourquoi la période de validation par défaut couvre maintenant deux semaines complètes avant la période manquante.
Les semaines notées
Section intitulée « Les semaines notées »- La bascule de l’équipe du cours était un peu meilleure que les tendances : environ 0,15 contre environ 0,14. Tout le gain provenait des clients fidèles.
- Le modèle de classement seul était encore meilleur : environ 0,17. Son gain provenait des clients occasionnels et fidèles. Les nouveaux clients obtenaient à peu près le même résultat qu’avec les tendances.
Les nouveaux produits
Section intitulée « Les nouveaux produits »- Montrer des nouveaux produits n’est pas la même chose que les deviner. Une case réservée montrait presque tous les produits Home office à environ deux tiers des clients ayant passé commande. Elle retrouvait environ 1 % de leurs commandes Home office.
- Cela avait un coût. Cette case réduisait le rappel des clients connus d’environ 4 %. C’est plus que la limite de 2 % d’Omar. Un dossier doit le dire, et prendre une décision.
Les règles et la page produit
Section intitulée « Les règles et la page produit »- Les règles comptent davantage pour le courriel. Sans règles, environ 8 % des cases des listes de l’équipe du cours contenaient des produits de santé sensibles. Les retirer coûtait environ 0,016 de rappel. Ensemble, toutes les règles modifiaient 95 % des listes.
- Les voisins du lot étaient des produits de remplacement. Sur les pages des nouveaux meubles, environ 8 des 10 voisins étaient des produits du même type. Un petit tableau des « achats suivants », par sous-catégorie, ajoutait des compléments à plusieurs pages. L’article suivant à partir des sessions de navigation montre une idée voisine : les produits vus pendant la même visite.
Le courriel, dans la simulation
Section intitulée « Le courriel, dans la simulation »Environ 4 700 clients ont reçu deux courriels simulés. La moitié recevait les tendances, et l’autre moitié les listes de l’équipe du cours. Les tendances rapportaient environ 1,2 $ de revenu supplémentaire par courriel.
- Les listes de l’équipe du cours rapportaient moins. Dans 18 des 20 tests simulés, la différence n’était pas nette. Dans 2 tests, les listes de l’équipe du cours étaient nettement moins bonnes.
- Le gagnant hors ligne rapportait le moins. Le modèle de classement seul avait le meilleur score sur les semaines notées. Dans la simulation, il rapportait environ 0,9 $ par courriel. Il était nettement moins bon que les tendances dans 3 des 20 tests.
Un gain hors ligne ne garantit pas un gain en ligne. Voilà pourquoi la partie 5 demande un plan de test avant tout envoi.
La vitesse
Section intitulée « La vitesse »Sur l’ordinateur portable de l’équipe du cours, d’autres tâches lourdes s’exécutaient en même temps. Ces durées sont donc longues :
- Le traitement en lot nocturne prenait environ 4 minutes pour la bascule. Il prenait environ 21 minutes pour le modèle de classement appliqué à chaque client (42 088 clients).
- Une consultation dans le service avait un p50 d’environ 1,5 ms. Son p95 était d’environ 93 ms : juste sous les 100 ms d’Amira.
- Le modèle de classement au moment de la requête prenait environ 145 ms pour la moitié des clients. Cela dépasse le budget, donc le courriel et la page proviennent du lot.
Erreurs fréquentes
Section intitulée « Erreurs fréquentes »Erreur courante
Le modèle de classement n'a aucune donnée pour apprendre
Symptôme : vous avez choisi la semaine du 20 au 26 juillet pour la validation. recs evaluate two-stage --period validation s’arrête avec une longue erreur de LightGBM. Sa dernière ligne est :
ValueError: Input data must be 2 dimensional and non empty.Cause : le modèle de classement apprend sur les 14 jours précédant la période. Avant le 20 juillet, ces jours tombent dans la période manquante : aucune commande, donc aucune étiquette.
Solution : choisissez une période de validation précédée de deux semaines d’événements, comme la période par défaut. Ou ajoutez --set train_days=21 pour que le modèle de classement remonte jusqu’au journal du cours. Le modèle apprend alors uniquement sur d’anciennes semaines, et il est peu performant. Dans l’essai de l’équipe du cours, il a perdu face aux tendances cette semaine-là. Il a gagné pendant la semaine de test, avec une semaine de données de Home office. Une période de validation différente de la période où vous servez les recommandations peut mener au mauvais choix de conception. Indiquez dans votre rapport sur quelle fenêtre le modèle de classement a appris.
Conséquence dans le travail en IA : un modèle entraîné sur une fenêtre vide échoue aussi sans avertissement en production. Vérifiez le contenu de chaque fenêtre d’entraînement.
Erreur courante
Une meilleure moyenne qui cache un segment moins bien servi
Symptôme : la conception choisie obtient le meilleur rappel à 10 (recall@10) global. Un collègue constate que les clients occasionnels sont moins bien servis, ou que la nouvelle catégorie apparaît très rarement.
Cause : la moyenne mélange les segments, et les nouveaux produits représentent une petite part des commandes. Un gain important pour les clients fidèles peut cacher une perte ailleurs.
Solution : présentez chaque segment et sa taille, utilisez recs compare --by segment et rapportez séparément les résultats des nouveaux produits. Nommez le groupe perdant et dites ce que vous faites pour lui.
Conséquence dans le travail en IA : un changement qui a « gagné » est annulé après les plaintes d’un groupe de clients.
- Les semaines notées devinées à partir du journal du cours. Régler une conception selon « ce qui s’est vendu en août dernier » n’est pas un découpage temporel. Utilisez uniquement les jours précédant votre période.
- Les tendances interprétées sans tenir compte de la période manquante. Juste après la période manquante, « les 28 derniers jours » ne contiennent que deux semaines d’événements. Précisez-le quand vous interprétez une liste de tendances.
- La réponse de Tomás acceptée. Le classement en deux étapes dominait le tableau hors ligne du cours, et il a aussi gagné hors ligne ici. Dans le courriel simulé de l’équipe du cours, il a rapporté le moins. La nouvelle catégorie pose aussi un problème différent. Mesurez chaque emplacement ici.
- Une page produit qui montre seulement des alternatives. Dix autres bureaux sur la page d’un bureau peuvent convenir à un client qui choisit encore. Ils ne conviennent pas à un client qui en a acheté un. Dites à qui votre page s’adresse.
- Une suppression testée sur le mauvais lot.
recs forgetreconstruit le lot. Exécutez cette commande dans un dossier de sorties distinct, ou après avoir exporté vos listes. - Un test arrêté quand il « semble bon ». Décidez d’abord de la taille, puis examinez les résultats une seule fois.
Afficher les valeurs de vérification publiques
Ouvrez ceci seulement après avoir obtenu vos propres chiffres. Ces valeurs proviennent des fichiers publics, ce qui vous permet de les vérifier. Ce ne sont pas les réponses au travail.
- Données : 150 nouveaux produits dans 6 sous-catégories, tous ajoutés le 20 juillet 2026; 5 000 nouveaux clients, dont 2 088 avec un événement dans les fichiers; 37 140 événements du 20 juillet au 2 août 2026. Chaque fichier dans
SHA256SUMSest valide. - Le dossier de données :
make_data.pyécrit 3 144 produits, 45 000 clients et 842 456 événements. Avec les périodes par défaut,recs checkdonne0.106pourpopular(rapide). - Les périodes par défaut : 2 118 clients ont commandé pendant la période de validation (la période de test du cours). Pendant la semaine de test, 1 234 clients ont commandé.
trendingsur la période de validation : recall@10 de0.156, comme dans le cours. - Vitesse sur le portable occupé de l’équipe du cours (Apple M4, un fil d’exécution) : le traitement en lot nocturne pour 42 088 clients a pris environ 4 minutes avec la sélection entre méthodes. Il a pris environ 21 minutes avec le modèle de classement pour chaque client.
Récapitulatif
Vous pouvez maintenant partir d’un problème de recommandation dans une nouvelle catégorie pour arriver à une décision. Vous précisez le but de chaque emplacement et le coût d’une mauvaise suggestion. Vous faites un découpage temporel sans fuite de données. Vous comparez la popularité à d’autres familles de méthodes, par segment, avec des intervalles. Vous montrez de nouveaux produits dès leur première semaine et servez les clients sans historique. Vous choisissez un système en présentant clairement ses règles, son coût et le groupe perdant. Vous l’exploitez comme un service avec une solution de repli et une demande de suppression. Vous planifiez aussi le test par courriel, avec sa taille et sa règle d’arrêt décidées à l’avance. Vous savez qu’un gagnant hors ligne n’est pas forcément nettement meilleur en ligne.