Blog · November 2026 · 9 min read Blog · Novembre 2026 · 9 min de lectureالمدونة · نوفمبر 2026 · 9 دقائق قراءة

Recommending products three ways, and the bugs I found a year later Recommander des produits de trois façons, et les bugs trouvés un an plus tardالتوصية بالمنتجات بثلاث طرق، والأخطاء التي وجدتها بعد عام

ShopO, our bachelor's final project, recommends products with popularity, cosine similarity and K-Means clustering. It worked on defense day. Rereading the code more than a year later, I found six problems, some of them invisible in a demo. ShopO, notre projet de fin de Licence, recommande des produits par popularité, par similarité cosinus et par clustering K-Means. Ça marchait le jour de la soutenance. En relisant le code plus d'un an après, j'ai trouvé six problèmes, dont certains invisibles pendant une démo.ShopO، مشروع تخرجنا في الليسانس، يوصي بالمنتجات حسب الشعبية، والتشابه بجيب التمام، والتجميع بـ K-Means. كان يعمل يوم المناقشة. وعند إعادة قراءة الشيفرة بعد أكثر من عام، وجدت ست مشكلات، بعضها لا يظهر أثناء العرض.

The projectLe projetالمشروع

ShopO is a multi-seller marketplace for electronics that we built as a team for our bachelor's degree at USTHB, defended in June 2025: React and TypeScript on the front, a Laravel API, MySQL, PayPal. Two places show recommendations: "similar products" on a product page, and "for you" on the customer's page. ShopO est une marketplace multi-vendeurs d'électronique, construite en équipe pour notre Licence à l'USTHB et soutenue en juin 2025 : React et TypeScript côté interface, une API Laravel, MySQL, PayPal. Deux endroits affichent des recommandations : les « produits similaires » sur la page d'un produit, et « pour vous » sur la page du client.ShopO سوق إلكترونية متعددة البائعين للأجهزة الإلكترونية، بنيناها كفريق لشهادة الليسانس في جامعة هواري بومدين، ونوقشت في جوان 2025: React وTypeScript في الواجهة، وواجهة برمجية بـ Laravel، وMySQL، وPayPal. ويعرض مكانان التوصيات: «منتجات مشابهة» في صفحة المنتج، و«مقترحة لك» في صفحة الزبون.

A new marketplace has no users and no ratings, so we seeded it with a public Kaggle dataset of electronics products: 965 products and 35,642 ratings from 351 users. The three approaches were explored in Jupyter notebooks first, then moved into a Flask service. Une nouvelle marketplace n'a ni utilisateurs ni notes : nous l'avons donc remplie avec un jeu de données Kaggle public de produits électroniques, soit 965 produits et 35 642 notes données par 351 utilisateurs. Les trois approches ont d'abord été explorées dans des notebooks Jupyter, puis intégrées dans un service Flask.السوق الجديدة لا مستخدمين لها ولا تقييمات، لذلك ملأناها بمجموعة بيانات عامة من Kaggle لمنتجات إلكترونية: 965 منتجاً و35642 تقييماً من 351 مستخدماً. استكشفنا الطرق الثلاث أولاً في دفاتر Jupyter، ثم نقلناها إلى خدمة Flask.

React/api/recommendations
→
LaravelMySQL → CSV
→
Flaskpandas · scikit-learn
→
Product idsIdentifiantsالمعرّفات→ Product::whereIn

Laravel exports products and ratings to CSV with Artisan commands. The Flask service trains on those files and returns product ids; Laravel then loads the full products from MySQL and sends them to the front end. Laravel exporte les produits et les notes en CSV avec des commandes Artisan. Le service Flask s'entraîne sur ces fichiers et renvoie des identifiants de produits ; Laravel charge ensuite les produits complets depuis MySQL et les envoie à l'interface.يصدّر Laravel المنتجات والتقييمات إلى ملفات CSV بأوامر Artisan. وتتدرب خدمة Flask على هذه الملفات وتعيد معرّفات المنتجات؛ ثم يحمّل Laravel المنتجات كاملة من MySQL ويرسلها إلى الواجهة.

1. Popularity, for people we know nothing about1. La popularité, pour ceux qu'on ne connaît pas1. الشعبية، لمن لا نعرف عنهم شيئاً

A visitor with no history gets the classic answer: the best-rated products. To avoid a product with one 5-star rating topping the list, we kept only products with an average above 3 and more than 100 ratings, then took the top 15. Un visiteur sans historique reçoit la réponse classique : les produits les mieux notés. Pour éviter qu'un produit avec une seule note de 5 étoiles arrive en tête, nous avons gardé seulement les produits avec une moyenne supérieure à 3 et plus de 100 notes, puis pris les 15 premiers.الزائر الذي لا تاريخ له يحصل على الإجابة الكلاسيكية: المنتجات الأعلى تقييماً. ولتجنب أن يتصدر القائمة منتج له تقييم واحد بخمس نجوم، أبقينا فقط المنتجات التي يتجاوز متوسطها 3 ولها أكثر من 100 تقييم، ثم أخذنا أول 15.

2. Content-based: products that look alike2. Par contenu : des produits qui se ressemblent2. حسب المحتوى: منتجات متشابهة

On a product page, "similar" means similar description. Each product's description and category become a bag of words (the 3,000 most frequent English words, without stop words), and cosine similarity measures the angle between two products' word vectors: 1 means the same words in the same proportions. Sur la page d'un produit, « similaire » veut dire une description similaire. La description et la catégorie de chaque produit deviennent un sac de mots (les 3 000 mots anglais les plus fréquents, sans les mots vides), et la similarité cosinus mesure l'angle entre les vecteurs de mots de deux produits : 1 veut dire les mêmes mots dans les mêmes proportions.في صفحة المنتج، «مشابه» يعني وصفاً مشابهاً. يتحول وصف كل منتج وفئته إلى حقيبة كلمات (أكثر 3000 كلمة إنجليزية تكراراً، دون الكلمات الشائعة الفارغة)، ويقيس التشابه بجيب التمام الزاوية بين متجهي كلمات منتجين: القيمة 1 تعني الكلمات نفسها بالنسب نفسها.

product_dataset["tags"] = product_dataset["about"] + product_dataset["category_name"]

cv = CountVectorizer(max_features=3000, stop_words="english")
vector = cv.fit_transform(product_dataset["tags"].values.astype("U")).toarray()
similarity = cosine_similarity(vector)   # 965 x 965 matrix

# for a product: sort its row, skip itself, keep the next 9
distance = sorted(enumerate(similarity[index]), key=lambda x: x[1], reverse=True)
recommended = [products.iloc[i]["id"] for i, _ in distance[1:10]]

3. Collaborative filtering: people like you3. Le filtrage collaboratif : les gens comme vous3. التصفية التعاونية: أشخاص يشبهونك

For a customer with a history, we look at what similar customers liked. First we drop the noise: products with 5 ratings or fewer, then users with 10 ratings or fewer. Then a user × product table of ratings is grouped with K-Means. The number of groups is not hard-coded: the service tries k from 1 to 20 and picks the "elbow" of the error curve with KneeLocator, with a minimum of 5. Pour un client avec un historique, on regarde ce qu'ont aimé les clients qui lui ressemblent. D'abord, on retire le bruit : les produits avec 5 notes ou moins, puis les utilisateurs avec 10 notes ou moins. Ensuite, un tableau utilisateurs × produits des notes est regroupé avec K-Means. Le nombre de groupes n'est pas fixé dans le code : le service essaie k de 1 à 20 et choisit le « coude » de la courbe d'erreur avec KneeLocator, avec un minimum de 5.للزبون الذي له تاريخ، ننظر إلى ما أحبه الزبائن المشابهون له. أولاً نزيل الضجيج: المنتجات التي لها 5 تقييمات أو أقل، ثم المستخدمون الذين لهم 10 تقييمات أو أقل. ثم يُجمَّع جدول تقييمات المستخدمين × المنتجات بخوارزمية K-Means. وعدد المجموعات غير مثبّت في الشيفرة: تجرّب الخدمة k من 1 إلى 20 وتختار «المرفق» في منحنى الخطأ بـ KneeLocator، بحد أدنى 5.

pivot = filtered.pivot_table(index="User ID", columns="Product ID", values="Rating").fillna(0)

sse = [KMeans(n_clusters=k, n_init=5, random_state=42).fit(pivot).inertia_ for k in range(1, 21)]
elbow = KneeLocator(range(1, 21), sse, curve="convex", direction="decreasing").elbow
best_k = max(elbow or 5, 5)

pivot["cluster"] = KMeans(n_clusters=best_k, n_init=5, random_state=0).fit_predict(pivot)
# for a user: average rating of each product inside their cluster,
# minus what they already rated, top 9

What I found rereading itCe que j'ai trouvé en le relisantما وجدته عند إعادة القراءة

The demo looked right: products appeared, they seemed related, the jury was happy. Reading the code again with more experience, here is what was wrong, from the most visible to the most subtle. La démo avait l'air juste : des produits apparaissaient, ils semblaient liés, le jury était content. En relisant le code avec plus d'expérience, voici ce qui n'allait pas, du plus visible au plus subtil.بدا العرض صحيحاً: ظهرت منتجات، وبدت مترابطة، وكانت اللجنة راضية. وعند إعادة قراءة الشيفرة بخبرة أكبر، هذا ما كان خاطئاً، من الأوضح إلى الأدق.

Bug 1: popular products returned row numbers, not product idsBug 1 : les produits populaires renvoyaient des numéros de ligne, pas des identifiantsالخطأ 1: المنتجات الشائعة أعادت أرقام أسطر لا معرّفات منتجات

After a reset_index(), the DataFrame index is just 0, 1, 2… and the product id becomes a normal column. The loop used the index: Après un reset_index(), l'index du DataFrame vaut simplement 0, 1, 2… et l'identifiant du produit devient une colonne normale. La boucle utilisait l'index :بعد reset_index()، يصبح فهرس DataFrame مجرد 0، 1، 2… ويتحول معرّف المنتج إلى عمود عادي. لكن الحلقة استعملت الفهرس:

for product_id, row in top_products.iterrows():   # product_id = row position
    recommended.append({"id": product_id, ...})

# fix
    recommended.append({"id": int(row["Product ID"]), ...})

The names in the JSON were right, so testing the endpoint alone looked fine. But Laravel only uses the ids, so the "popular" section showed products whose ids happened to equal those row positions: unrelated products. Les noms dans le JSON étaient justes, donc tester l'endpoint seul semblait correct. Mais Laravel n'utilise que les identifiants : la section « populaires » affichait les produits dont l'identifiant tombait par hasard sur ces numéros de ligne : des produits sans rapport.كانت الأسماء في JSON صحيحة، لذا بدا اختبار نقطة الوصول وحدها سليماً. لكن Laravel لا يستعمل إلا المعرّفات، فكان قسم «الشائعة» يعرض المنتجات التي صادف أن معرّفاتها تساوي أرقام تلك الأسطر: منتجات لا علاقة لها بالشعبية.

Bug 2: the ranking was lost on the way backBug 2 : le classement se perdait au retourالخطأ 2: ضاع الترتيب في طريق العودة

Flask carefully sorts products from most to least similar. Then Laravel runs Product::whereIn('id', $ids), and MySQL returns them in its own order, usually by id. The best recommendation could end up last. The fix is to sort the collection by the position in the list Flask sent: Flask trie soigneusement les produits du plus au moins similaire. Puis Laravel exécute Product::whereIn('id', $ids), et MySQL les renvoie dans son propre ordre, en général par identifiant. La meilleure recommandation pouvait finir dernière. La correction consiste à trier la collection selon la position dans la liste envoyée par Flask :يرتّب Flask المنتجات بعناية من الأكثر إلى الأقل تشابهاً. ثم ينفّذ Laravel Product::whereIn('id', $ids)، فيعيدها MySQL بترتيبه الخاص، غالباً حسب المعرّف. وقد تصبح أفضل توصية في الأخير. والتصحيح هو ترتيب المجموعة حسب الموقع في القائمة التي أرسلها Flask:

$order = $ids->flip();   // id => position
$products = Product::whereIn('id', $ids)->get()
    ->sortBy(fn ($p) => $order[$p->id])->values();

Bug 3: two words glued togetherBug 3 : deux mots collésالخطأ 3: كلمتان ملتصقتان

about + category_name concatenates two strings with no space, so the last word of the description and the first word of the category become one invented word, like "purchaseAccessories" (from "…date of purchase" + "Accessories&Peripherals"). The category, the most useful signal, was partly lost. One space fixes it: about + " " + category_name. about + category_name colle deux chaînes sans espace : le dernier mot de la description et le premier mot de la catégorie deviennent un seul mot inventé, comme « purchaseAccessories » (de « …date of purchase » + « Accessories&Peripherals »). La catégorie, l'indice le plus utile, était en partie perdue. Un espace suffit : about + " " + category_name.about + category_name تلصق نصين دون مسافة، فتصبح آخر كلمة في الوصف وأول كلمة في الفئة كلمة واحدة مخترعة، مثل «purchaseAccessories» (من «…date of purchase» و«Accessories&Peripherals»). وضاعت الفئة جزئياً، مع أنها أكثر المؤشرات فائدة. ومسافة واحدة تكفي: about + " " + category_name.

Problem 4: "not rated" was treated as "rated 0"Problème 4 : « pas noté » était traité comme « noté 0 »المشكلة 4: «غير مقيَّم» عومل كأنه «مقيَّم بصفر»

fillna(0) fills every missing rating with 0, on a 1 to 5 scale. For K-Means, a user who never saw a product "hated" it. And the cluster average of a product rated 5 by two people out of fifty becomes 0.2, so the recommender mostly pushes products that many people rated, not products people loved. Averaging only real ratings, or using a method built for sparse data like matrix factorization, would be more honest. fillna(0) remplace chaque note manquante par 0, sur une échelle de 1 à 5. Pour K-Means, un utilisateur qui n'a jamais vu un produit l'a « détesté ». Et la moyenne dans un groupe d'un produit noté 5 par deux personnes sur cinquante devient 0,2 : le système pousse surtout les produits que beaucoup de gens ont notés, pas ceux que les gens ont adorés. Faire la moyenne des vraies notes seulement, ou utiliser une méthode faite pour les données creuses comme la factorisation de matrice, serait plus juste.fillna(0) يملأ كل تقييم ناقص بصفر، على سلّم من 1 إلى 5. فبالنسبة لـ K-Means، المستخدم الذي لم يرَ المنتج قط «كرهه». ومتوسط منتج داخل مجموعة، قيّمه شخصان من خمسين بخمس نجوم، يصبح 0.2، فيدفع النظام أساساً المنتجات التي قيّمها كثيرون، لا تلك التي أحبها الناس. وحساب متوسط التقييمات الحقيقية فقط، أو استعمال طريقة مصممة للبيانات المتناثرة مثل تحليل المصفوفات، سيكون أكثر إنصافاً.

Problem 5: the model never learned anything newProblème 5 : le modèle n'apprenait jamais rien de nouveauالمشكلة 5: لم يتعلم النموذج شيئاً جديداً قط

A background thread asked Laravel to re-export the CSV files every 60 seconds. But all the training (vectors, similarity matrix, clusters) ran once, when the service started. The files on disk were always fresh; the model in memory was frozen. A product added after startup could never be recommended until someone restarted the service. Retraining after each export, or on a schedule, closes the loop. Un thread en arrière-plan demandait à Laravel de réexporter les fichiers CSV toutes les 60 secondes. Mais tout l'entraînement (vecteurs, matrice de similarité, groupes) ne tournait qu'une fois, au démarrage du service. Les fichiers sur le disque étaient toujours à jour ; le modèle en mémoire, lui, était figé. Un produit ajouté après le démarrage ne pouvait jamais être recommandé, jusqu'à ce que quelqu'un redémarre le service. Réentraîner après chaque export, ou à intervalle régulier, ferme la boucle.كان خيط في الخلفية يطلب من Laravel إعادة تصدير ملفات CSV كل 60 ثانية. لكن التدريب كله (المتجهات، ومصفوفة التشابه، والمجموعات) كان يعمل مرة واحدة عند تشغيل الخدمة. فالملفات على القرص كانت دائماً محدّثة، أما النموذج في الذاكرة فكان جامداً. والمنتج المضاف بعد التشغيل لا يمكن التوصية به أبداً حتى يعيد أحدهم تشغيل الخدمة. وإعادة التدريب بعد كل تصدير، أو بشكل دوري، تغلق الحلقة.

Problem 6: thresholds made for Kaggle, not for a new shopProblème 6 : des seuils faits pour Kaggle, pas pour une nouvelle boutiqueالمشكلة 6: عتبات مصنوعة لـ Kaggle، لا لمتجر جديد

"More than 100 ratings" works on a dataset where 64 products have that many. On a real new marketplace, no product would have 100 ratings for months, so the popularity list, the one meant for new visitors, would be empty exactly when it is needed most. A weighted average that pulls products with few ratings toward the global average, plus a fallback to recent best-sellers, would work from the first day. « Plus de 100 notes », ça marche sur un jeu de données où 64 produits en ont autant. Sur une vraie nouvelle marketplace, aucun produit n'aurait 100 notes avant des mois : la liste des populaires, celle prévue pour les nouveaux visiteurs, serait vide justement quand on en a le plus besoin. Une moyenne pondérée qui rapproche les produits peu notés de la moyenne générale, avec un repli sur les meilleures ventes récentes, marcherait dès le premier jour.«أكثر من 100 تقييم» تنجح في مجموعة بيانات فيها 64 منتجاً لها هذا العدد. أما في سوق جديدة حقيقية، فلن يصل أي منتج إلى 100 تقييم قبل أشهر، فتكون قائمة الشائعة، وهي المخصصة للزوار الجدد، فارغة بالضبط حين نحتاجها أكثر. ومتوسط مرجّح يقرّب المنتجات قليلة التقييم من المتوسط العام، مع اللجوء إلى الأكثر مبيعاً مؤخراً، سيعمل من اليوم الأول.

What I would build todayCe que je construirais aujourd'huiما كنت سأبنيه اليوم

  • Tests on the contract, not just the model. Bugs 1 and 2 were not machine learning bugs: they lived at the boundary between Python and PHP. One test checking "the first id Flask returns is the first product Laravel shows" would have caught both.Tester le contrat, pas seulement le modèle. Les bugs 1 et 2 n'étaient pas des bugs d'apprentissage automatique : ils vivaient à la frontière entre Python et PHP. Un seul test vérifiant « le premier identifiant renvoyé par Flask est le premier produit affiché par Laravel » les aurait attrapés tous les deux.اختبار العقد بين الخدمتين، لا النموذج فقط. لم يكن الخطآن 1 و2 خطأي تعلم آلي: كانا على الحدود بين Python وPHP. واختبار واحد يتحقق من أن «أول معرّف يعيده Flask هو أول منتج يعرضه Laravel» كان سيلتقطهما معاً.
  • An offline evaluation. Hide some of each user's ratings, recommend, and count how many hidden products show up. Without a number, "the recommendations look good" is an opinion.Une évaluation hors ligne. Cacher une partie des notes de chaque utilisateur, recommander, et compter combien de produits cachés apparaissent. Sans chiffre, « les recommandations ont l'air bonnes » reste une opinion.تقييم دون اتصال. إخفاء جزء من تقييمات كل مستخدم، ثم التوصية، وعدّ كم منتجاً مخفياً يظهر. فبدون رقم، تبقى عبارة «التوصيات تبدو جيدة» مجرد رأي.
  • Something that scales. A full similarity matrix is fine for 965 products (under a million values), but it grows with the square of the catalog. TF-IDF vectors with a nearest-neighbors index would keep working with a much larger catalog.Quelque chose qui passe à l'échelle. Une matrice de similarité complète va bien pour 965 produits (moins d'un million de valeurs), mais elle grandit avec le carré du catalogue. Des vecteurs TF-IDF avec un index des plus proches voisins continueraient de marcher avec un catalogue beaucoup plus grand.حل قابل للتوسع. مصفوفة التشابه الكاملة مناسبة لـ 965 منتجاً (أقل من مليون قيمة)، لكنها تكبر بمربع حجم الكتالوج. ومتجهات TF-IDF مع فهرس لأقرب الجيران ستبقى تعمل مع كتالوج أكبر بكثير.

TakeawaysÀ retenirالخلاصة

  • Each approach covers a different moment: popularity for strangers, content for a product page, collaborative filtering for known customers.Chaque approche couvre un moment différent : la popularité pour les inconnus, le contenu pour la page d'un produit, le filtrage collaboratif pour les clients connus.كل طريقة تغطي لحظة مختلفة: الشعبية للغرباء، والمحتوى لصفحة المنتج، والتصفية التعاونية للزبائن المعروفين.
  • In a recommender, a missing value is information. Turning it into a zero changes what the model learns.Dans un système de recommandation, une valeur manquante est une information. La transformer en zéro change ce que le modèle apprend.في نظام التوصية، القيمة الناقصة معلومة في حد ذاتها. وتحويلها إلى صفر يغيّر ما يتعلمه النموذج.
  • The riskiest code is often the glue between two services, not the algorithm.Le code le plus risqué est souvent la colle entre deux services, pas l'algorithme.أخطر شيفرة غالباً هي الرابط بين خدمتين، لا الخوارزمية.
  • Rereading your old code is one of the best ways to see how much you have learned.Relire son ancien code est une des meilleures façons de voir tout ce qu'on a appris.إعادة قراءة شيفرتك القديمة من أفضل الطرق لترى كم تعلمت.

The code, the notebooks and the UML diagrams are on GitHub. Le code, les notebooks et les diagrammes UML sont sur GitHub.الشيفرة ودفاتر Jupyter ومخططات UML موجودة على GitHub.