Comment préparer une base de documentation efficace pour un assistant IA

Beaucoup de développeurs jettent toute leur documentation dans une base vectorielle sans tri préalable. Résultat : l’IA perd du temps à analyser des pages inutiles et les réponses perdent en précision.

Le vrai problème : le bruit structurel

Sur la plupart des sites de docs, une partie importante du contenu sert surtout à la navigation ou aux obligations légales. Ce sont les pages d’accueil, les listes de liens, les mentions légales ou les historiques de versions. Ces pages n’apportent aucune information technique, mais elles polluent les embeddings et ralentissent les recherches.

Une approche en deux temps

Plutôt que de tout traiter de la même façon, on peut filtrer en deux passes.

Premier tri automatique

On commence par des règles simples sur les URLs et la structure des pages. On repère facilement :

• Les pages légales (/legal/, /privacy, /terms)
• Les hubs de navigation avec peu de texte
• Les changelogs et listes de références

Ce premier filtre tourne localement et élimine souvent la moitié des pages sans aucun coût.

Classification par LLM local

Pour les pages restantes, on envoie un extrait léger à un modèle local : l’URL, le titre, les 200 premiers mots et la hiérarchie des titres. Le modèle classe ensuite le contenu selon la grille Diátaxis (conceptuel, tutoriel, how-to, exemple, structurel). Seules les pages ambiguës passent par cette étape.

Découper intelligemment avant l’embedding

Les pages de documentation dépassent souvent la limite de tokens. Plutôt que de tronquer, on découpe au niveau des titres (H1, H2, H3) et on moyenne les embeddings obtenus. Cette méthode respecte la structure du document et évite de perdre le contexte des sections.

On utilise un modèle local de type sentence-transformer pour garder le contrôle et éviter les frais d’API.

Combiner liens explicites et similarité sémantique

Une fois le contenu propre, on construit un graphe de connaissances. Deux types de relations coexistent :

• Les liens hypertextes écrits par les auteurs (connexions explicites et fiables)
• Les liens sémantiques calculés par similarité cosinus entre embeddings (seuil recommandé : 0.75)

On limite le nombre de voisins par page pour éviter les hubs trop connectés, et on exclut les pages structurelles du calcul sémantique.

Stocker tout dans un SQLite unique

Le résultat final tient dans une seule base SQLite :

• Le markdown nettoyé
• Les classifications de pages
• Les vecteurs d’embedding
• Les arêtes du graphe avec leurs poids
• Les métadonnées

Cette base est portable, interrogeable en SQL et peut être filtrée facilement (« montre-moi seulement les tutoriels sur l’authentification »). L’agent IA peut aussi naviguer dans le graphe pour trouver des pages liées.

Pipeline complet

1. Crawler le site en respectant robots.txt
2. Convertir le HTML en markdown propre
3. Classifier les pages (règles puis LLM)
4. Générer les embeddings avec découpage par titres
5. Construire le graphe (liens + similarité)
6. Enregistrer dans SQLite

Pourquoi ça change tout

Un assistant IA bien nourri passe moins de temps sur le bruit et plus sur le contenu utile. Les requêtes sont plus rapides, les réponses plus pertinentes, et tout reste local. Cette méthode fonctionne aussi bien pour une petite documentation produit que pour un écosystème multi-produits.