Optimisation RAG de la documentation

Cette doc est lue par deux publics : un humain (rendu HTML du site, cartouche strippé et réaffiché en encart) et un RAG (cœur d'ingestion → chunks → embeddings → récupération, cf. specs/ia-coeur.md). Ce fichier fait autorité sur les règles qui concilient les deux : lisibilité humaine et digérabilité machine.

Objectif de fond : la récupération se fait par similarité sémantique sur des chunks. Un bon chunk est auto-portant (compréhensible hors de son document) et riche en mots signifiants. Toute la convention découle de ce principe.

1. Règles côté documentation (doc-side) — applicables par nous

Statut : déjà tenues sur le corpus (vérifié 2026-06-04), sauf 1.4 et 1.5 à généraliser.

1.1 Cartouche complet sur chaque document (5 champs, cf. competences.md et la section « Cartouche » de DOCUMENTATION.md). Le summary est une phrase BLUF dense en mots-clés : c'est l'ancre de récupération la plus forte du document.

1.2 Un sujet par document, titres de section signifiants dans leur famille. On n'uniformise pas la structure de corps entre familles (specs ≠ guides ≠ tutos ≠ agents) : l'hétérogénéité de ton est légitime. Les titres récurrents de gabarit (## Pour aller plus loin, ## Objectif, ## Exemple) restent — leur désambiguïsation est du ressort de l'ingestion (§ 2.1), pas d'une réécriture.

1.3 Accents et UTF-8 : prose toujours accentuée, pas de BOM (casse le front-matter et pollue le premier embedding). Vérifié : 0 BOM, 0 mojibake sur le corpus.

1.4 Phrase d'attaque auto-portante : le premier paragraphe sous le # H1 rappelle le sujet et le contexte en toutes lettres (ex. « Objectif : configurer les sous-domaines OVH… »), sans dépendre du titre. C'est le chunk le plus souvent récupéré ; il ne doit pas commencer par « Ce guide… » sans nommer le sujet.

1.5 Sigles centraux expansés au premier usage (NDD → « nom de domaine (NDD) »). On expanse inline les sigles porteurs du sujet du document (un doc sur le mail expanse DKIM / SPF / DMARC) ; les sigles incidents s'appuient sur le glossaire.md, référence transverse tenue exhaustive. Objectif : la forme longue — souvent celle de la requête utilisateur — apparaît au moins une fois là où elle compte, sans churn sur tout le corpus.

2. Contrat d'ingestion (RAG-side) — à porter par codexia

Le cœur RAG (telaria/rag-bundle) découpe déjà par structure de titres et chaque chunk porte ses métadonnées Chunk{documentPath, documentTitle, section, anchor, position, content, tokenCount, contentHash} (cf. ia-coeur.md § 3.1–3.2). Les points ci-dessous augmentent la qualité de récupération à partir de cet existant.

2.1 Embedding contextuel (priorité haute) : embedder le titre du document + le chemin de section en préfixe du content, pas seulement les stocker en métadonnées. Sinon deux chunks ## Pour aller plus loin de fiches différentes produisent des vecteurs quasi identiques. Forme suggérée du texte embeddé : "<documentTitle> › <section>\n\n<content>". Le content affiché à l'utilisateur reste inchangé (le préfixe ne sert qu'au calcul du vecteur).

2.2 Cartouche comme signal, sans pollution :

• injecter le summary du cartouche dans le chunk de tête du document (au texte embeddé) — il condense le sujet et améliore le rappel ;
• exposer skills, status (et updated) comme métadonnée filtrable (facette de recherche), hors embeddings — conformément à la décision « filtrable par le RAG sans polluer les embeddings ». Ne pas réinjecter ces champs dans chaque chunk.

2.3 Strip du cartouche du corps embeddé : le bloc front-matter brut (clés YAML) ne doit pas être embeddé tel quel (bruit). Seules ses valeurs utiles sont réinjectées via 2.1/2.2. Cohérent avec le viewer qui strippe déjà le cartouche à l'affichage.

2.4 Granularité : conserver le découpage guidé par les titres avec chevauchement léger (ia-coeur.md § 3.2). Éviter les chunks < ~50 tokens (titres orphelins) en les fusionnant avec la section suivante.

Modèle de génération : la digestion/synthèse RAG vise Haiku ou Sonnet (Opus réservé à l'usage perso). Les règles ci-dessus réduisent le besoin de contexte au moment de la génération, donc le coût — un chunk auto-portant se suffit à un modèle plus léger.

3. État & coordination

• § 1 (doc-side) : règles 1.1–1.3 tenues. 1.4 — audit 2026-06-04 : corpus déjà conforme (le sujet est nommé dans la phrase d'attaque) ; 1 cas corrigé (pilotage/veille/README.md). 1.5 — glossaire complété (CLI / NDD / RAG → exhaustif)
  • sigles centraux expansés dans la famille nouveau-domaine. Les deux règles sont désormais des critères de relecture pour tout nouveau doc, pas une passe de masse.
• § 2 (RAG-side) : acté par codexia (Lead dev, RAG owner) le 2026-06-05 (inbox codexia #44). Arbitrages : 2.1 embedding contextuel "<documentTitle> › <section>\n\n<content>" adopté (le content affiché reste inchangé) ; 2.2 summary dans le chunk de tête (embeddé)
  • skills/status/updated en facette filtrable hors-vecteur (nouvelles colonnes + filtre retrieval) — cadré comme dev scopé ; 2.3 strip front-matter déjà en place ; 2.4 fusion des chunks orphelins (< ~50 tokens) adoptée. L'implé est portée par codexia côté rag-bundle ; ce fichier passe status: validé côté décisions.
• Référence d'implémentation : specs/ia-coeur.md (pipeline, modèle Chunk, contrat d'interface).