Search Engine

Vue d'ensemble

Products Manager v5.7 intègre deux moteurs de recherche complémentaires qui opèrent en parallèle :

• Meilisearch : moteur de recherche full-text optimisé pour la rapidité et la pertinence par mots-clés (< 50 ms).
• Qdrant : moteur de recherche sémantique basé sur des embeddings vectoriels, qui comprend le sens des requêtes indépendamment des mots exacts utilisés.

Ces deux moteurs sont combinés dans la barre de recherche principale pour produire des résultats hybrides, exploitant la précision du full-text et la richesse sémantique des vecteurs. Chacun peut également être utilisé indépendamment selon le contexte (recherche de doublons, produits similaires, etc.).

La fonctionnalité est contrôlée par le feature flag search_engine (voir Module feature flags).

Meilisearch — Recherche full-text

Champs indexés

Meilisearch indexe les champs suivants pour chaque produit :

Performances

La recherche full-text retourne les premiers résultats en moins de 50 ms pour un catalogue de plusieurs millions de produits. Meilisearch maintient l'index en mémoire pour des réponses quasi-instantanées, y compris avec des filtres et des facettes actifs.

Tolérance aux fautes de frappe

Meilisearch applique une tolérance aux fautes de frappe (typo-tolerance) configurable :

• 1 faute tolérée pour les mots de 5 à 8 caractères
• 2 fautes tolérées pour les mots de 9 caractères et plus
• Correspondance exacte requise pour les codes (SKU, EAN) via la configuration exactAttributes

Stemming et langues

Le stemming (réduction à la racine des mots) est appliqué selon la langue du catalogue. Products Manager configure automatiquement Meilisearch avec les langues actives dans les paramètres tenant.

Filtres et facettes

La recherche full-text supporte des filtres combinables :

catégorie = "Électronique" AND marque = "Samsung" AND prix >= 100 AND stock > 0

Les facettes permettent un affichage dynamique des filtres disponibles dans l'interface (ex. : nombre de produits par marque, par catégorie, par tranche de prix). Elles sont calculées en temps réel avec chaque requête.

Attributs filtrables configurés : category, brand, price, stock_status, status, tags, tenant_id.

Configuration

MEILISEARCH_URL=http://localhost:7700
MEILISEARCH_MASTER_KEY=votre_master_key

Indexation asynchrone

L'index Meilisearch est mis à jour de manière asynchrone après chaque mutation produit (création, modification, suppression) via une tâche Celery. Le délai entre la modification et sa visibilité dans la recherche est généralement inférieur à 2 secondes.

Réindexation complète

En cas de désynchronisation ou après une migration de données, vous pouvez déclencher une réindexation complète du catalogue :

# Via l'API admin
POST /api/v1/search/reindex

# Via la commande Django
python manage.py reindex_search --engine meilisearch

La réindexation est exécutée en tâche de fond et n'interrompt pas le service (double-buffering d'index).

Qdrant — Recherche sémantique

Principe

Qdrant stocke des vecteurs d'embeddings représentant la signification sémantique de chaque produit. Contrairement à la recherche full-text, la recherche sémantique ne cherche pas des mots identiques mais des concepts proches.

Exemples :

• La requête "protection écran tablette" peut trouver "Film protecteur iPad" même sans le mot "protection".
• La requête "chaussures de sport légères" peut trouver des "sneakers running" ou "baskets trail".

Embeddings

Les embeddings sont générés via le modèle OpenAI text-embedding-3-small (1536 dimensions). Ce modèle offre un bon équilibre entre qualité sémantique et coût.

Le texte soumis à l'embedding est une concaténation structurée des champs produit :

{nom} | {marque} | {catégorie} | {description courte} | {tags}

La génération d'embeddings requiert une clé API OpenAI valide (variable OPENAI_API_KEY). Les embeddings sont générés une seule fois par produit et mis en cache — ils ne sont recalculés que si les champs texte du produit changent.

Cas d'usage

Qdrant est utilisé dans plusieurs contextes dans Products Manager :

Configuration

QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=votre_api_key

Collection Qdrant

Products Manager utilise une collection Qdrant nommée products avec la configuration suivante :

{
  "collection_name": "products",
  "vectors": {
    "size": 1536,
    "distance": "Cosine"
  },
  "payload_schema": {
    "sku": "keyword",
    "category": "keyword",
    "brand": "keyword",
    "tenant_id": "keyword",
    "product_id": "integer"
  }
}

Chaque vecteur est accompagné d'un payload JSON contenant les métadonnées filtrables (SKU, catégorie, marque, tenant). Cela permet de restreindre la recherche sémantique à un tenant ou une catégorie spécifique.

Recherche hybride

La barre de recherche principale de Products Manager combine les résultats des deux moteurs :

1. Meilisearch retourne les N premiers résultats full-text triés par pertinence keyword.
2. Qdrant retourne les N premiers résultats sémantiquement proches.
3. Un algorithme de fusion des scores (Reciprocal Rank Fusion) combine et déduplique les deux listes pour produire un classement final.

Ce mode hybride est particulièrement efficace pour :

• Les requêtes courtes ou approximatives (bénéficient de la sémantique)
• Les requêtes avec codes produit exacts (bénéficient du full-text)
• Les requêtes multi-mots avec synonymes ou variantes

Module feature flag

Le moteur de recherche est contrôlé par le feature flag search_engine. Lorsqu'il est désactivé, Products Manager revient à une recherche SQL basique (ILIKE).

Pour activer ou désactiver le module :

Settings > Modules > Search Engine → toggle actif/inactif

Ou via l'API admin :

PATCH /api/v1/admin/modules/search_engine
{ "enabled": true }

Il est possible d'activer Meilisearch sans Qdrant (recherche full-text uniquement) en laissant QDRANT_URL non défini.

Performances et monitoring

Le monitoring des performances de recherche est disponible dans Settings > Monitoring > Search. Vous y trouverez les temps de réponse, le volume de requêtes, et les termes recherchés les plus fréquents.

Dépannage

Meilisearch non disponible → fallback SQL LIKE

Si Meilisearch est inaccessible (service arrêté, timeout), Products Manager bascule automatiquement sur une recherche SQL ILIKE. Les performances sont dégradées (plusieurs secondes sur de grands catalogues) mais le service reste fonctionnel. Une alerte est émise dans les logs et le dashboard monitoring.

Qdrant indisponible → recherche keyword seule

Si Qdrant est inaccessible, la recherche hybride se dégrade en recherche full-text uniquement (Meilisearch seul). Les fonctionnalités dépendant de Qdrant (produits similaires, détection de doublons sémantique) sont temporairement désactivées avec un message d'information dans l'interface.

Index Meilisearch désynchronisé

Si les résultats de recherche ne reflètent pas les dernières modifications produit :

python manage.py reindex_search --engine meilisearch

Embeddings Qdrant manquants

Si des produits n'apparaissent pas dans la recherche sémantique (pas d'embedding généré) :

python manage.py reindex_search --engine qdrant

Cette commande régénère les embeddings manquants sans recalculer ceux qui sont déjà à jour.

Résultats de recherche vides après migration

Après une migration de base de données ou un changement de schéma, déclenchez une réindexation complète des deux moteurs :

python manage.py reindex_search --engine all