Table of Contents

🇬🇧 English version

Voir aussi : ADR-006 — Sous-système RAG · Système de mémoire · Sous-systèmes opt-in · Retour à l'index

Pipeline RAG

Sous-système Retrieval-Augmented Generation (src/rag/) : ingestion incrémentale avec validation de sécurité, pipeline de requête étagé (transform → retrieve → fuse → rerank → assemble → generate → groundedness) dont chaque étape est tracée, retrieval hybride BM25 + vectoriel, rerankers enfichables, graphe correctif CRAG construit sur le mode d'orchestration Graph maison, profils de qualité (fast / balanced / quality / adaptive / corrective), intégration crew YAML avec injection de connaissances citées, et harnais d'évaluation offline sous gate CI.

Vue d'ensemble

Un agent qui colle des documents entiers dans son prompt noie son contexte et ne peut rien citer. Le sous-système RAG précalcule et structure cette connaissance :

  • Ingestion : les documents sont chargés (fichiers, CSV, HTML, PDF, pages web), validés contre l'injection de prompt, découpés en chunks, embarqués sous forme d'embeddings et upsertés dans une collection du document store. Un manifeste par collection rend la ré-ingestion incrémentale — une source inchangée coûte zéro embedding.
  • Requête : une question traverse une séquence fixe d'étapes activables et revient sous forme de RagAnswer — texte généré avec des marqueurs de citation [n], les citations résolvant chaque marqueur vers son chunk source (score et offsets inclus), et la trace d'exécution complète de la passe.
  • Réglages de qualité : un seul bouton (Orkeon:Rag:Profile) sélectionne un preset ; chaque valeur peut ensuite être surchargée clé par clé via la configuration. Profil = preset, configuration = surcharge.

Trois surfaces de consommation partagent les mêmes pipelines : les outils agents (rag_search, rag_ingest, rag_eval dans Orkeon.Tools.Rag), les blocs YAML de crew rag: / knowledge:, et l'espace de noms rag.* du DSL de scripting.

Projets (ADR-006)

Projet Rôle Dépend de
Orkeon.Rag.Abstractions Contrats, DTOs, options (IRagPipeline, RagAnswer, RagOptions, RagProfilePresets…) Orkeon.Domain uniquement
Orkeon.Rag Implémentations : loaders, chunkers, validation, stores, retrieval, reranking, routage, évaluation, DI Application, Analysis.Abstractions (voir ADR-006)
Orkeon.Rag.Onnx Reranker cross-encoder ONNX opt-in (ms-marco-MiniLM-L-6-v2), AddOrkeonOnnxReranker() Orkeon.Rag (concret)
Orkeon.Rag.Onnx.Model Package compagnon embarquant les poids int8 du modèle — offline garanti —
Orkeon.Tools.Rag Outils agents rag_search / rag_ingest / rag_eval, AddOrkeonRagTools() Orkeon.Rag.Abstractions, Orkeon.Rag (concret — le couplage gardé par l'ADR-006), Tools.Abstractions, Analysis.Abstractions

Orkeon.Rag.Abstractions est un shared kernel secondaire (même statut que Orkeon.Analysis.Abstractions, ADR-003) : Orkeon.Application le référence pour les ports ; Orkeon.Infrastructure référence Orkeon.Rag uniquement comme câblage de composition DI.

Démarrage rapide

Le sous-système est opt-in — AddOrkeonInfrastructure() seul ne câble rien. Tout hôte runner bâti sur RunnerHost (orkeon run sous toutes ses formes, orkeon-host) fait lui-même les deux appels ci-dessous, et chaque binaire livré — orkeon, orkeon-host, le REPL orkeon-repl — ajoute le reranker ONNX ; un hôte qui construit son propre conteneur les fait :

services.AddOrkeonLocalEmbeddings();      // or any IEmbeddingProvider (local BGE: no API key)
services.AddOrkeonInfrastructure();       // semantic-first defaults for embeddings + chat
services.AddOrkeonRag(configuration);     // the subsystem (Orkeon.Rag.DependencyInjection)
services.AddOrkeonRagTools();             // optional: rag_search / rag_ingest / rag_eval tools
var ingestion = provider.GetRequiredService<IIngestionPipeline>();
await ingestion.IngestAsync(new IngestionRequest
{
    Collection = "product-kb",
    Sources = [new SourceDescriptor { Location = "/kb/faq.md" }],
});

var rag = provider.GetRequiredService<IRagPipeline>();
var answer = await rag.QueryAsync(new RagQuery
{
    Text = "How many days do customers have to request a refund?",
    Collection = "product-kb",
    TopN = 3,
});
// answer.Text        — generated text with [n] markers
// answer.Citations   — marker -> chunk id, source id, snippet, score, offsets
// answer.Trace       — stages executed, variants, route, verdicts

L'hôte doit fournir un IEmbeddingProvider et un IChatClient ; AddOrkeonInfrastructure() enregistre pour les deux des défauts semantic-first (ordre de résolution pour les embeddings : provider local/Analysis enregistré dans le conteneur → configuration Orkeon:Embeddings → échec explicite au premier usage, jamais en silence).

Quel modèle le sous-système interroge : le profil par défaut de l'hôte, sauf si Orkeon:Rag:LlmProfile nomme un autre de ses profils (Llm:Profiles:<nom>, via ILlmProfileRegistry). Alors la génération citée, les transformateurs de requête, le reranker listwise, l'évaluateur et le vérificateur d'ancrage du graphe correctif, le classifieur llm et le juge d'évaluation appellent tous ce profil — un seul profil pour tout le sous-système, quel que soit le profil RAG (Orkeon:Rag:Profile) d'une requête. Le client de chat du profil est résolu au premier appel RAG qui a besoin d'un modèle, jamais au simple chargement d'une crew ; RagLlm.EnsureProfileIsKnown, que l'hôte runner et le REPL appellent une fois le conteneur construit, ne vérifie que le nom et refuse un profil que l'hôte n'offre pas — liste blanche Orkeon:Host:LlmProfiles d'orkeon-host comprise — en listant les profils connus. orkeon eval rag --offline ignore la clé : le stub extractif répond à la place de tout modèle.

Démos exécutables, entièrement offline : rag/basic-ingestion, rag/hybrid-retrieval, rag/custom-reranker, rag/crew-yaml, et la variante scripting scripting/08-rag.ork.ts.

Extensions d'enregistrement

AddOrkeonRag(configuration) est le seul appel dont un hôte a besoin ; il compose les extensions plus étroites ci-dessous, toutes en TryAdd* (un enregistrement de l'hôte l'emporte toujours) et utilisables seules :

Extension Enregistre
AddOrkeonRag(configuration) Le sous-système entier : options, loaders, validation, document store + décorateur hybride, manifestes, les deux pipelines, le résolveur de profils, et toutes les extensions ci-dessous sauf le reranker ONNX et AddOrkeonEphemeralSearch
AddOrkeonQueryTransforms() QueryTransformerFactory avec none / multi-query / rag-fusion / hyde
AddOrkeonRagReranking() RerankerFactory avec none / llm / decision plus chaque IRerankerRegistrar
AddOrkeonQueryRouting(configuration) L'IQueryComplexityClassifier nommé par Orkeon:Rag:QueryRouting:Classifier
AddOrkeonHybridRetrieval(configuration, …) Le décorateur HybridSearchDocumentStore (BM25 + RRF) autour de l'IDocumentStore
AddOrkeonCorrectiveRag(configuration) IRetrievalEvaluator, IGroundednessChecker, CorrectiveRagPipeline (expérimental, ORKEXP003)
AddOrkeonRagWebFallback(configuration) L'IWebDocumentRetriever, uniquement quand Orkeon:Rag:WebFallback est activé et possède un Endpoint
AddOrkeonKnowledgeAugmentation() IKnowledgeContextAugmenter (pièces jointes knowledge: des agents)
AddOrkeonRagEvaluation() Chargeur de dataset, IRagEvaluator, rédacteur de rapport, IRagEvalHarness
AddOrkeonEphemeralSearch() IEphemeralCollectionSearch derrière les tools txt_search / mdx_search / pdf_search / directory_search — échoue à l'appel, pas à l'enregistrement, quand AddOrkeonRag est absent
AddOrkeonOnnxReranker(configure?) Orkeon.Rag.Onnx : le reranker onnx / cross-encoder
AddOrkeonRagTools() Orkeon.Tools.Rag : rag_search, rag_ingest, rag_eval

Un hôte qui appelle AddOrkeonRag n'appelle donc jamais lui-même les six extensions plus étroites (AddOrkeonQueryTransforms, AddOrkeonRagReranking, AddOrkeonQueryRouting, AddOrkeonHybridRetrieval, AddOrkeonKnowledgeAugmentation, AddOrkeonRagEvaluation) — elles sont idempotentes, un second appel est donc sans effet. On ne les appelle seules que pour composer une pile partielle à la main, p. ex. le harnais d'évaluation sur un IRagProfileResolver construit par l'hôte, ou une factory sans le reste du sous-système. Deux règles d'ordre : AddOrkeonHybridRetrieval décore le dernier IDocumentStore enregistré et lève une exception s'il n'y en a encore aucun (elle lie aussi Orkeon:Rag:Retrieval:Hybrid, raccourci à plat = true compris) ; AddOrkeonKnowledgeAugmentation exige un IRagProfileResolver à la résolution (AddOrkeonRag l'enregistre) — sans l'augmenter, les pièces jointes knowledge: des agents ne sont pas injectées, et la factory de crew avertit pour chaque agent qui en déclare. Les extensions réellement opt-in, qu'AddOrkeonRag n'appelle pas, sont AddOrkeonOnnxReranker, AddOrkeonEphemeralSearch et AddOrkeonRagTools.

Contrats

Tous dans Orkeon.Rag.Abstractions (Interfaces/, Models/, Options/) :

Contrat Rôle
IRagPipeline Façade de requête : RagQuery → RagAnswer (citations + trace)
IRagRetrievalCapable Opt-in : la moitié retrieval seule (transform → retrieve → fuse → rerank → assemble), pas de génération, aucun appel LLM
IIngestionPipeline Façade d'ingestion : IngestionRequest → IngestionReport
IDocumentStore Upsert / recherche / suppression par source sur une collection nommée
IDocumentLoader Source → RagDocument (texte, CSV, HTML, PDF, page web)
IChunkingStrategy Document → tranches Chunk (recursive, sentence, structural, semantic)
IQueryTransformer Requête → textes de retrieval + un QueryTransformKind (voir plus bas)
IReranker Candidats → meilleurs topN, scorés par le reranker (cascade CandidateK → TopN)
IQueryComplexityClassifier Requête → QueryRoute (NoRetrieval / SingleShot / Iterative)
IRagProfileResolver Nom de profil → instance de pipeline mémoïsée
IKnowledgeContextAugmenter Pièces jointes de connaissance de l'agent → bloc de prompt cité
IRagCollectionsBootstrapper Bloc rag: de la crew → ingestion au kickoff
IRetrievalEvaluator, IGroundednessChecker Hooks correctifs (verdicts, contrôle d'hallucination — voir RAG correctif) ; expérimentaux, ORKEXP003
IRagEvaluator, IRagEvalHarness* Évaluation offline (métriques, datasets golden)
IEphemeralCollectionSearch Collections in-memory jetables (AddOrkeonEphemeralSearch)
IDocumentStoreCollectionProbe Capacité optionnelle du store (HasContentAsync) : permet à l'ingestion de repérer un manifeste qui a survécu à ses données — implémentée par MemoryProviderDocumentStore et relayée par le décorateur hybride

* le contrat du harnais et son runner vivent dans Orkeon.Rag.Evaluation ; le port d'évaluation est dans les abstractions.

Les composants nommés (chunkers, transformers, rerankers) se résolvent via des factories suivant le pattern MemoryProviderFactory : noms et alias comparés sans tenir compte de la casse, et un nom inconnu échoue toujours bruyamment avec la liste des noms connus — jamais de repli silencieux.

Pipeline de requête étagé

StagedRagPipeline (implémentation IRagPipeline par défaut) est une séquence fixe d'étapes activables, pilotée par RagOptions :

flowchart LR
    Q[RagQuery] --> T[transform]
    T --> R[retrieve]
    R --> F[fuse]
    F --> RR[rerank]
    RR --> A[assemble]
    A --> G[generate]
    G --> GR[groundedness]
    GR --> ANS[RagAnswer<br/>text + citations + trace]
# Étape Rôle Données de trace (extrait)
1 transform Le transformer nommé produit les textes de retrieval (none saute l'étape) mode, transformer, kind, variants, variant_1…variant_n
2 retrieve CandidateK candidats par texte de retrieval ; l'hybride est honoré par requête par les stores qui en sont capables candidates, top_k, mode, hybrid, variants
3 fuse Combinaison par kind des classements par texte + dédoublonnage par id de chunk, puis MMR opt-in method (rrf/union/dedup), in, out, mmr*
4 rerank Reranker nommé, cascade CandidateK → TopN (désactivé : troncature dans l'ordre du retrieval) reranker, candidates, kept
5 assemble Budget de tokens (≈ 4 caractères/token) + ordonnancement edges anti-Lost-in-the-Middle chunks, ordering, dropped_by_budget
6 generate Génération ancrée avec marqueurs [n] (system prompt anti-hallucination) model
7 groundedness Hook optionnel de vérification post-génération (IGroundednessChecker) grounded, score

Chaque étape ajoute un RagTraceStep à RagAnswer.Trace — durées, décomptes et noms des composants choisis sont toujours observables. Quand le retrieval ne rapporte aucun candidat, la génération est sautée et une réponse déterministe « sans contexte » est renvoyée (le pipeline ne laisse jamais le modèle répondre sans ancrage).

Transformers de requête par kind

Les transformers déclarent comment leurs textes de sortie se combinent à l'étape fuse (QueryTransformKind) :

Kind Intégré Sémantique
Union multi-query Un retrieval par texte (original + variantes) ; fusion par union des ids de chunk, scores d'origine du store conservés — le maximum l'emporte sur les doublons
Fusion rag-fusion Un retrieval par texte ; fusion des classements par Reciprocal Rank Fusion (même RrfK que l'étape hybride)
Replacement hyde Le ou les textes de substitution sont les sondes de retrieval à la place de la question — la génération et les citations utilisent toujours la question originale

Intégrés enregistrés par AddOrkeonRag : none, multi-query, rag-fusion, hyde. Ceux qui s'appuient sur un LLM résolvent le client de chat du sous-système (celui du profil par défaut, ou celui que nomme Orkeon:Rag:LlmProfile) paresseusement ; le parsing des variantes du LLM est tolérant, et une sortie vide dégrade vers la requête originale.

Assemblage anti-Lost-in-the-Middle

Avec Context.Ordering: edges (le défaut), les chunks classés r1 (meilleur) … rm sont disposés en r1, r3, r5, … depuis la tête et …, r6, r4, r2 pour fermer la queue — les deux chunks les plus forts occupent les extrémités où l'attention du LLM est la plus forte, les plus faibles se retrouvent au milieu. Les marqueurs de citation restent fondés sur le rang ([1] = meilleur chunk) quelle que soit la disposition. linear restaure l'ordre de rang simple.

Recherche hybride (BM25 + RRF)

AddOrkeonRag enveloppe toujours l'IDocumentStore enregistré — y compris celui enregistré par l'hôte — dans le décorateur HybridSearchDocumentStore, de sorte que l'ingestion alimente un index BM25 in-process par collection à côté du store vectoriel. Le fait qu'une recherche fusionne réellement se décide par requête (RetrievalQuery.Hybrid, positionné par les presets de profil), avec Orkeon:Rag:Retrieval:Hybrid:Enabled comme mode par défaut ; un défaut désactivé est un passthrough comportemental strict.

Provenance des scores (ScoredChunk.ScoreOrigin) :

  1. hybrid-native — le provider mémoire sous-jacent implémente IHybridSearchCapable (p. ex. LanceDB) : texte + vecteur fusionnés côté provider.
  2. rrf — chemin émulé : classement vectoriel interne + BM25 in-process, fusionnés par Reciprocal Rank Fusion. Les scores RRF sont des agrégats de rangs, pas des similarités.
  3. Origine interne (vector / local-cosine) — passthrough quand le versant lexical n'a rien à apporter.

L'index BM25 in-process ne couvre que les chunks upsertés via le décorateur dans le processus courant ; à l'échelle, préférer un provider à recherche hybride native — le décorateur bascule dessus automatiquement.

Diversification MMR

Opt-in (Orkeon:Rag:Retrieval:Mmr:Enabled), appliquée à l'étape fuse : la Maximal Marginal Relevance réordonne les candidats fusionnés en arbitrant pertinence contre redondance — chaque sélection maximise λ·pertinence − (1 − λ)·similarité-max-aux-déjà-sélectionnés (défaut λ = 0.7, penchant pertinence). Les embeddings des candidats ne sont pas recalculés : le repli sur la similarité lexicale (Jaccard) est le défaut honnête.

Reranking

L'étape rerank resserre CandidateK candidats (défaut 50) vers TopN (défaut 5) à l'aide d'un IReranker nommé :

Nom (alias) Implémentation Notes
none (noop) NoopReranker Troncature dans l'ordre du retrieval
llm (listwise) LlmListwiseReranker Un appel de chat listwise ; parsing tolérant (une réponse malformée conserve l'ordre du retrieval) ; l'alternative intégrée quand le package ONNX est absent — à sélectionner explicitement
onnx (cross-encoder) Orkeon.Rag.Onnx Cross-encoder ms-marco-MiniLM-L-6-v2, poids int8 embarqués, entièrement offline ; AddOrkeonOnnxReranker()
decision DecisionModelReranker Une requête au modèle de décision de l'hôte : la requête et tous les passages comme état, une question oui/non par passage, le score étant la probabilité du oui ; un passage est coupé à 4000 caractères. Exige un fournisseur de décision actif (AddOrkeonDecisionProvider), sinon sa résolution lève InvalidOperationException

Les hôtes contribuent des rerankers via IRerankerRegistrar — enregistrés dans la DI, appliqués à la construction du singleton RerankerFactory, ordre d'enregistrement indifférent (c'est ainsi que le package ONNX se branche ; voir examples/rag/custom-reranker pour un reranker fourni par l'hôte). La factory elle-même est enregistrée en TryAdd : une RerankerFactory enregistrée par l'hôte l'emporte purement et simplement.

Les chunks reclassés portent leur scoreur dans ScoredChunk.ScoreOrigin : cross-encoder (logits passés par une sigmoïde, dans (0, 1)), llm-rerank (rang décroissant normalisé, meilleur = 1.0) ou decision-rerank (la probabilité du oui).

Le reranker ONNX résout son modèle paresseusement au premier usage : le package compagnon Orkeon.Rag.Onnx.Model quand il est référencé (poids embarqués, offline garanti), sinon OnnxRerankerOptions.ModelPath + VocabPath (chemins virtuels VFS, tous deux requis), sinon une erreur explicite — le runtime ne télécharge jamais de poids (tools/download-reranker-model.sh dans le package les provisionne, avec vérification SHA-256). AddOrkeonOnnxReranker(o => …) règle aussi BatchSize (défaut 16) et MaxSequenceLength (défaut 512) ; ces options sont C# uniquement, liées à aucune section de configuration.

Profils

RagProfilePresets déplie un nom de profil en un RagOptions complet ; la section de configuration Orkeon:Rag surcharge ensuite chaque valeur individuellement.

fast (défaut) balanced quality adaptive corrective
Retrieval vectoriel seul, CandidateK = TopK hybride BM25 + RRF, CandidateK = 50 hybride, CandidateK = 100 routé (voir plus bas) hybride, nœud de graphe retrieve (voir CRAG)
Rerank désactivé cross-encoder ONNX 50 → 5 cross-encoder ONNX routé aucun — le graphe corrige en bouclant, pas en reclassant
Groundedness désactivé désactivé activé routé nœud de graphe natif check_groundedness
Requiert rien Orkeon.Rag.Onnx Orkeon.Rag.Onnx Orkeon.Rag.Onnx (sa route SingleShot exécute balanced) + classifieur + client de chat client de chat (grader/réécriture ; replis heuristiques sans lui)

fast est le défaut prêt à l'emploi parce que balanced exige le package ONNX opt-in — en faire le défaut ferait refuser le démarrage, en nommant onnx, de tout hôte se contentant d'un AddOrkeonRag() nu (les options effectives sont jugées au démarrage de l'hôte). On opte pour balanced avec une seule ligne de configuration.

IRagProfileResolver (ProfileRagPipelineResolver) mémoïse un pipeline par nom de profil ; le nom réservé default se résout vers l'IRagPipeline enregistré par l'hôte, de sorte qu'un pipeline fourni par l'hôte garde le dernier mot pour les requêtes sans profil. Les noms inconnus échouent bruyamment avec la liste des profils connus.

Routage adaptatif (Adaptive-RAG)

Le profil adaptive se résout vers un AdaptiveRagPipeline : un IQueryComplexityClassifier route d'abord chaque requête, et la décision est toujours tracée (RagTrace.Route + une étape route portant le classifieur, la route et le délégué).

flowchart LR
    Q[query] --> C{classifier}
    C -- NoRetrieval --> D[direct LLM answer<br/>no citations]
    C -- SingleShot --> B[balanced pipeline]
    C -- Iterative --> CO[corrective graph pipeline]

Classifieurs (Orkeon:Rag:QueryRouting:Classifier) : heuristic (défaut — règles déterministes, zéro appel LLM) ou llm (un appel de chat léger et contraint ; sélectionné sans IChatClient, l'heuristique est le repli documenté, avec un avertissement).

La route Iterative délègue au pipeline de graphe corrective mémoïsé (voir RAG correctif) ; l'étape de trace route porte delegate=corrective et RagTrace.Route enregistre la décision.

Référence de configuration (Orkeon:Rag)

Liée par-dessus le preset sélectionné — chaque clé est une surcharge individuelle.

Clé Défaut Signification
Orkeon:Rag:Profile fast Preset : fast / balanced / quality / adaptive / corrective (un nom inconnu échoue bruyamment)
Orkeon:Rag:Collection — La collection qu'interroge rag_search quand l'agent n'en nomme aucune (non définie : default), et celle qu'évalue rag_eval quand ni l'appel ni le dataset n'en nomment et que le dataset n'apporte pas de corpus. rag.query/rag.ingest et knowledge: nomment toujours la leur
Orkeon:Rag:LlmProfile profil par défaut Le profil LLM de l'hôte (Llm:Profiles:<nom>) auquel va chaque appel de modèle du sous-système — génération, transformateurs, reranker listwise, évaluateur et vérificateur d'ancrage correctifs, classifieur llm, juge d'évaluation ; un nom inconnu fait refuser le démarrage de l'hôte en listant les profils connus
Orkeon:Rag:Provider ambiant Type du provider de document store (inmemory/in-memory, redis, sqlite, chromadb/chroma, pinecone, lancedb/lance ; un type inconnu échoue bruyamment) ; non défini = IMemoryProvider ambiant. La connexion est la section hôte propre de ce provider (Orkeon:Redis, Orkeon:Sqlite, Orkeon:ChromaDb, Orkeon:Pinecone, Orkeon:LanceDb), et le store partage avec la mémoire des crews l'instance de ce type que tient la factory
Orkeon:Rag:Retrieval:TopK 5 Chunks conservés pour l'assemblage du contexte (le RagQuery.TopN de l'appelant l'emporte)
Orkeon:Rag:Retrieval:CandidateK 5 (fast) Étage large de la cascade (toujours ≥ TopN final) ; fast n'en a pas et prend TopK, un profil qui rerank prend 50, quality 100
Orkeon:Rag:Retrieval:MinScore aucun Plancher optionnel sur le score brut ; non défini, aucun plancher ne s'applique
Orkeon:Rag:Retrieval:Hybrid:Enabled false (fast) Mode hybride par défaut ; raccourci à plat Retrieval:Hybrid = true accepté
Orkeon:Rag:Retrieval:Hybrid:RrfK 60 Constante de Reciprocal Rank Fusion
Orkeon:Rag:Retrieval:Mmr:Enabled false Diversification MMR à l'étape de fusion
Orkeon:Rag:Retrieval:Mmr:Lambda 0.7 Arbitrage pertinence/diversité dans [0, 1]
Orkeon:Rag:QueryTransform:Mode none none / multi-query / rag-fusion / hyde
Orkeon:Rag:QueryTransform:VariantCount 3 Variantes demandées aux transformers autres que none
Orkeon:Rag:Rerank:Enabled false (fast) Si l'étape de rerank s'exécute
Orkeon:Rag:Rerank:Kind none none / llm / onnx / decision / tout nom enregistré
Orkeon:Rag:Rerank:TopN 5 Chunks conservés après reranking
Orkeon:Rag:Context:MaxTokens 2000 Budget de contexte (≈ 4 caractères/token ; les chunks en excès sont écartés, jamais de dépassement)
Orkeon:Rag:Context:Ordering edges edges (anti-Lost-in-the-Middle) ou linear
Orkeon:Rag:Groundedness:Enabled false Vérification post-génération (tracée comme sautée en l'absence de checker)
Orkeon:Rag:Generation:SystemPrompt intégré Surcharge du system prompt d'ancrage
Orkeon:Rag:Generation:Temperature / MaxOutputTokens — Échantillonnage transmis au client de chat
Orkeon:Rag:QueryRouting:Classifier heuristic heuristic ou llm (profil adaptive)
Orkeon:Rag:Corrective:MaxIterations 3 Budget d'itérations correctives — réécritures de requête, qu'elles soient déclenchées par un verdict Incorrect ou par une réponse non ancrée
Orkeon:Rag:Corrective:WebFallback:Enabled false Politique côté pipeline : le graphe correctif peut-il router vers son nœud web_fallback
Orkeon:Rag:Corrective:WebFallback:MaxResults 3 Nombre de documents web que le graphe demande au retriever
Orkeon:Rag:WebFallback:* désactivé Section séparée — transport du retriever web (Enabled, Endpoint, ApiKeyEnvVar, MaxResults, Timeout, SuspiciousAction) ; voir Fallback web
Orkeon:Rag:Ingestion:DefaultChunkingStrategy recursive Stratégie quand une requête n'en nomme aucune
Orkeon:Rag:Ingestion:ManifestDirectory /output/rag/manifests Répertoire VFS des manifestes par collection

Ingestion

DefaultIngestionPipeline exécute : chargement (DocumentLoaderFactory sélectionne par type/extension de source — texte, CSV, HTML, PDF, WebPageLoader pour les URLs) → validation de sécurité → chunking (stratégie nommée) → embedding → upsert.

Loader Prend en charge Indice SourceDescriptor.Kind
TextFileLoader .txt, .md, .markdown, .text, .log file (ou aucun)
CsvDocumentLoader .csv file (ou aucun)
HtmlDocumentLoader .html, .htm file (ou aucun)
PdfDocumentLoader .pdf file (ou aucun)
WebPageLoader URLs http:// / https:// url (ou aucun)
InlineTextLoader contenu inline (enregistré par AddOrkeonEphemeralSearch) text

Les loaders de fichiers lisent via le VFS (chemins virtuels uniquement). WebPageLoader échoue en mode fermé sans IUrlValidator (AddOrkeonInfrastructure() en enregistre un) : chaque URL est validée contre le SSRF avant la requête, et son client HTTP ne suit aucune redirection, si bien qu'une URL approuvée ne peut pas être renvoyée vers une adresse interne.

Stratégie de chunking (alias) Comportement
recursive (recursive_text, default) Découpage récursif par séparateurs — le défaut
sentence (sentences) Chunks alignés sur les phrases
structural (markdown, headings) Découpage selon les titres
semantic Ferme un chunk quand la phrase suivante s'écarte du centroïde du chunk (seuil 0.75, extension similarity_threshold) ; sans fonction d'embedding, dégrade vers structural — et AddOrkeonRag n'en câble aucune

ChunkingOptions (par IngestionRequest) dimensionne les chunks en caractères : MaxChunkSize 1000, Overlap 200 par défaut.

  • Validation (sécurité du chemin d'ingestion) : PromptInjectionDocumentValidator et ContentIntegrityValidator s'exécutent sur chaque document ; le contenu rejeté part vers l'IQuarantineStore et la provenance est enregistrée (IProvenanceTracker). Détails et modèle de menace dans security.md.
  • Manifeste incrémental (par collection, un fichier JSON écrit via le VFS à {ManifestDirectory}/{collection}.json) : le hash de contenu de chaque source et le profil d'embedding (provider, modèle, dimensions) y sont consignés. Les sources inchangées sont intégralement sautées — chunksEmbedded = 0 ; celles qui ont changé sont purgées et ré-ingérées. Posture d'échec : un manifeste manquant ou corrompu dégrade vers une ingestion complète, un répertoire de manifestes non inscriptible dégrade vers un avertissement (l'ingestion fonctionne, simplement jamais de manière incrémentale) — jamais de crash.
  • Détection de manifeste périmé : le manifeste (VFS) et le store in-memory par défaut n'ont pas la même durée de vie — un second processus trouverait toutes les sources « inchangées » face à un store vide. Quand le store implémente IDocumentStoreCollectionProbe et déclare la collection vide alors que le manifeste liste des sources, le manifeste est écarté et la passe ingère tout.
  • Reindex = true purge chaque source enregistrée et reconstruit la collection. C'est aussi le seul moyen de ré-ingérer après un changement de profil d'embedding : une dérive entre le profil consigné au manifeste et le provider actif fait échouer la passe bruyamment plutôt que de mélanger en silence des vecteurs incompatibles.
  • prune (option de rag_ingest, rag.ingest({ prune: true })) : supprime les chunks et les entrées de manifeste des sources du manifeste absentes de l'ensemble de sources ingéré, et les rapporte en SourcesPruned (<n> pruned dans la sortie de l'outil, sourcesPruned dans le payload du script). L'élagage est sauté pour une passe ayant enregistré une erreur : un chargement en échec ne provoque jamais de perte de données.
  • Portée et concurrence :
    • La persistance du store suit Orkeon:Rag:Provider : le store in-memory par défaut est perdu à la fin du processus ; sqlite, redis, chromadb, pinecone et lancedb persistent.
    • Le document store est global à l'hôte : un store par hôte, partagé par chaque workspace et chaque crew. Les chunks ingérés via un workspace sont récupérables depuis un autre.
    • Le manifeste d'ingestion est par workspace (/output/rag/manifests/{collection}.json via le VFS de chaque workspace). Un second workspace partageant un store persistant voit un manifeste vide ou différent et ré-ingère.
    • Les ingestions d'une même collection sont sérialisées par un verrou en processus par collection (de la lecture du manifeste à son écriture) ; des collections différentes s'exécutent en parallèle. La mise à jour du registre de collections du store est atomique par provider.
    • Le verrou ne vaut qu'en processus : un verrou inter-processus requiert le provider et est hors périmètre, donc deux processus hôtes partageant un store peuvent encore entrer en concurrence.
  • Les sources en glob (*, **, ?) sont dépliées via le VFS par SourceGlobExpander sur chaque surface consommatrice (scripting rag.ingest, outil rag_ingest, CLI orkeon rag ingest, corpus du harnais d'évaluation, et le bloc rag: de la crew). Une adresse http:// / https:// n'est jamais un motif : le ? de sa chaîne de requête ou un * en font partie, et elle atteint WebPageLoader telle qu'écrite, sans que le VFS soit consulté (SourceGlobExpander.IsWebAddress, une seule règle pour toutes les surfaces). Le bloc de crew accepte aussi un répertoire, qui vaut tous les fichiers qu'il contient, et résout un chemin relatif contre le dossier de la crew — tout cela décidé dans RagCollectionsBootstrapper, qui avertit, en nommant la collection, d'un motif ou d'un répertoire qui ne donne aucun fichier.

Intégration crew YAML

Deux blocs YAML, consommés à des moments différents (voir examples/rag/crew-yaml) :

rag:                        # crew-level: collections ingested at crew creation
  collections:
    product-kb:
      sources: [/kb/faq.md]
      chunking: { strategy: recursive, max_tokens: 256, overlap: 32 }

agents:
  support:
    role: Support agent
    goal: Answer from the knowledge base
    knowledge: [product-kb] # agent-level: retrieval attachment
  • Le bloc rag: est parsé en RagCrewConfig ; CrewFactory le transmet à l'IRagCollectionsBootstrapper lors de CreateFromConfigAsync — ingestion au kickoff via le pipeline incrémental (un manifeste à jour en fait un no-op). Une crew déclarant rag: sur un hôte sans AddOrkeonRag journalise un avertissement au lieu d'échouer ; un agent qui y déclare knowledge: aussi.
  • Les pièces jointes knowledge: voyagent sur l'agrégat Agent ; à l'assemblage du contexte de tâche, l'orchestrateur d'exécution appelle IKnowledgeContextAugmenter. Pour chaque pièce jointe, il résout le pipeline du profil de la pièce jointe et n'en exécute que la moitié retrieval (IRagRetrievalCapable.RetrieveAsync — transformation, hybride, rerank et assemblage selon le profil, sans génération ni appel LLM imbriqué), puis injecte dans le prompt de l'agent un bloc borné et numéroté avec citations [n].

Où ça tourne. Tout hôte bâti sur RunnerHost enregistre le sous-système : orkeon run sur une crew YAML, un répertoire de crew ou un script .ork.ts (avec ou sans --events), et orkeon-host ; orkeon-repl aussi, et l'hôte C# de examples/rag/crew-yaml appelle lui-même AddOrkeonRag. orkeon run --validate charge la crew sans rien ingérer. Rien du sous-système n'est construit tant qu'une crew ne s'en sert pas : une crew sans rag:/knowledge: ne charge pas de modèle d'embedding pour lui. Ses réglages sont pourtant jugés au démarrage de l'hôte, qu'une crew s'en serve ou non : un Orkeon:Rag:Provider, un profil, un reranker, un transformeur de requête, un ordre de contexte, un classifieur ou une stratégie de découpage inconnus refusent le démarrage, avec la liste des noms connus (quand un réglage est refusé). L'ingestion exige un fournisseur d'embeddings : le runner par défaut a celui embarqué (sauf si RaggableTree:Enabled vaut false et que rien d'autre n'est configuré). Les manifestes incrémentaux vont sous /output/rag/manifests ; sans montage /output inscriptible, les collections sont ingérées à chaque chargement, avec un avertissement.

Clés YAML :

Clé Effet
rag.collections.<name>.sources Ingérées à la création de la crew : fichiers, globs, répertoires (tous les fichiers qu'ils contiennent) et URL ; un chemin sans / initial est relatif au dossier de la crew (/crew sous orkeon run) ; un motif ou un répertoire qui ne donne rien est un warning de chargement
rag.collections.<name>.chunking (strategy, max_tokens, overlap) Tokens convertis en caractères à ×4
rag.defaults.profile Le profil de retrieval de toute pièce jointe qui n'en nomme pas (recopié sur elle à la création de la crew)
knowledge: forme courte ([product-kb]) Attache la collection avec les défauts ci-dessous
knowledge: forme longue (collection, top_k défaut 5, min_score, max_context_tokens défaut 2000) top_k est le TopN de la requête ; min_score filtre sur le score que rend le profil (similarité vectorielle sous fast, score du cross-encoder sous un profil qui reranke) ; max_context_tokens borne les extraits de la pièce jointe (×4 caractères)
knowledge: forme longue profile Le pipeline de retrieval : le profile de la pièce jointe, sinon rag.defaults.profile, sinon Orkeon:Rag:Profile (fast s'il n'est pas défini). fast, balanced et quality savent récupérer seuls ; corrective et adaptive non (leurs graphes génèrent en chemin) et font échouer la tâche avec un message qui le dit ; un nom inconnu échoue comme le résolveur. balanced/quality exigent aussi le reranker ONNX, qu'orkeon, orkeon-host et orkeon-repl enregistrent

Le document store relève de l'hôte (Orkeon:Rag:Provider), pas de la crew : une crew qui écrit rag.provider est refusée au chargement ('rag.provider' is retired: the document store is the host's choice — set Orkeon:Rag:Provider in the settings).

Surfaces scripting et CLI

  • DSL de scripting (.ork.ts) : les globales de première classe rag.ingest({ collection, sources, chunkingStrategy?, reindex?, prune? }), rag.query(question, { collection, profile?, topN? }) et rag.retrieve(question, { … }) — voir examples/scripting/08-rag.ork.ts. L'espace de noms est toujours enregistré ; les appels échouent avec un message actionnable quand l'hôte n'a pas câblé le sous-système. query et retrieve renvoient un payload de même forme et seul query exécute l'étape de génération : un script qui ne lit que citations devrait appeler retrieve — voir ci-dessous.
  • CLI (orkeon) : orkeon rag ingest|search|eval sur les mêmes pipelines — options dans la référence CLI. Une collection dont le manifeste consigne un autre fournisseur, modèle ou nombre de dimensions d'embedding est refusée (code 1, avec le nom de la collection, les deux modèles et orkeon rag ingest --reindex) sur rag ingest sans --reindex, sur rag search, sur eval rag --no-ingest -c <collection> et sur eval rag -c <collection> quand sa pré-ingestion tourne sans --reindex. Une collection sans manifeste, et eval rag sans -c, ne sont pas contrôlées.
  • Outils agents (Orkeon.Tools.Rag, AddOrkeonRagTools(), requiert AddOrkeonRag) :
Outil Paramètres Comportement
rag_search question (obligatoire), top_k (défaut 3), collection (défaut Orkeon:Rag:Collection, sinon default) IRagPipeline.QueryAsync → réponse + bloc Sources: avec scores ; collection = "raggable-tree" route vers l'index de code RaggableTree quand il est enregistré
rag_ingest collection, sources (chemins / globs / adresses http(s)) — tous deux obligatoires ; chunking_strategy, reindex, prune IIngestionPipeline avec dépliage des globs ; affiche le rapport d'ingestion
rag_eval dataset (obligatoire), collection, profile (défaut default), compare, k (défaut 5), use_llm_judge, reindex Le harnais offline ci-dessous

Un agent de crew qui liste l'un des trois outils (tools: [rag_search]) le reçoit partout où l'hôte les a enregistrés : tout hôte RunnerHost (orkeon run sur une crew YAML, un répertoire de crew ou un script .ork.ts, et orkeon-host), le REPL, et un hôte C# qui appelle AddOrkeonRagTools(). Construire un outil ne résout rien : les pipelines sont résolus à son premier appel.

Retrieval sans génération

IRagRetrievalCapable.RetrieveAsync exécute les étapes 1 à 5 et s'arrête. Même requête, mêmes passages, aucun appel LLM.

Un appelant qui cite les passages retrouvés n'a pas besoin d'une réponse générée : retrieve évite l'appel de génération et ses tokens.

if (pipeline is IRagRetrievalCapable retriever)
{
    var answer = await retriever.RetrieveAsync(
        new RagQuery { Text = question, Collection = "kb", TopN = 6 });
    // answer.Text is empty; answer.Citations holds the assembled passages.
}

Deux propriétés à connaître avant de s'y fier :

  • La capacité est opt-in et doit être sondée. StagedRagPipeline l'implémente ; le graphe correctif non, parce qu'il entrelace l'évaluation du retrieval avec la génération — « retrieval seul » n'est pas un préfixe de son exécution. rag.retrieve lève une exception sur un pipeline qui ne peut pas l'honorer plutôt que de se replier sur QueryAsync, ce qui facturerait exactement ce que l'appelant demandait d'éviter.
  • La trace porte toujours une étape generate, dont le détail indique que l'étape a été sautée à dessein. Une étape absente se lirait comme une trace produite par un pipeline plus ancien.

Évaluation (datasets golden, gate CI)

Le harnais offline (IRagEvalHarness) transforme la qualité du retrieval en un chiffre publié plutôt qu'en une affirmation :

  • Dataset (examples/rag/eval/golden.yaml) : un répertoire de corpus plus des cas — question, références de sources relevant (comparées par suffixe aux ids ingérés), expected_substrings, reference_answer, tags. Le corpus est ingéré (de manière incrémentale) avant chaque passe.
  • Métriques : recall@k, precision@k et MRR par cas et agrégés (déterministes) ; la génération (groundedness, answer-relevance) est notée par un juge LLM quand il est disponible, avec un repli heuristique déterministe — le rapport indique toujours quel juge a tourné.
  • Profils comparés en une seule passe : orkeon eval rag --dataset … --compare fast,balanced,quality,corrective,adaptive --offline (--offline remplace la génération par un stub extractif déterministe — zéro réseau ; le tableau mesuré et sa lecture honnête vivent dans examples/rag/eval/README.md).
  • Gate CI (.github/workflows/rag-eval.yml) : le tableau comparatif est publié dans le step summary, et un garde anti-régression fait échouer le build quand le recall@5 agrégé ou le MRR du profil balanced passe sous les planchers (--min-recall 0.80 --min-mrr 0.70, bloc env: du workflow). Les cas étiquetés correctif sont exclus des gates : ils sont conçus exprès pour mettre en échec un retrieval en une passe (voir plus bas).
  • Schéma : publié comme interface RagEvalDataset / RagEvalCase dans les typings de scripting (src/scripting/Orkeon.Scripting/Typings/rag.d.ts). Un cas sans question est refusé avec une erreur nommant case #<index> ('<id>') et le champ manquant.
  • Hôtes : l'espace de noms de script rag (rag.retrieve, rag.ingest, …) est lié dans les trois hôtes — orkeon run, le REPL et le daemon (RunnerExecution) — par une seule RagScriptingBackendFactory.Build(IServiceProvider) qui résout IIngestionPipeline depuis le DI ; le verrou d'ingestion par collection est donc partagé avec rag_ingest.

RAG correctif (CRAG)

Le profil corrective se résout vers CorrectiveRagPipeline (Orkeon.Rag.Corrective) — CRAG construit sur le mode d'orchestration Graph d'Orkeon : l'exécution du pipeline est un StateGraph<RagGraphState> — le moteur StateGraph<TState> du Domain, celui-là même qui sous-tend ProcessType.Graph — avec arêtes conditionnelles, cycles contrôlés et le circuit breaker natif du graphe. Le moteur correctif n'est pas une boucle ad hoc greffée sur le RAG ; le RAG démontre le mode d'orchestration Graph et réciproquement. Même façade IRagPipeline que tous les autres profils : le profil sélectionne l'exécuteur, les appelants ne voient jamais qu'un RagAnswer. Les types correctifs (CorrectiveRagPipeline, IRetrievalEvaluator, IGroundednessChecker, IWebDocumentRetriever, AddOrkeonCorrectiveRag…) sont marqués expérimentaux — diagnostic ORKEXP003, voir API expérimentales.

Topologie du graphe

flowchart LR
    S((start)) --> R[retrieve]
    R --> E{evaluate}
    E -- Correct --> G[generate]
    E -- Ambiguous --> RF[refine]
    E -- "Incorrect · budget left" --> RW[rewrite_query]
    RW --> R
    E -- "Incorrect · budget exhausted, opt-in" --> W[web_fallback]
    RF --> G
    W --> G
    G --> CG{check_groundedness}
    CG -- "ungrounded · budget left" --> RW
    CG -- "grounded / exhausted" --> X((end))

Chaque exécution de nœud ajoute une étape corrective:<node> (avec l'ordinal d'itération) à RagAnswer.Trace ; les verdicts s'accumulent dans RagTrace.Verdicts, les sondes réécrites dans RagTrace.QueryVariants, le nombre de tours de boucle dans RagTrace.Iterations.

Nœud Rôle
retrieve Embarque la sonde courante (question originale, ou dernière réécriture) et recherche CandidateK candidats — hybride BM25 + RRF selon le preset — en conservant TopN
evaluate IRetrievalEvaluator note les chunks face à la question originale (la sonde a pu être réécrite, le besoin d'information non) → RetrievalVerdict
rewrite_query Un appel LLM contraint (température 0) réécrit la sonde de retrieval pour franchir le fossé de vocabulaire, nourri du raisonnement de l'évaluateur et des affirmations non étayées ; reboucle vers retrieve. Une réécriture inutilisable rejoue la sonde précédente mais consomme quand même le budget — jamais d'exception
refine Décomposition puis recomposition sur Ambiguous : filtre par les pertinences par chunk de l'évaluateur (seuil 0.5), redécoupe les chunks en phrases et conserve les segments partageant du vocabulaire avec la question — ne vide jamais l'ensemble de travail
web_fallback Dernier recours opt-in une fois la réécriture épuisée (voir plus bas) ; sauté et tracé sinon
generate Génération ancrée répondant à la question originale de l'utilisateur — jamais à la sonde réécrite — avec les mêmes marqueurs [n] fondés sur le rang, le même budget de tokens et la même disposition edges anti-Lost-in-the-Middle que le pipeline étagé
check_groundedness IGroundednessChecker vérifie la réponse face au contexte ; non ancrée → reboucle par rewrite_query ; sans checker enregistré, le nœud est tracé comme sauté et le graphe se termine

Les deux points de décision sont des arêtes conditionnelles : après evaluate → [generate | rewrite_query | refine | web_fallback], après check_groundedness → [rewrite_query | end].

Verdicts (Correct | Incorrect | Ambiguous)

  • Correct → directement vers generate.
  • Ambiguous → refine, puis generate.
  • Incorrect → rewrite_query tant que le budget d'itérations tient ; à épuisement, le fallback web opt-in se déclenche (uniquement s'il est activé et qu'un retriever est enregistré et qu'il n'a pas encore été tenté), sinon génération best-effort avec les meilleurs chunks disponibles — chaque saut est tracé avec sa raison (disabled, no IWebDocumentRetriever registered, already attempted).

Évaluateur et checker par défaut (enregistrés par AddOrkeonCorrectiveRag, lui-même appelé par AddOrkeonRag) : adossés au LLM quand un IChatClient est enregistré — LlmRetrievalEvaluator et LlmGroundednessChecker, contraints via LlmResponseFormat (json_object là où le provider le câble, p. ex. DeepSeek ; parsing JSON tolérant ailleurs) — sinon les déterministes HeuristicRetrievalEvaluator / HeuristicGroundednessChecker, avec un avertissement.

Double borne — la boucle ne peut jamais s'emballer

  1. Corrective.MaxIterations (défaut 3) : le routage ne réentre jamais dans rewrite_query au-delà du budget — cela borne à la fois le cycle de réécriture Incorrect et la reboucle de groundedness.
  2. Circuit breaker du graphe : la CircuitBreakerPolicy propre au moteur StateGraph, explicitement dérivée du budget (MaxTransitions = (n+2)×7, MaxStateVisits = n+2, timeout par état 2 min, total 10 min) — une seconde couche indépendante qui ne se déclenche que si les invariants de routage venaient à être violés. Un disjoncteur déclenché est intercepté, tracé (corrective:circuit_breaker) et dégradé en réponse best-effort (la génération s'exécute hors du graphe si elle n'avait pas encore tourné). Le pipeline ne lève jamais d'exception pour une condition de boucle.

Le groundedness est natif au graphe

Le preset corrective maintient délibérément Groundedness.Enabled = false : ce drapeau active l'étape 7 optionnelle du pipeline étagé, alors que le graphe exécute son propre nœud check_groundedness dès qu'un IGroundednessChecker est enregistré. Honorer le drapeau ici serait de la configuration morte au mieux, et une double vérification si le preset alimentait un jour un pipeline linéaire.

Fallback web — opt-in, validé contre l'injection

Deux sections de configuration délibérément séparées ; les deux interrupteurs Enabled sont désactivés par défaut et doivent tous deux être activés pour qu'un document web atteigne un jour le graphe :

Section Type Responsabilité
Orkeon:Rag:Corrective:WebFallback (Enabled, MaxResults) RagWebFallbackOptions (Abstractions) Politique côté pipeline : le graphe peut-il router vers web_fallback, et pour combien de documents
Orkeon:Rag:WebFallback (Enabled, Endpoint, ApiKeyEnvVar, MaxResults, Timeout, SuspiciousAction) WebSearchRetrieverOptions (Orkeon.Rag.WebFallback) Transport HTTP : recherche JSON compatible SearxNG + téléchargement de page + politique sur le contenu suspect

Le découpage est architectural, pas accidentel : le shared kernel Abstractions ne dépend que du Domain et de la BCL (ADR-006), et la sortie vers le web est un opt-in explicite à part entière. AddOrkeonRagWebFallback(configuration) enregistre l'IWebDocumentRetriever (WebSearchDocumentRetriever) — activé mais non configuré, il reste inerte avec un avertissement, et la clé d'API ne provient jamais que de la variable d'environnement ApiKeyEnvVar. Chaque page téléchargée passe par PromptInjectionDocumentValidator : le contenu Rejected ne quitte jamais le retriever, le contenu Suspicious est marqué dans les métadonnées ou écarté selon SuspiciousAction, et le contenu n'est jamais réécrit. Modèle de menace, signaux détectés et limites honnêtes : security.md. Les chunks web portent ScoreOrigin = "web" et ouvrent l'ensemble de travail ; les chunks retrouvés localement — qui viennent d'être notés Incorrect — le ferment.

Profils corrective et adaptive

Le preset corrective alimente les nœuds du graphe : retrieval hybride BM25 + RRF (les sondes réécrites ont besoin du versant lexical pour franchir les fossés de vocabulaire) et aucune étape de rerank linéaire — le graphe corrige par des boucles evaluate → rewrite plutôt qu'en reclassant, si bien que le profil n'a besoin d'aucun package ONNX opt-in. La route Iterative du profil adaptive délègue au pipeline corrective mémoïsé (l'étape route trace delegate=corrective).

Honnêteté mesurée

Le mécanisme de bout en bout — verdict du grader Incorrect → réécriture LLM → re-retrieval → notes-power.md cité sur le cas q-007 planté exprès, que quality manque — est prouvé par tests/e2e/Orkeon.E2E.Tests/CorrectiveRagMechanismSlowTests.cs (vrais embeddings BGE, vrai store hybride ; le LLM est scripté pour les deux rôles que la CI ne peut pas fournir, et étiqueté comme tel). Dans le tableau d'évaluation entièrement offline, corrective obtient 0.78 de recall@5 / 0.64 de MRR — en dessous de quality : le stub extractif dégrade les nœuds LLM du graphe — le grader pêche des mots de verdict dans les passages renvoyés en écho, et chaque réécriture s'effondre en une même sonde dégénérée partagée par tous les cas. Preuve : avec Corrective:MaxIterations = 0 (aucune réécriture possible), la ligne revient aux 0.89 / 0.89 des profils linéaires. Cet artefact est analysé ligne à ligne dans examples/rag/eval/README.md — publié tel que mesuré, sans lissage.

Décisions d'architecture

Le registre de décision du sous-système RAG est ADR-006 (statut de shared kernel d' Orkeon.Rag.Abstractions, couplages autorisés, anciens namespaces supprimés sans shims). Les décisions de phase qui se superposent à cet ADR : le double package ONNX (Orkeon.Rag.Onnx runtime + Orkeon.Rag.Onnx.Model poids int8 embarqués — offline garanti), les presets de profil + surcharges clé par clé avec fast comme défaut sûr, les transformers de requête avec sémantique de fusion par kind, le CRAG construit sur le StateGraph du Domain plutôt que sur une boucle ad hoc, et le fallback web strictement opt-in et validé contre l'injection, avec son découpage en sections politique/transport (cette page et ADR-006).

Limitations V1

  • L'index BM25 in-process est par processus et non persisté ; l'hybride natif (LanceDB) est préférable à l'échelle — automatique quand le provider le supporte.
  • MMR utilise la similarité lexicale entre candidats (les embeddings ne sont pas recalculés à l'étape de fusion).
  • balanced / quality / adaptive exigent les packages ONNX opt-in ; sans eux, utiliser Rerank:Kind = llm ou rester sur fast ou corrective.
  • Sans véritable IChatClient, les nÅ“uds LLM du graphe correctif (grader, réécriture, groundedness) dégradent — l'évaluation offline mesure les garde-fous de la boucle, pas la qualité de la réécriture (analyse honnête dans examples/rag/eval/README.md et limitations).
  • Les heuristiques anti-injection du fallback web sont fondées sur des motifs et contournables (security.md) ; le fallback est opt-in et n'est pas éprouvé contre un vrai réseau en CI.