Maillage interne intelligent : architecture d'un plugin WordPress piloté par l'IA et les embeddings

Le maillage interne reste l'un des leviers SEO les plus sous-exploités. Trop souvent géré à la main, il souffre d'oublis, de doublons et d'une vision en silo du contenu. Un projet récent présenté sur dev.to par NEXU WP propose une approche radicalement différente : piloter le maillage interne de WordPress par la sémantique, grâce aux embeddings vectoriels et à plusieurs fournisseurs d'IA. Décortiquons l'architecture technique de cette solution.

De la recherche par mots-clés à la compréhension sémantique

L'idée centrale est de construire une base de connaissance vectorielle du contenu du site. Plutôt que de comparer des chaînes de caractères, le plugin génère des embeddings (représentations vectorielles denses) pour chaque article ou page. Ces embeddings sont produits côté serveur, en tâche de fond, via plusieurs fournisseurs configurables : OpenAI, Anthropic Claude, Google Gemini, ou DeepSeek.

Ce choix multi-providers n'est pas anodin. Il permet de basculer d'un modèle à l'autre selon le rapport coût/qualité du moment, et d'éviter la dépendance à un unique fournisseur. C'est un pattern de résilience API à retenir dans tout projet qui consomme des services d'IA tiers.

Les vecteurs générés sont stockés dans PostgreSQL avec l'extension pgvector. Ce choix est pertinent : pgvector permet d'exécuter des recherches de similarité cosinus directement en SQL, sans infrastructure dédiée (pas besoin de Pinecone ou Weaviate pour un volume WordPress standard). La requête de suggestion se résume alors à trouver les N voisins les plus proches d'un vecteur cible — une opération native et indexée.

-- Exemple de recherche des contenus les plus proches
SELECT post_id, content_preview,
       1 - (embedding <=> $1::vector) AS similarity
FROM content_embeddings
ORDER BY embedding <=> $1::vector
LIMIT 10;

Traitement asynchrone : workers, queues et batch processing

Générer des embeddings pour des centaines d'articles ne peut pas se faire de manière synchrone sans bloquer l'interface ou dépasser les timeouts HTTP. Le plugin traite donc le corpus en batches asynchrones, un pattern directement comparable à ce que l'on implémente avec le Messenger Component de Symfony ou les jobs queued de Laravel.

Concrètement, cela implique :

• Une file de messages (queue) qui reçoit les tâches de génération d'embeddings.
• Des workers qui consomment ces tâches en arrière-plan, indépendamment du cycle requête/réponse de WordPress.
• Un scanner de liens existants qui s'exécute en parallèle pour cartographier le maillage actuel et éviter de suggérer des liens déjà présents.

Ce découplage est fondamental : l'indexation initiale d'un site de 500 articles peut prendre plusieurs minutes et plusieurs centaines de requêtes API. Sans queue, c'est inenvisageable en production.

Trade-offs coûts API vs self-hosting

Pour un site éditorial de taille moyenne (< 1 000 articles), le coût d'indexation via OpenAI text-embedding-3-small reste inférieur à quelques euros. Le vrai coût récurrent est la re-indexation lors des mises à jour de contenu : un webhook sur save_post suffit à déclencher la mise à jour ciblée d'un seul vecteur.

Visualisation et UX : le graphe de liens comme outil de pilotage

L'une des fonctionnalités les plus remarquables sur le plan de l'expérience développeur est le graphe visuel des liens internes, rendu avec D3.js. Chaque nœud représente un contenu, chaque arête un lien existant. Les suggestions apparaissent dans une couleur distincte avant d'être appliquées.

Ce type de visualisation transforme une donnée abstraite (la structure du site) en quelque chose d'actionnable :

• Identification immédiate des pages orphelines (nœuds isolés).
• Détection des clusters thématiques et des ponts faibles entre sections.
• Prévisualisation des suggestions avant application, avec score de pertinence et ancre proposée.

La fonctionnalité orphan rescue inverse la logique habituelle : au lieu de partir d'une page et chercher où la lier, elle part des pages à forte autorité pour redistribuer l'équité de liens vers les pages isolées. C'est une approche SEO-first bien pensée.

Checklist de mise en production

Avant de déployer une architecture similaire sur un projet PHP/Symfony ou WordPress, voici les points à valider :

• ✅ PostgreSQL + pgvector installé (version ≥ 0.5.0 recommandée pour les index HNSW).
• ✅ Worker process supervisé (Supervisor, systemd, ou équivalent) pour consommer la queue sans interruption.
• ✅ Rate limiting côté API : implémenter un back-off exponentiel sur les erreurs 429.
• ✅ Cache des embeddings : ne jamais re-générer un vecteur si le contenu n'a pas changé (hash MD5 du contenu suffisant).
• ✅ Seuil de similarité configurable : un seuil trop bas génère du bruit, trop haut manque des liens pertinents. Exposer ce paramètre dans l'interface.
• ✅ Système d'undo par batch : toute insertion en masse doit être réversible (log des modifications avec snapshot).
• ✅ Monitoring des coûts API : tracer le nombre de tokens consommés par batch et alerter si le coût dépasse un seuil.

Conclusion

Ce projet illustre parfaitement comment des primitives bien connues — queues, workers, stockage vectoriel, API d'IA — peuvent s'assembler pour automatiser une tâche éditorialement coûteuse. La beauté de l'approche réside dans sa portabilité : les mêmes patterns (embeddings + pgvector + batch processing) s'appliquent aussi bien dans un contexte Symfony/API Platform que dans un plugin WordPress.

Pour les projets MulerTech qui manipulent de grands volumes de contenu, c'est une architecture à garder en tête dès que la question du maillage interne ou de la recherche sémantique se pose.

Article inspiré du projet NEXU WP publié sur dev.to.