Lot 0 — Cœur RAG : spécification

Spécification détaillée du socle commun (« cœur ») de l'initiative Vitrine IA : ingestion → découpage → embeddings → index vectoriel → récupération. Rattaché au cadre : specs/ia-vitrine.md. Statut : spec alignée sur l'implémentation (telaria/rag-bundle v0.1.3).> État d'implémentation : L0 cœur RAG validé en prod sur VPS le 2026-05-26 (181 documents / 2430 chunks indexés, recherche fonctionnelle).

1. Objectif et périmètre

Le cœur est la fondation réutilisée par les trois surfaces (MCP, chatbot, veille). Il transforme une arborescence de documents Markdown en une base interrogeable par similarité sémantique.

• Headless par conception : pas d'interface utilisateur propre. Il s'expose via une CLI (commandes Symfony) et une API de service (pour les surfaces).
• Réutilisable : packagé en bundle Symfony, avec une source paramétrable (racine de documents) → exploitable pour Codexia comme pour d'autres projets.
• Indépendant du LLM : le cœur fait du retrieval. La génération (Claude) est consommée par les surfaces, pas par le cœur.

Périmètre L0 : ingestion de la doc Codexia, découpage, embeddings (via microservice Python), index sqlite-vec, service de récupération, CLI, UI de diagnostic minimale. Hors L0 : génération LLM, UI de chat (L2), outils MCP (L1), sources externes / veille (L3), ré-indexation temps réel.

2. Vue d'ensemble du pipeline

Indexation (hors-ligne, batch)
  .md (source) ──▶ Ingestion ──▶ Découpage ──▶ Embeddings ──▶ Index
                   (walk+filtre)  (chunks +     (microservice   (sqlite-vec)
                                   métadonnées)  Python)

Requête (à la demande)
  question ──▶ Embeddings(query) ──▶ kNN (index) ──▶ top-k chunks + scores + sources
                                                      │
                                                      └─▶ contexte fourni aux surfaces

3. Composants

3.1 Ingestion

• Parcours récursif d'une racine source (paramétrable ; par défaut, le dépôt doc).
• Filtres obligatoires : respecter .aiignore → exclure SCRATCH.md et inputs/legacy/ de l'indexation. Exclure les fichiers binaires/ressources non textuelles.
• Lecture UTF-8 ; extraction du front-matter et de la structure de titres (H1/H2/H3).

3.2 Découpage (chunking)

• Découpage guidé par la structure (sections de titres), borné par une taille cible (en tokens) avec chevauchement léger pour ne pas couper le sens.
• Chaque chunk porte ses métadonnées : chemin du fichier, titre du document, section (ancre), position, empreinte (hash) pour la ré-indexation incrémentale.

3.3 Embeddings (microservice Python)

• Vectorisation déléguée à un microservice Python (FastAPI + sentence-transformers), modèle intfloat/multilingual-e5-base.
• Convention e5 : préfixes query: / passage: gérés côté service selon le type demandé.
• Appels par lots à l'indexation ; appel unitaire rapide à la requête.

3.4 Index vectoriel (SQLite + sqlite-vec)

• Stockage embarqué : SQLite + extension sqlite-vec (table virtuelle de vecteurs + recherche kNN).
• upsert par chunk ; ré-indexation incrémentale par comparaison de hash (ne ré-embedde que ce qui a changé).

Décision (figée) & rationale — pourquoi pas la base MySQL existante :

• L'index vectoriel est un artefact dérivé et reconstructible (régénérable depuis les .md), pas de la donnée métier : on le découple de la base métier, comme on le ferait d'un index de recherche. MySQL reste la base métier.
• MySQL 8.4 LTS n'a aucun support vectoriel natif : le type VECTOR et les fonctions de distance sont apparus en MySQL 9.0 (branche Innovation, pas LTS). L'utiliser imposerait un calcul de similarité en force brute côté PHP — viable à petite échelle, mais artisanal.
• sqlite-vec fournit le kNN prêt à l'emploi, sans serveur supplémentaire, et sans contraindre la version de MySQL.
• Alternatives écartées : pgvector (impose un serveur PostgreSQL) ; MySQL 9.x VECTOR (release Innovation, à rebours du choix LTS « technologies éprouvées »).

Prérequis serveur & chargement : sqlite-vec est une extension chargeable (non incluse par défaut) → à installer sur le serveur (binaire pré-compilé ou compilation). Le bundle la charge côté PHP via Pdo\Sqlite::loadExtension() (PHP 8.5), chemin configurable (RAG_SQLITE_VEC_PATH, sinon le nom vec0) ; chargement paresseux (exception claire si indisponible, sans bloquer le boot).

⚠️ Nuance importante (corrige une approximation antérieure) : la recherche kNN (table virtuelle vec0) exige l'extension chargée dans PHP — c'est intrinsèque à sqlite-vec. Le repli « indexation par l'outillage » (CLI/Python) ne couvre donc que l'écriture de l'index ; si PHP ne peut pas charger l'extension, il faut aussi déporter la recherche hors PHP (p. ex. vers le service Python) — sinon l'application ne peut pas interroger l'index. À tester en priorité sur le VPS (open_basedir, build PHP), et à répercuter dans guides/deployment.md.

✅ Validé sur VPS le 2026-05-26 : Pdo\Sqlite::loadExtension() fonctionne sur le build PHP 8.4 du VPS — le chemin nominal (recherche en PHP) est le cas principal. Le repli « déport hors PHP » devient un plan B théorique, à n'invoquer que si un autre hôte bloque le chargement.

3.5 Service de récupération (retrieval)

• Entrée : une requête en langage naturel (+ k, filtres optionnels par chemin/section).
• Sortie : top-k chunks avec score de similarité et source (chemin, section, ancre).
• Évolution prévue (hors L0) : retrieval hybride (dense + lexical) — d'où l'option bge-m3 au cadre.

4. Contrats d'interface

4.1 Microservice Python (HTTP)

GET  /health                  → { "status": "ok", "model": "...", "dim": 768 }
POST /embed                    → vectorise un lot
  requête : { "type": "query"|"passage", "texts": ["..."] }
  réponse : { "model": "...", "dim": 768, "vectors": [[...], ...] }

• Validation stricte des entrées : type hors {query,passage}, ou texts vide → HTTP 422 (la forme des réponses 200 est inchangée). Pas de fallback silencieux (qui produirait un mauvais préfixe e5). Le client (cœur RAG) traite un 422 comme une erreur d'entrée.
• Service stateless, déployable séparément ; URL injectée en configuration côté Symfony.

4.2 Côté Symfony (bundle Telaria\Rag)

Signatures réelles, figées en v0.1.x :

• ChunkerInterface::chunk(Document $document): Chunk[]
• EmbeddingClientInterface::embed(string $type, string[] $texts): float[][] + health(): array{status,model,dim}
• VectorStoreInterface : initialize(): void ; upsertDocument(Document $doc, Chunk[] $chunks, float[][] $vectors): void (remplacement transactionnel du document + ses chunks/vecteurs) ; documentHash(string $path): ?string (réindexation incrémentale au niveau document) ; search(float[] $vector, int $k): Hit[] ; stats(): array{documents,chunks,last_indexed_at}
• RetrievalService::retrieve(string $query, ?int $k = null): Hit[]
• IngestionService::ingest(?string $sourceRoot = null, bool $incremental = true): IngestReport
• Modèles : Chunk{documentPath, documentTitle, section, anchor, position, content, tokenCount, contentHash} ; Hit{chunk, score} avec score = 1 - distance_cosinus (∈ ~[0,1]).

5. Modèle de données (schéma SQLite)

• document : id, path, title, content_hash, indexed_at.
• chunk : id, document_id, section, anchor, position, content, token_count, content_hash.
• chunk_vector : table virtuelle sqlite-vec (chunk_id ↔ vecteur, dimension du modèle).
• ingest_run : id, source_root, started_at, finished_at, docs, chunks, status (traçabilité).

6. Interface (réponse à la question « interface graphique »)

Le cœur étant headless, son interface de pilotage est double :

6.1 CLI (interface primaire, L0)

• app:rag:ingest [--source=PATH] [--full] : indexe une racine (--full = réindexation complète ; par défaut incrémentale par content_hash).
• app:rag:reindex : ré-indexation incrémentale (par hash).
• app:rag:search "question" [--k=5] : teste une requête, affiche chunks + scores + sources.
• app:rag:stats : nb documents/chunks, date de dernière indexation, santé du microservice.

6.2 UI de diagnostic — ✅ implémentée (/admin/rag)

Implémentée dans telaria : route /admin/rag (ROLE_ADMIN), dégrade proprement (bannière) si sqlite-vec/microservice absents. Elle rend visible le travail « invisible » du retrieval — fort atout vitrine :

• Statistiques d'index (documents, chunks, dernière indexation, état du microservice).
• Formulaire de requête de test → affichage des passages récupérés avec score de similarité et lien vers la source.
• Rendu serveur, sans JavaScript requis (honore l'amélioration progressive), derrière ROLE_ADMIN.
• Aligné sur le design system existant (specs/design.md, specs/ui.md, specs/bootstrap.md) et conforme RGAA 4.1 AA.

6.3 Où vit la « vraie » interface utilisateur

• Chatbot (L2) : c'est l'interface end-user riche (Q/R + citations). Même design system, RGAA AA, amélioration progressive (le streaming ajoute du JS, mais doit dégrader proprement).
• MCP (L1) : pas d'UI à construire — l'« interface » est le client agent (Claude Desktop, Cursor…) ; la démo se fait côté client.

7. Configuration

Réglages dans config/packages/telaria_rag.yaml (telaria_rag.*) :

• source_root, included_paths, excluded_paths (exclut SCRATCH.md, inputs/legacy/).
• embedding.{service_url, model, dimension, timeout, batch_size} — défauts : intfloat/multilingual-e5-base, dimension: 768.
• chunk.{size, overlap} — défauts 512 / 64.
• retrieval.k — défaut 5.
• store.{database_path, extension_path}.

Variables d'environnement (hôte) — surchargent les chemins/URL sensibles :

8. Gouvernance et garde-fous

• Respect de .aiignore : SCRATCH.md et inputs/legacy/ ne sont jamais indexés par défaut (cohérent avec la confidentialité du bac à sable).
• Sources traçables : chaque chunk conserve sa provenance → toute réponse de surface pourra citer ses sources (exigence AGENTS.md).
• Pas de données personnelles dans la doc Codexia (risque RGPD faible) ; à réévaluer si des sources externes en introduisent.

9. Contraintes et performance

• VPS CPU-only : l'indexation (coûteuse) tourne en batch / hors-ligne ; l'embedding d'une requête est léger à la demande.
• Modèle e5-base choisi pour rester fluide sur CPU (cf. décision du cadre).
• Empreinte mémoire du microservice à surveiller ; un seul modèle chargé.

10. Tests unitaires (cas concrets)

Ingestion

• Une racine de fixtures est parcourue ; les fichiers non-Markdown sont ignorés.
• SCRATCH.md et inputs/legacy/ ne sont jamais ingérés (par défaut).
• Les included_paths / excluded_paths de la configuration sont respectés.
• Le front-matter et la hiérarchie de titres (H1/H2/H3) sont extraits.

Découpage (chunking)

• Un document est découpé selon sa structure, en respectant size et overlap.
• Chaque chunk porte ses métadonnées : path, section, anchor, position, content_hash.
• Un document plus court que size produit un seul chunk.
• Une modification du contenu change le content_hash (base de la réindexation incrémentale).

Client d'embeddings (microservice mocké)

• L'appel envoie {type, texts} à /embed ; les vecteurs de la réponse sont retournés tels quels.
• Une entrée invalide (type hors {query,passage} ou texts vide) → le service renvoie 422 ; le client propage l'erreur (pas d'embedding silencieux).
• Une erreur/timeout du service est propagée proprement (l'index n'est pas corrompu).

Index vectoriel (VectorStoreInterface, impl. sqlite-vec)

• upsert puis search renvoie les chunks les plus proches, triés par score (cosinus).
• La réindexation incrémentale ne ré-embedde pas un chunk dont le content_hash est inchangé.
• Un index vide renvoie un résultat vide (sans erreur).

Récupération (RetrievalService)

• Une requête est vectorisée en type=query, puis renvoie le top-k avec score et source (path, section, anchor).
• La borne k est respectée.

Gouvernance (intégration)

• ingest → search sur fixtures : un passage attendu figure dans le top-k.
• Vérification de bout en bout que SCRATCH.md et inputs/legacy/ n'apparaissent jamais dans les résultats.

11. Production documentaire d'accompagnement (doctrine)

Ce lot introduit des concepts qui doivent être expliqués (cf. cadre §11) :

Tous produits : fiche 2.6 Embeddings, tuto microservice Python, tuto sqlite-vec, tuto RAG bout-en-bout.

12. Décisions (tranchées avec l'instance codexia)

1. Découpage : size=512 / overlap=64 tokens, configurables (à calibrer sur la doc FR ; estimateur de tokens heuristique, pas de tokenizer natif PHP).
2. Métrique & dimension : cosinus, dimension 768 (multilingual-e5-base).
3. Frontière bundle : un seul bundle « cœur » (Telaria\Rag) ; le store est un service interchangeable derrière VectorStoreInterface (on scindera si un autre store émerge).
4. Chargement sqlite-vec : côté PHP via Pdo\Sqlite::loadExtension(RAG_SQLITE_VEC_PATH ?? 'vec0'), paresseux (cf. nuance §3.4 : la recherche exige l'extension en PHP) — à valider sur le VPS. Packaging du microservice : du ressort de tlr-embeddings.

Tranché : l'UI de diagnostic (§6.2) est incluse dans le périmètre L0. Implémentation : bundle telaria/rag-bundle (Telaria\Rag, tag v0.1.3 signé — bug PDO::PARAM_INT pour rowid/k sur vec0 corrigé en v0.1.3), consommé par telaria en ^0.1 ; UI /admin/rag (ROLE_ADMIN). Validation bout-en-bout sur VPS le 2026-05-26 : 181 documents / 2430 chunks indexés, top-1 pertinent (cosinus ~0.86) sur requêtes test.

Documents liés

• Cadre : specs/ia-vitrine.md
• Veille « IA dans Codexia » (embeddings, vector store) : pilotage/veille/README.md
• Fiche RAG (prompt engineering avancé) : agents/4-interagir-avec-l-ia/4-3-le-prompt-engineering-niveau-avance.md
• Modèles de déploiement : agents/2-fondements-techniques/2-5-les-modeles-de-deploiement.md

Implémentation

Historique des décisions