Wo WooCommerce WordPress & WooCommerce Débutant

Vector Search Native — Documentation complète

Installation, configuration des providers IA, indexation, REST API, hooks et dépannage du plugin de recherche sémantique WooCommerce.

Mis à jour juillet 1, 2026 Version du module 1.0.0

Présentation

Vector Search Native transforme la recherche produit WooCommerce en moteur sémantique. Au lieu de comparer des mots-clés lettre à lettre, le plugin convertit chaque produit et chaque requête en vecteurs numériques (embeddings) via un modèle d’IA, puis calcule leur similarité de sens. Résultat : un client qui tape « veste été coton léger » trouve votre « blazer estival en lin », même sans mot commun.

Le plugin prend en charge trois providers d’embeddings — OpenAI, Voyage AI et Cohere — interchangeables en un clic, avec une indexation incrémentale qui n’appelle l’API que lorsque le contenu d’un produit a réellement changé, et un fallback automatique vers la recherche mots-clés native lorsque la recherche vectorielle ne suffit pas.

Prérequis

WordPress 6.2 ou supérieur
WooCommerce 7.0 ou supérieur (testé jusqu’à 9.4)
PHP 8.0 ou supérieur
Une clé API chez l’un des trois providers : OpenAI, Voyage AI ou Cohere
WP-Cron fonctionnel (ou un cron système qui appelle wp-cron.php)

Aucune extension MySQL particulière, aucun serveur Redis ni Elasticsearch requis. Le calcul de similarité s’effectue en PHP pur, ce qui rend le plugin compatible avec tout hébergement mutualisé standard.

Installation

Dans votre back-office WordPress, allez dans Extensions → Ajouter → Téléverser une extension.
Sélectionnez le fichier vector-search-native.zip puis cliquez sur Installer maintenant.
Cliquez sur Activer. Le plugin crée automatiquement ses deux tables (wp_vsn_embeddings et wp_vsn_index_queue) et planifie sa tâche cron.
Un nouveau menu Vector Search apparaît sous WooCommerce.

Configuration du provider

Rendez-vous dans WooCommerce → Vector Search. La section « Embedding provider » liste les trois providers disponibles. Sélectionnez celui de votre choix dans le menu déroulant « Active provider », collez votre clé API dans le bloc correspondant, choisissez un modèle puis cliquez sur Test connection. Un message vert confirmant la dimension du vecteur (par exemple « Connection OK. Embedding dimension: 1536 ») valide la configuration.

Quel modèle choisir

OpenAI text-embedding-3-small (1536d) : le meilleur rapport qualité-prix, recommandé par défaut.
OpenAI text-embedding-3-large (3072d) : qualité maximale, environ 6 fois plus cher.
Voyage voyage-3 (1024d) : excellent retrieval, entraîné pour la recherche.
Cohere embed-multilingual-v3.0 (1024d) : le choix pour les catalogues multilingues FR/EN/ES/DE/IT.

Changer de provider ou de modèle rend les vecteurs existants incompatibles (dimensions différentes). Après un changement, lancez systématiquement un réindex complet.

Indexation initiale

Toujours sur la page Vector Search, cliquez sur Queue all products for reindex. Tous les produits publiés entrent dans la file d’attente.
Cliquez sur Auto-process until done. Le plugin traite la file par lots (25 produits par défaut) jusqu’à épuisement, en direct depuis votre navigateur.
Les compteurs « Indexed », « Queued » et « Stuck » se mettent à jour en temps réel.

Vous pouvez aussi laisser WP-Cron faire le travail en arrière-plan : la tâche vsn_process_queue tourne selon l’intervalle configuré (5 minutes par défaut) et vide progressivement la file.

Coût indicatif : environ 0,02 € pour 1 000 produits avec OpenAI text-embedding-3-small. L’indexation incrémentale par hash SHA-256 garantit qu’un produit inchangé ne déclenche jamais d’appel API, même si la file le repasse en revue.

Fonctionnement de la recherche

Une fois l’indexation terminée, la recherche produit WooCommerce (frontend et widgets standards) est automatiquement interceptée. Le plugin :

Convertit la requête du visiteur en vecteur via le provider actif (avec cache de 10 minutes).
Calcule la similarité cosinus contre tous les vecteurs produits stockés.
Retient les produits dépassant le seuil de similarité minimum (0,30 par défaut) dans la limite du nombre maximum de candidats (200 par défaut).
Injecte les IDs triés par pertinence dans la requête WordPress.

Si le nombre de résultats est inférieur au seuil de fallback (3 par défaut), le plugin s’efface et laisse la recherche mots-clés WooCommerce native s’exécuter normalement. Vos visiteurs ne voient jamais une page vide à cause d’un problème côté IA.

Réglages avancés

Contenu indexé

La section « Content to index » permet de choisir les champs inclus dans l’embedding : description courte, description longue, SKU, catégories, étiquettes et attributs. Le titre du produit est toujours indexé. Réduire les champs peut affiner la pertinence sur certains catalogues ; les inclure tous maximise le rappel.

Seuils et candidats

Minimum similarity (0,0 – 1,0) : en dessous de ce score cosinus, un produit n’est pas retenu. Montez vers 0,4 – 0,5 pour filtrer agressivement, descendez vers 0,2 pour élargir.
Max candidates : nombre de produits retournés à WooCommerce après tri. La pagination s’applique ensuite normalement.
Fallback threshold : nombre minimal de résultats vectoriels avant de basculer sur les mots-clés.

File d’attente et cron

Cron interval : fréquence de traitement de la file (1, 5, 15 minutes ou horaire).
Batch size (1 – 100) : produits traités par tick. Augmentez prudemment pour éviter les rate limits provider.
Chaque produit en échec est retenté jusqu’à 5 fois, avec le dernier message d’erreur conservé en base. Le compteur « Stuck » signale les produits ayant épuisé leurs tentatives.

REST API

Cinq endpoints sont exposés sous /wp-json/vsn/v1/, tous réservés aux utilisateurs disposant de la capacité manage_woocommerce :

POST /reindex — met tous les produits en file d’attente.
POST /process — traite un lot immédiatement.
GET /stats — retourne les compteurs (total, indexés, en file, bloqués).
POST /test — teste une clé API (paramètres : provider, api_key, model).
POST /clear — vide entièrement l’index des embeddings.

Exemple de réindex complet depuis un script de déploiement :

curl -X POST https://votre-boutique.fr/wp-json/vsn/v1/reindex 
  -u admin:MOT_DE_PASSE_APPLICATION

Hooks développeurs

vsn_indexed_text

Personnalise le texte envoyé au provider pour chaque produit. Idéal pour injecter des champs ACF ou des méta métier :

add_filter( 'vsn_indexed_text', function ( $text, $product ) {
    $matiere = get_post_meta( $product->get_id(), 'matiere', true );
    if ( $matiere ) {
        $text .= "nMatière : " . $matiere;
    }
    return $text;
}, 10, 2 );

vsn_should_engage

Contrôle finement quand la recherche vectorielle s’active :

// Désactiver la recherche vectorielle pour les requêtes d'un seul mot.
add_filter( 'vsn_should_engage', function ( $engage, $query ) {
    $s = (string) $query->get( 's' );
    if ( str_word_count( $s ) < 2 ) {
        return false;
    }
    return $engage;
}, 10, 2 );

Boutiques multilingues

Avec WPML ou Polylang, chaque traduction est un produit WordPress distinct : chacune est donc embeddée séparément, dans sa propre langue. Deux recommandations :

Utilisez un modèle multilingue (Cohere embed-multilingual-v3.0 ou Voyage voyage-multilingual-2) pour que les requêtes et les fiches soient projetées dans le même espace sémantique quelle que soit la langue.
Après l'ajout d'une nouvelle langue ou une campagne de traduction massive, lancez un réindex complet pour couvrir les nouveaux produits.

Dépannage

Des produits restent en « Stuck »

Un produit bascule en « Stuck » après 5 échecs consécutifs. Les causes fréquentes : clé API invalide ou expirée, rate limit provider, ou timeout réseau. Vérifiez votre clé avec Test connection, corrigez, puis cliquez sur Queue all products for reindex — cela remet les compteurs de tentatives à zéro.

La recherche semble inchangée

Vérifiez que la case Enabled est cochée dans les réglages généraux.
Vérifiez que le compteur « Indexed » correspond bien à votre nombre de produits.
Si vous utilisez un plugin de recherche tiers (FiboSearch, SearchWP…), celui-ci peut court-circuiter la requête WordPress standard avant l'interception. Désactivez-le ou contactez-nous pour un ajustement d'intégration.

La file ne se vide pas toute seule

WP-Cron ne se déclenche que lors des visites. Sur un site à faible trafic, configurez un cron système :

*/5 * * * * curl -s https://votre-boutique.fr/wp-cron.php > /dev/null 2>&1

Désinstallation

La désactivation du plugin suspend le cron mais conserve les données. La suppression du plugin depuis la page Extensions déclenche uninstall.php, qui supprime les deux tables MySQL, l'option de réglages et les tâches planifiées. Aucun résidu en base.

FAQ

Puis-je utiliser le plugin sans clé API ?

Non — la recherche sémantique nécessite un provider. Sans clé, le plugin reste inerte et la recherche native WooCommerce continue de fonctionner normalement.

Les clés API sont-elles exposées côté client ?

Non. Tous les appels aux providers s'effectuent côté serveur, depuis PHP. La clé n'apparaît jamais dans le HTML ni dans les requêtes du navigateur.

Quel volume de catalogue est supporté ?

Le scan cosinus en PHP reste très performant jusqu'à environ 50 000 produits sur un hébergement mutualisé standard. Au-delà, contactez-nous pour discuter d'une intégration avec un index approximate-nearest-neighbor dédié.

Cette page vous a-t-elle été utile ?

Toujours bloqué ? Contactez le support

PrestaShop

WordPress / WooCommerce

Shopware 6