Tuto — RAG de bout en bout

Public visé : développeur qui veut relier toutes les briques du RAG en un flux qui marche. Objectif : assembler ingestion → embeddings → index → récupération → génération pour répondre à une question avec des sources. C'est la mise en œuvre conjointe du cœur (specs/ia-coeur.md) et du chatbot (specs/ia-chatbot.md).

Concept : Embeddings et recherche sémantique et RAG (fiche 4.3).

Vue d'ensemble

INDEXATION (une fois, hors-ligne)
  doc .md → découpage → embeddings (passage) → index sqlite-vec

REQUÊTE (à chaque question)
  question → embedding (query) → kNN → passages + sources
           → prompt (system + passages + question) → Claude → réponse + citations

Étape 1 — Indexer la doc

Voir les tutos dédiés :

• découpage + métadonnées : spec L0 §3.2 ;
• vecteurs : microservice d'embeddings Python (appel type=passage) ;
• stockage : index vectoriel sqlite-vec.

À la fin, on a un fichier index.sqlite avec les passages et leurs vecteurs.

Étape 2 — Récupérer (retrieval)

1. Embedder la question (type=query) via le microservice.
2. Recherche kNN dans sqlite-vec → top-k chunk_id + distance.
3. Joindre la table chunk → passages + sources (path, section).

C'est le rôle du RetrievalService du cœur. Astuce qualité : filtrer les passages dont le score est sous un seuil (sinon on injecte du bruit).

Étape 3 — Construire le prompt

[system]
Tu es un assistant documentaire. Réponds UNIQUEMENT à partir du contexte.
Cite tes sources. Si le contexte ne contient pas la réponse, dis-le.

[contexte]
Passage 1 (source: specs/ia-coeur.md#retrieval) : "..."
Passage 2 (source: agents/.../2-6...md) : "..."

[user]
{question de l'utilisateur}

Le bloc system + contexte est stable → candidat au prompt caching pour réduire le coût.

Étape 4 — Générer avec Claude

• Appeler l'API avec température basse (factualité) et une borne de tokens.
• Récupérer la réponse et conserver la liste des sources des passages injectés.

Étape 5 — Restituer avec citations

La réponse est affichée avec ses sources cliquables (chemin + section). Une question hors doc → message « pas dans la documentation » (garde-fou, cf. fiche 6.1).

Erreurs fréquentes

• Chunks trop gros → vecteurs « flous », mauvais rappel. Calibrer taille/chevauchement.
• Pas de seuil de score → l'IA reçoit des passages hors-sujet et peut broder.
• Oublier les préfixes e5 (query: / passage:) → qualité dégradée.
• Citer sans vérifier → toujours restituer les sources réellement utilisées.

Pour aller plus loin

• Cœur : specs/ia-coeur.md — Chatbot : specs/ia-chatbot.md
• Exposer la même recherche à un agent : serveur MCP en Symfony