# D3 · Integration (incl. RAG) Conception du pipeline RAG de bout en bout, chunking et embeddings, récupération et reranking, grounding et citations, évaluation et débogage de la récupération, moindre privilège et autorisation des outils, choix MCP vs API, observabilité, et patrons d’intégration en entreprise. import { Accordions, AccordionItem, Tabs, TabItem, Steps } from '@prosefly/astro-components'; C’est le **plus grand domaine de l’examen – 19 %, environ 12 des 63 items**. Il est dominé par l’**architecture RAG** mais couvre aussi la gouvernance des capacités des outils/agents, l’identité et l’autorisation, le choix du mécanisme d’intégration, l’observabilité à l’échelle, et les patrons d’intégration en entreprise. Le jugement récurrent testé : quand une réponse est *confiante mais fausse*, suspectez la **récupération et l’indexation avant le modèle** ; et quand un agent a de nombreux outils, appliquez le **moindre privilège** en supprimant des capacités, non en les journalisant ou en les confirmant. ## Objectifs d’apprentissage À la fin de cette page, vous devriez savoir : 1. Concevoir un **pipeline RAG** étape par étape : ingestion → chunking → embedding → indexation → récupération → rerank → grounding. 2. Accorder une **stratégie de chunking** à la forme des données. 3. Choisir la récupération **dense vs sparse vs hybride** et un index/vector store avec filtres de métadonnées. 4. Améliorer la récupération avec le **reranking, la réécriture de requête, HyDE, le multi-query, MMR**. 5. **Évaluer la récupération** (recall@k, MRR, faithfulness, pertinence de réponse) et déboguer les réponses confiantes-mais-fausses. 6. Trancher entre **RAG, long contexte (1M) et fine-tuning** ; concevoir le **RAG agentique**. 7. Mener l’analyse de **surcharge de capacités / moindre privilège** et combler les écarts **authn/authz**. 8. Choisir les mécanismes d’intégration (**MCP vs API/CLI vs agent-à-agent**), concevoir l’**observabilité à l’échelle**, et appliquer les **patrons d’intégration en entreprise** (files, webhooks, idempotence, batch, fraîcheur). --- ## 3.1 The RAG pipeline, stage by stage Le Retrieval-Augmented Generation ancre le modèle dans *vos* données en récupérant des passages pertinents et en les plaçant dans le contexte au moment de la requête. Apprenez le pipeline comme un squelette fixe ; chaque décision de conception s’insère dans une étape. ```text INGESTION INDEX-BUILD (offline) QUERY-TIME (online) ┌──────────┐ ┌───────────────────────────────┐ ┌───────────────────────────────────┐ │ sources │ │ clean → chunk → embed → │ │ query → (rewrite/HyDE/multi-query) │ │ (docs, │──▶│ write vectors + metadata to │ │ → retrieve top-k (dense+sparse) │ │ DB, web)│ │ vector store / search index │ │ → rerank → assemble context │ └──────────┘ └───────────────────────────────┘ │ → Claude generates grounded answer │ │ freshness / refresh pipeline ▲ │ → cite sources → validate │ └──────────────────────────────┘ └───────────────────────────────────┘ ``` | Étape | Responsabilité | Mode de défaillance principal | | --- | --- | --- | | Ingestion | Tirer, nettoyer, normaliser, dédupliquer les données source | Contenu périmé/dupliqué ; structure perdue | | Chunking | Découper en unités récupérables | Chunks trop grands (dilution) ou trop petits (fragmentation) | | Embedding | Transformer les chunks en vecteurs | Modèle d’embedding erroné/incompatible | | Indexation | Stocker vecteurs + métadonnées pour la recherche | Non ré-indexé après rafraîchissement → hits périmés | | Récupération | Aller chercher les chunks candidats d’une requête | Rappel faible ; mauvais classement | | Rerank | Réordonner les candidats par vraie pertinence | Sauté → meilleur passage enfoui sous le top-k | | Grounding | Contraindre la réponse au texte récupéré + citer | Le modèle répond depuis sa mémoire paramétrique, non le contexte | --- ## 3.2 Chunking strategies matched to data shape Le chunking est la décision RAG à plus fort levier. La bonne stratégie dépend de la **structure de la source**. | Stratégie | Comment elle découpe | Idéale pour | Faiblesse | | --- | --- | --- | --- | | Taille fixe | N tokens avec chevauchement | Prose uniforme, référence rapide | Coupe en milieu de phrase/d’idée | | Récursive | Découper sur les frontières paragraphe → phrase → token | Texte général avec un peu de structure | Reste aveugle au sens aux frontières | | Sémantique | Découper là où la similarité d’embedding chute | Texte topiquement dense où les idées changent | Plus de calcul à la construction | | Structurelle / document-aware | Découper sur les titres, sections, lignes de tableau, blocs de code | Manuels, contrats, Markdown, HTML, code | Requiert un parseur par format | | Parent–enfant | Récupérer de petits chunks enfants, renvoyer le parent plus grand pour le contexte | Correspondance précise + contexte riche pour le modèle | Plus de stockage/de comptabilité | | Late chunking | Embarquer tout le document, puis pooler par chunk depuis les embeddings de tokens | Longs documents où le contexte cross-chunk compte | Nécessite un support d’embedding long-context | ```text Document shape? ├─ Structured (headings/tables/code) → structural / document-aware chunking ├─ Long, cross-referential prose → parent–child or late chunking ├─ Topically shifting prose → semantic chunking └─ Uniform prose, need a baseline → recursive (fall back to fixed) ``` :::tip[Signal d’examen] « Les réponses citent la mauvaise section / perdent le contexte environnant » → les chunks sont trop petits ou aveugles aux frontières ; passez au chunking **parent–enfant** ou **structurel**. « Contrats / manuels / code » dans l’énoncé → chunking **document-aware**, non taille fixe. ::: --- ## 3.3 Embeddings and indexing ### Dense vs sparse vs hybride | Type de récupération | Signal | Fort sur | Faible sur | | --- | --- | --- | --- | | Dense (embeddings) | similarité sémantique | paraphrase, synonymes, concepts | IDs exacts, tokens rares, codes | | Sparse (BM25 / mots-clés) | recouvrement lexical | termes exacts, références de pièces, noms | synonymes, paraphrase | | Hybride (dense + sparse, fusionnés) | les deux, scores fusionnés | la plupart des corpus d’entreprise | un peu plus d’infra | La plupart des RAG de production utilisent la récupération **hybride** (p. ex. fusion par reciprocal-rank de BM25 et dense) car les vraies requêtes mêlent concepts et identifiants exacts. ### Vector store et filtres de métadonnées | Facteur de choix | Recommandation | | --- | --- | | Échelle (milliards de vecteurs) | Vector DB dédiée ou service managé | | Déjà sur un cloud | Utiliser son offre vector/recherche managée (IAM, résidence hérités) | | Besoin de lexical + vectoriel en un | Un moteur de recherche avec support hybride | | Filtrage | Stocker des **métadonnées** (tenant, type de doc, ACL, date) et filtrer *avant/le long de* la recherche vectorielle | **Les filtres de métadonnées sont aussi un contrôle de sécurité** : filtrer par `tenant_id` et ACL par utilisateur au moment de la récupération est la façon d’empêcher les fuites cross-tenant/de permission (voir 3.9). --- ## 3.4 Retrieval and re-ranking techniques | Technique | Ce qu’elle fait | Quand l’ajouter | | --- | --- | --- | | top-k | aller chercher les k candidats les plus proches | toujours ; réglez k pour le rappel vs le bruit | | MMR (max marginal relevance) | diversifier les résultats, réduire la redondance | des chunks quasi dupliqués encombrent le top-k | | Reranking | un cross-encoder re-score les candidats par vraie pertinence | la précision compte ; récupérer large, reranker vers peu | | Réécriture de requête | reformuler/étendre la requête | requêtes conversationnelles ou sous-spécifiées | | HyDE | générer une réponse hypothétique, embarquer *celle-ci* pour récupérer | requêtes creuses où le vocabulaire de la réponse diffère de celui de la question | | Multi-query | émettre plusieurs variantes de requête, unir les résultats | récupération critique pour le rappel | Une recette de haute précision courante : **récupérer large (k=50, hybride) → reranker → garder les 5–8 premiers → grounder**. Le reranking est souvent le plus grand gain de précision à lui seul. ```text query ─▶ [rewrite / multi-query] ─▶ hybrid retrieve (k=50) │ ▼ reranker ─▶ top 6 ─▶ context ─▶ Claude ``` --- ## 3.5 Grounding and citations Le grounding signifie que la réponse est **contrainte aux passages récupérés**, et que chaque affirmation est traçable. - Instruisez le modèle de répondre **uniquement** à partir du contexte fourni et de dire quand le contexte est insuffisant (ne jamais inventer). - Utilisez la fonctionnalité **Citations** / des références structurées pour que chaque affirmation renvoie à son chunk source et à sa localisation. - Renvoyez `insufficient context` plutôt qu’une supposition tirée de la mémoire paramétrique quand la récupération échoue — un système grounded préfère « je n’ai pas cela » à une fabrication confiante. ```json { "system": "Answer ONLY from . Cite the source id for each claim. If the context does not contain the answer, say so.", "messages": [ {"role": "user", "content": "{retrieved_chunks_with_ids}\n\nQuestion: What is the termination notice period?"} ] } ``` --- ## 3.6 Evaluating retrieval Vous ne pouvez pas corriger ce que vous ne mesurez pas. La récupération et la génération sont évaluées **séparément** pour savoir quelle étape a échoué. | Métrique | Mesure | Étape | | --- | --- | --- | | Recall@k | Le chunk pertinent est-il entré dans le top-k ? | Récupération | | MRR | À quel rang le premier chunk pertinent est-il arrivé ? | Récupération / rerank | | Precision@k | Quelle part du top-k est réellement pertinente ? | Récupération / rerank | | Faithfulness / groundedness | La réponse est-elle soutenue par le contexte récupéré (pas de fabrication) ? | Génération | | Pertinence de réponse | La réponse répond-elle à la question ? | Génération | :::tip[Signal d’examen] Si le **recall@k est élevé mais les réponses sont fausses**, la défaillance est dans la génération/le grounding (ou le reranking), non la récupération. Si le **recall@k est faible**, corrigez d’abord le chunking/les embeddings/la récupération. Ne mesurer que la justesse de bout en bout masque quelle étape a cassé — un piège de la métrique agrégée. ::: --- ## 3.7 Débogage des réponses confiantes-mais-fausses après un rafraîchissement de document C’est un scénario d’examen emblématique. Un document est mis à jour ; l’assistant continue de donner l’**ancienne** réponse, avec assurance. L’instinct de blâmer le prompt ou le modèle est faux. 1. **Suspectez d’abord l’index.** Le document rafraîchi a-t-il été re-chunké, ré-embarqué et ré-indexé ? Un rafraîchissement qui met à jour le store source mais **pas l’index vectoriel** laisse des vecteurs périmés que la récupération renvoie fidèlement. 2. **Inspectez ce qui a été récupéré.** Journalisez les IDs et le texte des chunks récupérés pour la requête défaillante. Si c’est l’*ancien* contenu, c’est un bug d’indexation/de fraîcheur, non un bug de modèle. 3. **Vérifiez les métadonnées de chunk/version.** Un `updated_at` périmé ou un job de ré-indexation manquant le confirme. 4. **Seulement alors**, examinez le grounding/le prompt. Si la récupération a renvoyé le *nouveau* contenu mais que la réponse a utilisé l’ancien, l’instruction de grounding ou le reranking est en cause. ```text Confident-but-wrong after a refresh? 1. What did retrieval return? ──stale── ▶ re-chunk/re-embed/re-index (fix freshness pipeline) 2. Returned fresh content? ──yes──── ▶ check grounding instruction / reranking 3. Neither? ────────── ▶ check embedding-model mismatch / query rewrite ``` :::caution[Le mauvais instinct] Les distracteurs suggéreront « réécrire le system prompt », « monter l’effort », ou « passer à un plus gros modèle ». Aucun ne corrige une récupération périmée. Le bon premier geste est d’**inspecter et réparer la couche de récupération/indexation**. ::: --- ## 3.8 RAG vs long context vs fine-tuning | Approche | Idéale quand | Profil coût/exploitation | Échoue quand | | --- | --- | --- | --- | | RAG | Le corpus est grand, change souvent, exige citations/fraîcheur | Infra de récupération + pipeline de rafraîchissement | La qualité de récupération est mauvaise | | Long contexte (1M) | Corpus petit/borné qui tient dans la fenêtre ; simplicité valorisée | Coût élevé en tokens par appel ; pas d’infra | Corpus trop grand/coûteux ; dégradation du needle | | Fine-tuning | Style/format/comportement de domaine stable à ancrer | Cadence d’entraînement + ré-entraînement | Les faits changent souvent (ré-entraînement infaisable) | ```text Does the knowledge change frequently or need citations? ── yes ─▶ RAG Is the corpus small, stable, and fits comfortably in context? ── yes ─▶ long context Is it about behaviour/format/style rather than changing facts? ── yes ─▶ fine-tuning ``` Ces options ne sont pas mutuellement exclusives : fine-tuner pour le style, RAG pour les faits, long contexte pour une session bornée. --- ## 3.9 RAG agentique, surcharge de capacités des outils et moindre privilège Le **RAG agentique** laisse le modèle décider *quand* et *quoi* récupérer, émettre des requêtes de suivi, et combiner les sources — plus puissant que la récupération one-shot, mais avec plus de coût et de surface de défaillance. Utilisez-le quand les requêtes sont multi-hop ou exploratoires ; utilisez le RAG simple quand une seule récupération suffit. ### Surcharge de capacités et moindre privilège Un agent avec trop d’outils (18 contre 4–5 recommandés) est plus lent, plus sujet aux erreurs, et plus dangereux. La **bonne remédiation d’un outil destructeur inutile est de le supprimer**, non de journaliser son usage ou d’ajouter une confirmation. | Symptôme | Mauvais correctif | Bon correctif | | --- | --- | --- | | L’agent a `refund`, `delete_account`, `issue_credit` dont il n’a jamais légitimement besoin | Journaliser les appels ; ajouter « êtes-vous sûr ? » | **Supprimer** les outils de l’allowlist de l’agent (moindre privilège) | | 18 outils, le modèle choisit les mauvais | Un prompt plus long décrivant chacun | Réduire à 4–5 ; utiliser **tool search + `defer_loading`** pour les grands catalogues | | Action dangereuse occasionnelle | Prompt « ne jamais faire X » | Un hook de permission programmatique refuse X | :::caution[Le moindre privilège, c’est la suppression, non l’observation] Journaliser une capacité dangereuse ou la confirmer laisse toujours la capacité présente et accessible (agence excessive). La bonne réponse de l’examen **supprime** les outils inutiles pour que l’agent ne puisse pas du tout les invoquer. ::: ### Analyse des écarts authn / authz Les outils agissent sur de vrais systèmes, donc **l’identité et les permissions doivent se propager jusqu’à l’appel de l’outil** — l’agent doit agir *en tant que l’utilisateur*, avec ses permissions, non comme un compte de service omnipotent. | Écart | Risque | Contrôle | | --- | --- | --- | | L’agent utilise un compte de service unique pour tous les utilisateurs | Un utilisateur atteint les données d’un autre | Propager l’identité de l’utilisateur final ; portée par utilisateur | | L’outil n’a pas de vérification de permission par utilisateur | Élévation de privilège | Appliquer les ACL dans l’outil, pas seulement dans le prompt | | Serveur MCP distant non authentifié | N’importe qui peut appeler des outils puissants | **OAuth 2.1** sur le serveur MCP distant | | La récupération ignore les ACL | Fuite cross-tenant | Filtre de métadonnées/ACL au moment de la récupération (3.3) | --- ## 3.10 Choosing the integration mechanism | Mécanisme | À utiliser quand | Notes | | --- | --- | --- | | **MCP** | Outils/ressources réutilisables partagés entre de nombreux agents/clients ; protocole standard | JSON-RPC 2.0 ; `stdio` local / Streamable HTTP distant ; OAuth 2.1 pour le distant ; le MCP connector laisse la Messages API appeler des serveurs distants | | **API directe / outil CLI** | Une capacité ponctuelle ou propre à l’app ; contrôle/latence les plus serrés | Défini comme un `tool` dans la requête ; pas de surcharge de protocole | | **Agent-à-agent** | Décomposer entre des agents spécialisés à contexte isolé | Coordinateur/sous-agent ; coût/latence plus élevés | ```text Will many clients/agents reuse this capability? ── yes ─▶ MCP server (OAuth if remote) One app, tight control/latency? ── yes ─▶ direct API/CLI tool Need a specialised agent with its own context? ── yes ─▶ agent-to-agent (subagent) ``` ### Découverte progressive vs contexte monolithique Ne chargez **pas** chaque outil et document dans le contexte d’emblée. Utilisez la **découverte progressive** : **tool search + `defer_loading: true`** pour les grands catalogues d’outils, et des **Skills** chargées à la demande. Un contexte monolithique est coûteux, hostile au cache, et dégrade la justesse de sélection d’outils. --- ## 3.11 Observability at scale À l’échelle de production, vous ne pouvez pas déboguer ce que vous ne pouvez pas tracer. Instrumentez chaque requête de bout en bout. | Signal | Ce qu’il faut capturer | | --- | --- | | Traces | Arbre de spans complet : récupération, rerank, appel de modèle, appels d’outils, validation | | IDs de corrélation | Un ID enfilé à travers app → modèle → outils → systèmes en aval | | Télémétrie tokens/coût | Tokens d’entrée/sortie/thinking et coût par requête, par segment, par modèle | | Télémétrie de récupération | Requête, IDs des chunks récupérés, scores, ordre de rerank | | Erreurs & stop reasons | `stop_reason`, codes d’erreur, retries, replis, drapeaux de mode dégradé | ```text [req id: 9f3a] ── app ──▶ retrieve(k=50) ──▶ rerank(6) ──▶ opus-5 ──▶ tool:lookup ──▶ validate ──▶ resp correlation id 9f3a threads through every span; token+cost tagged per span ``` La télémétrie de coût/latence par segment est ce qui vous permet de router, cacher et optimiser (D4) avec des preuves plutôt que des suppositions. --- ## 3.12 Enterprise integration patterns and data freshness | Patron | Objectif | Note propre à Claude | | --- | --- | --- | | File (queue) | Découpler des producteurs en rafale des appels de modèle rate-limités | Lisse la charge face aux paliers RPM/ITPM | | Webhook | Réagir aux événements externes (ticket créé, doc mis à jour) | Déclencher ingestion/rafraîchissement et exécutions d’agent | | Idempotence | Retries sûrs sans effets de bord dupliqués | Clés d’idempotence sur les actions d’outil ; critique avec les retries à backoff | | Batch | Travail de masse tolérant à la latence | **Message Batches API** : remise de 50 %, résultats sous 24 h | | Rafraîchissement / fraîcheur | Garder l’index à jour | Re-chunk/re-embed/re-index piloté par événement ou planning (lié à 3.7) | :::tip[Signal d’examen] « Requête réessayée facturée/agie deux fois » → **clés d’idempotence**. « Des milliers de documents à classer la nuit, le coût compte » → **Batch API**. « Le document a changé mais pas la réponse » → **pipeline de fraîcheur/rafraîchissement** et ré-indexation. ::: --- ## 3.13 A concrete RAG pipeline configuration Les auteurs d’items récompensent les candidats qui savent lire une config et prédire son comportement. Une base d’entreprise défendable : ```yaml ingestion: sources: [confluence, s3_pdfs, postgres_kb] dedup: content_hash pii_scrub: true chunking: strategy: structural # split on headings/sections fallback: recursive target_tokens: 400 overlap_tokens: 60 parent_child: true # match child (~400), return parent (~1500) embedding: model: text-embedding-3-large # keep query + index model identical dimensions: 1024 index: store: managed_vector_db metadata: [tenant_id, doc_type, acl, updated_at, source_id] filters_before_search: [tenant_id, acl] # security + precision retrieval: mode: hybrid # BM25 + dense, RRF fusion k: 50 rerank: model: cross_encoder_reranker keep_top: 6 query_transform: [rewrite, multi_query] # for conversational/sparse queries generation: model: claude-sonnet-5 grounding: answer_only_from_context citations: true on_insufficient_context: "say so; do not use parametric memory" refresh: trigger: [webhook_on_update, nightly_schedule] action: re_chunk_re_embed_re_index ``` | Réglage | Effet si trop bas | Effet si trop haut | | --- | --- | --- | | `target_tokens` | fragmente les idées ; perd le contexte | dilue la pertinence ; enfouit la réponse | | `overlap_tokens` | faits de frontière perdus | gonflement du stockage/coût, hits dupliqués | | `k` (pré-rerank) | rappel faible | bruit ; rerank plus lent | | `keep_top` | le meilleur passage peut être écarté | gonflement du contexte, coût plus élevé, dilution du needle | :::tip[Signal d’examen] « Récupérer large (k≈50 hybride) → reranker → garder 6 → grounder avec citations » est la recette canonique de haute précision. Les distracteurs qui sautent le reranking, utilisent le dense-only, ou montent `keep_top` à 50 sont les mauvaises réponses. ::: --- ## 3.14 Retrieval evaluation with worked numbers Vous devez pouvoir *calculer* les métriques, pas seulement les nommer. **Cadre.** 5 requêtes ; pour chacune on connaît l’unique chunk pertinent et son rang dans la liste récupérée : | Requête | Rang du chunk pertinent | Dans le top-3 ? | Rang réciproque | | --- | --- | --- | --- | | Q1 | 1 | oui | 1/1 = 1.00 | | Q2 | 4 | non | 1/4 = 0.25 | | Q3 | 2 | oui | 1/2 = 0.50 | | Q4 | (non récupéré) | non | 0 | | Q5 | 1 | oui | 1/1 = 1.00 | ```text recall@3 = (#queries whose relevant chunk is in top-3) / total = 3/5 = 0.60 MRR = mean reciprocal rank = (1.00 + 0.25 + 0.50 + 0 + 1.00) / 5 = 0.55 ``` Supposons maintenant qu’ajouter un **reranker** déplace le chunk pertinent de Q2 au rang 2 et récupère celui de Q4 au rang 3 : ```text recall@3 → 5/5 = 1.00 (both now in top-3) MRR → (1.00 + 0.50 + 0.50 + 0.333 + 1.00)/5 = 0.667 ``` Le reranker a relevé le recall@3 de 0,60 → 1,00 et le MRR de 0,55 → 0,67 — le plus grand gain de précision/classement à lui seul, sans toucher au chunking ni aux embeddings. | Métrique | Formule | Se lit comme | | --- | --- | --- | | recall@k | pertinents-dans-le-top-k ÷ total des requêtes | « avons-nous récupéré la réponse tout court ? » | | MRR | moyenne(1 ÷ rang du premier pertinent) | « à quel rang est-il arrivé ? » | | precision@k | pertinents-dans-le-top-k ÷ k | « à quel point le top-k est-il propre ? » | | faithfulness | affirmations soutenues ÷ total des affirmations | « la réponse est-elle restée grounded ? » | :::caution[Interpréter les chiffres] Un **recall** élevé mais une **faithfulness** faible ⇒ la récupération va bien, la génération/le grounding est cassé. Un **recall** faible ⇒ corrigez d’abord le chunking/les embeddings/la récupération. Ne reporter que la justesse de bout en bout masque laquelle est vraie — le piège de la métrique agrégée. ::: --- ## 3.15 Multi-tenant isolation and ACL-aware retrieval Dans un index partagé, la récupération est une **frontière de sécurité**. Une requête ne doit jamais faire remonter le chunk d’un autre tenant ou d’un utilisateur non autorisé. ```text user (tenant_42, role: support) asks a question │ attach identity: {tenant_id: 42, acl_groups: [support]} ▼ filter BEFORE/ALONGSIDE vector search: WHERE tenant_id = 42 AND acl IN ('public','support') ▼ hybrid retrieve → rerank → ground (only authorised chunks ever enter context) ``` | Écart | Fuite | Contrôle | | --- | --- | --- | | Pas de filtre `tenant_id` | Exposition de données cross-tenant | Pré-filtre obligatoire sur `tenant_id` | | ACL appliquée seulement dans le prompt | Le modèle peut être amené à la contourner | Appliquer l’ACL à la **couche de récupération**, non dans la prose | | Compte de service partagé pour la récupération | L’utilisateur voit des données inaccessibles | Propager l’identité de l’utilisateur final dans le filtre de requête | | Le rerank/cache ignore le tenant | Hit cross-tenant caché | Cadencer les caches par tenant + ACL | :::danger[Le filtrage au moment de la récupération est le contrôle] Filtrer *après* la génération (« le modèle ne le mentionnera pas ») n’est pas un contrôle — le chunk non autorisé est déjà entré dans le contexte et peut fuir. La bonne réponse de l’examen filtre par `tenant_id`/ACL **avant** la recherche vectorielle. ::: --- ## 3.16 Scénario détaillé : un agent RAG de support qui fuit, périmé et sur-privilégié **Scénario.** Un agent de support SaaS B2B sert 300 tenants depuis un index vectoriel partagé unique. Trois plaintes arrivent : (1) un tenant voit occasionnellement le runbook d’un autre tenant dans une réponse ; (2) après que les clients ont mis à jour leurs docs, l’agent cite encore la version d’hier, avec assurance ; (3) l’agent a 22 outils dont `delete_ticket` et `refund` qu’il ne devrait jamais appeler. La récupération est dense-only, k=8, sans reranker. **Trace de raisonnement d’expert.** 1. **L’isolation d’abord (sévérité la plus élevée).** L’exposition cross-tenant est un incident de sécurité. Ajoutez un **pré-filtre `tenant_id` (et ACL) obligatoire** sur chaque requête, cadencez les caches par tenant, et propagez l’identité de l’utilisateur final. Ne comptez pas sur la formulation du prompt pour séparer les tenants. 2. **La fraîcheur ensuite.** Le confiant-mais-faux-après-mise-à-jour est une récupération périmée : le rafraîchissement a mis à jour le store source mais pas l’**index vectoriel**. Inspectez les IDs des chunks récupérés (ils seront anciens), puis corrigez le pipeline de **re-chunk/re-embed/re-index** avec des déclencheurs webhook + nocturnes. 3. **Le moindre privilège en troisième.** Supprimez `delete_ticket`, `refund`, et les autres outils inutiles de l’allowlist — ne vous contentez pas de journaliser ou d’ajouter « êtes-vous sûr ? ». Réduisez à ~4–5 outils ; utilisez tool search + `defer_loading` si le catalogue légitime est grand. 4. **Puis la qualité.** Dense-only + k=8 + sans rerank sous-performe sur les identifiants exacts et la précision. Passez à la **récupération hybride, k=50, rerank, garder le top 6**, et mesurez recall@k et faithfulness par segment de tenant. 5. **Fermez la boucle.** Instrumentez des IDs de corrélation et une télémétrie de récupération par segment pour que le prochain incident soit reconstructible. **Pourquoi les alternatives tentantes sont fausses :** « ajouter une règle du system prompt de ne pas révéler d’autres tenants » est du prompt comme mécanisme d’application et laisse la fuite ; « passer à un plus gros modèle » ne corrige ni l’isolation ni la fraîcheur ; « journaliser les outils dangereux » laisse l’agence excessive ; « monter k à 500 » ajoute du bruit au lieu d’ajouter un reranker. --- ## 3.17 Common misconceptions | Idée reçue | Réalité | Pourquoi c’est important à l’examen | | --- | --- | --- | | « Confiant-mais-faux signifie que le modèle est mauvais. » | Après un changement de données, cela signifie généralement une récupération/indexation périmée. | Inspectez d’abord la récupération ; les correctifs prompt/modèle sont des distracteurs. | | « Les embeddings denses récupèrent tout. » | Le dense est faible sur les IDs/codes exacts ; l’hybride ajoute du sparse. | Les énoncés à références de pièces/SKU requièrent l’hybride. | | « Une plus grande fenêtre de contexte remplace le RAG. » | Elle coûte plus par appel, ne peut pas citer, et se dégrade sur le needle. | Le bourrage long-context est la mauvaise réponse pour les corpus grands/changeants. | | « Le fine-tuning est la façon d’ajouter de la connaissance. » | Le fine-tuning ancre le comportement/le style ; les faits changeants nécessitent le RAG. | Les énoncés à faits changeant chaque semaine rejettent le fine-tuning. | | « Journaliser un outil dangereux le rend sûr. » | La capacité reste accessible — agence excessive. | Le moindre privilège signifie *suppression*, non observation. | | « Les règles de prompt maintiennent les tenants isolés. » | L’isolation doit être appliquée au filtre de récupération. | Le filtrage ACL au moment de la récupération est le bon contrôle. | | « Les serveurs MCP sont authentifiés par défaut. » | Le MCP distant nécessite OAuth 2.1 + vérifications par utilisateur. | Le MCP distant non authentifié est un piège de sécurité. | | « Réessayer est toujours sûr. » | Les actions non idempotentes se dupliquent ; ajoutez des clés d’idempotence. | Les énoncés de double-facturation testent l’idempotence. | --- ## Pièges de l’examen dans ce domaine | Piège | Pourquoi c’est faux | | --- | --- | | Blâmer le prompt/le modèle pour des réponses confiantes-mais-fausses après un rafraîchissement | La cause est généralement une récupération/indexation périmée ; inspectez d’abord ce qui a été récupéré | | Corriger un outil dangereux inutile en le journalisant ou le confirmant | Laisse l’agence excessive ; le moindre privilège signifie **supprimer** l’outil | | Donner 18 outils à un agent « pour la flexibilité » | Plus lent, sujet aux erreurs ; réduisez à 4–5, utilisez tool search + `defer_loading` | | Utiliser la récupération dense-only pour des références de pièces / IDs exacts | Le dense rate les tokens exacts ; utilisez sparse/hybride | | Ne mesurer que la justesse de bout en bout | Masque si c’est la récupération ou la génération qui a échoué ; mesurez recall@k et faithfulness séparément | | Bourrer un corpus grand et changeant en long-context | Coûteux, pas de citations, dégradation du needle ; utilisez le RAG | | Fine-tuner pour injecter des faits changeant fréquemment | Cadence de ré-entraînement infaisable ; utilisez le RAG | | Sauter le reranking | Meilleur passage enfoui sous le top-k ; la précision souffre | | Un compte de service pour les appels d’outils de tous les utilisateurs | Exposition de données cross-user ; propagez l’identité + ACL par utilisateur | | Serveur MCP distant non authentifié | N’importe qui peut invoquer des outils puissants ; exigez OAuth 2.1 | | Réessayer des actions d’outil non idempotentes sans clés | Effets de bord dupliqués (double remboursement/facturation) | | Charger tous les outils/docs dans le contexte d’emblée | Coûteux, hostile au cache, pire sélection d’outils ; utilisez la découverte progressive | | Appliquer l’isolation multi-tenant avec une règle de system prompt | L’isolation doit être un filtre `tenant_id`/ACL au moment de la récupération, non de la prose | | Filtrer les chunks non autorisés après la génération | Le chunk est déjà entré dans le contexte ; filtrez avant la recherche vectorielle | | Monter k à des centaines au lieu d’ajouter un reranker | Ajoute du bruit ; le reranking est le gain de précision/classement | | Ne reporter que la justesse de bout en bout pour un système RAG | Masque si la récupération ou le grounding a échoué ; mesurez recall@k et faithfulness | | Utiliser le même modèle d’embedding pour la requête et l’index de façon incohérente | Un décalage modèle requête/index ruine la similarité ; gardez-les identiques | | Cacher les résultats de récupération sans cadencer par tenant/ACL | Risque de servir un hit caché cross-tenant | --- ## Questions d’entraînement A. Réécrire le system prompt pour qu’il soit plus juste. B. Inspecter ce que la récupération a réellement renvoyé ; le document mis à jour n’a probablement pas été re-chunké/ré-embarqué/ré-indexé, donc la récupération sert des vecteurs périmés. C. Passer à Opus 5 avec effort xhigh. D. Ajouter plus d’exemples few-shot. **Réponse : B.** Le confiant-mais-faux immédiatement après un rafraîchissement pointe vers une récupération/indexation périmée, non le modèle. Le premier geste est de journaliser les chunks récupérés et de confirmer si le rafraîchissement a mis à jour l’index vectoriel. Les réécritures de prompt (A, D) et un plus gros modèle (C) ne peuvent pas corriger une récupération périmée. A. Garder les outils mais journaliser chaque appel pour l’audit. B. Supprimer les outils inutiles de l’allowlist de l’agent (moindre privilège) pour qu’il ne puisse pas du tout les invoquer. C. Ajouter une confirmation avant l’exécution de ces outils. D. Ajouter une phrase du system prompt interdisant leur usage. **Réponse : B.** Le moindre privilège signifie que la capacité ne devrait pas être présente. Supprimer les outils élimine l’agence excessive. La journalisation (A) et la confirmation (C) laissent la capacité accessible ; une règle de prompt (D) est du prompt comme mécanisme d’application et peut être contournée. A. Augmenter k à 500. B. Utiliser la récupération hybride (BM25 + dense avec fusion de rangs) pour que les identifiants exacts et les correspondances sémantiques soient tous bien classés. C. Passer à un plus gros modèle de génération. D. Retirer les filtres de métadonnées. **Réponse : B.** Les embeddings denses sont faibles sur les tokens/codes exacts ; le sparse (BM25) les gère, et la fusion hybride couvre les deux types de requête. Un k énorme (A) ajoute du bruit sans corriger la correspondance lexicale ; un plus gros modèle (C) ne change pas ce qui est récupéré ; retirer les filtres (D) nuit à la précision et à la sécurité. A. Récupération ; baisser k. B. Génération/grounding ; renforcer l’instruction de répondre uniquement à partir du contexte, ajouter des citations, et envisager le reranking pour que le meilleur passage soit en tête. C. Embeddings ; changer le modèle. D. Indexation ; tout ré-indexer. **Réponse : B.** Un rappel élevé signifie que les bons chunks sont récupérés, donc la faute est dans la génération/le grounding — le modèle répond depuis la mémoire paramétrique. Les instructions de grounding, les citations et le reranking la traitent. Les correctifs côté récupération (A, C, D) visent une étape qui performe déjà bien. A. Fine-tuner un modèle sur le corpus chaque semaine. B. RAG avec récupération hybride, reranking et citations, plus un pipeline de rafraîchissement planifié. C. Bourrer tout le corpus dans le contexte de 1M par requête. D. Long contexte plus fine-tuning combinés. **Réponse : B.** Les corpus grands, changeant fréquemment et exigeant des citations sont le cas RAG canonique. Le fine-tuning hebdomadaire (A) est une cadence de ré-entraînement infaisable pour des faits. Le corpus dépasse la fenêtre et coûterait trop et perdrait les citations (C). (D) hérite des deux problèmes. A. Utiliser un chunking structurel/document-aware qui découpe sur les clauses/sections. B. Utiliser un chunking parent–enfant : correspondre sur de petits chunks enfants mais renvoyer la clause parente plus grande pour le contexte. C. Passer à la récupération dense-only. D. Augmenter la température. E. Retirer les citations. **Réponse : A et B.** Les contrats sont structurés, donc un chunking par clause/section préserve les frontières, et le parent–enfant donne une correspondance précise avec assez de contexte environnant. Le dense-only (C), la température (D) et le retrait des citations (E) ne traitent pas le problème de chunking — les deux derniers l’aggravent. A. Rien ; le MCP est sûr par défaut. B. Une authentification OAuth 2.1 sur le serveur MCP distant, plus des vérifications de permission par utilisateur dans les outils. C. Un system prompt plus long. D. Un palier de rate-limit supérieur. **Réponse : B.** Les serveurs MCP distants requièrent OAuth 2.1, et les outils doivent appliquer des permissions par utilisateur pour que l’agent agisse avec l’autorité de l’appelant. Le MCP n’est pas authentifié par défaut (A) ; les prompts (C) et les rate limits (D) ne traitent pas l’autorisation. A. Des appels synchrones en temps réel dans une boucle serrée. B. La Message Batches API pour une remise de 50 % avec des résultats sous 24 heures. C. Un système multi-agents. D. Le fine-tuning. **Réponse : B.** Le travail de masse tolérant à la latence est exactement le cas d’usage de la Batch API (remise de 50 %, résultats sous 24 h). Les boucles synchrones (A) atteignent les rate limits et coûtent plus. Le multi-agent (C) ajoute coût/complexité ; le fine-tuning (D) est sans rapport avec un batch de classification. A. Désactiver entièrement les retries. B. Ajouter des clés d’idempotence à l’outil de remboursement pour que les appels réessayés soient dédupliqués et ne produisent pas d’effet de bord dupliqué. C. Baisser la température du modèle. D. Journaliser les doublons et rapprocher plus tard. **Réponse : B.** Les retries sur des actions non idempotentes causent des effets de bord dupliqués ; les clés d’idempotence rendent les retries sûrs. Désactiver les retries (A) nuit à la résilience. La température (C) est sans rapport. Rapprocher après coup (D) a tout de même facturé les clients deux fois. A. Le RAG agentique, où le modèle décide quand/quoi récupérer et peut émettre des requêtes de suivi, au prix de plus de latence et de tokens. B. Tout bourrer dans le contexte pour éviter la récupération. C. Fine-tuner sur les questions multi-hop. D. Retirer le reranking pour accélérer. **Réponse : A.** Les requêtes multi-hop, exploratoires justifient la boucle de récupération pilotée par le modèle du RAG agentique ; l’arbitrage est un coût et une latence plus élevés que le RAG one-shot. Le bourrage de contexte (B) ne passe pas à l’échelle ; le fine-tuning (C) ne peut pas retenir des faits changeants ; retirer le reranking (D) nuit à la précision. A. La coder en dur comme un outil CLI par app dans chaque service. B. La construire comme un serveur MCP (avec OAuth 2.1 si distant) pour que de nombreux clients la réutilisent via un protocole standard. C. L’implémenter uniquement comme une passation agent-à-agent. D. Coller sa logique dans chaque system prompt. **Réponse : B.** La réutilisation entre de nombreux clients sous un protocole standard est la vocation du MCP. Les outils CLI par app (A) fragmentent l’implémentation ; l’agent-à-agent (C) sert l’isolation de contexte spécialisée, non la capacité partagée ; le collage dans le prompt (D) est non maintenable. A. Utiliser tool search avec `defer_loading: true` pour que seuls les outils pertinents soient chargés. B. Packager le matériel de référence comme des Skills chargées progressivement à la demande. C. Augmenter la fenêtre de contexte à 1M et continuer à tout charger. D. Escalader chaque requête vers Opus 5. E. Désactiver le prompt caching. **Réponse : A et B.** La découverte progressive — tool search avec chargement différé et Skills à la demande — garde le contexte allégé, restaure un préfixe de cache stable, et améliore la sélection d’outils. Une fenêtre plus grande (C) paie toujours pour le gonflement ; escalader les modèles (D) augmente le coût ; désactiver le caching (E) est l’inverse du correctif. A. Ajouter une règle du system prompt disant au modèle de ne pas révéler les données d’autres tenants. B. Appliquer un filtre `tenant_id` (et ACL) obligatoire au moment de la récupération, avant/le long de la recherche vectorielle, pour que seuls les chunks autorisés entrent dans le contexte. C. Filtrer la réponse après la génération pour retirer les données d’autres tenants. D. Donner à chaque tenant un plus gros modèle. **Réponse : B.** L’isolation est une frontière de sécurité au moment de la récupération : filtrez par `tenant_id`/ACL avant la recherche vectorielle. Une règle de prompt (A) est du prompt comme mécanisme d’application contournable ; le filtrage post-génération (C) est trop tardif — le chunk est déjà entré dans le contexte ; un plus gros modèle (D) n’isole pas les données. A. recall@3 = 1.00 ; MRR = 1.00. B. recall@3 = 0.60 ; MRR = 0.55. C. recall@3 = 0.55 ; MRR = 0.60. D. recall@3 = 0.80 ; MRR = 0.70. **Réponse : B.** Trois des cinq chunks pertinents sont dans le top 3 (rangs 1, 2, 1) → recall@3 = 3/5 = 0,60. Les rangs réciproques sont 1, 0,25, 0,5, 0, 1 → MRR = 2,75/5 = 0,55. L’option A ignore les ratés ; C intervertit les deux valeurs ; D est arithmétiquement faux. A. Grounding ; resserrer l’instruction de répondre uniquement à partir du contexte. B. Récupération : corriger le chunking/les embeddings/l’hybride et ajouter le reranking, car un rappel faible signifie que le chunk pertinent n’est souvent pas récupéré du tout. C. Ajouter plus de citations. D. Basculer le modèle de génération vers Opus 5. **Réponse : B.** Un rappel faible signifie que le bon chunk n’atteint pas le top-k, donc la défaillance est en amont dans la récupération. Le grounding/les citations (A, C) et un plus gros modèle de génération (D) ne peuvent pas aider si la réponse n’a jamais été récupérée. A. Le vector store est corrompu ; reconstruire le matériel. B. Décalage de modèle d’embedding requête/index ; utiliser le modèle d’embedding identique pour l’indexation et l’interrogation. C. k est trop bas ; le monter à 1000. D. Le modèle de génération est trop petit. **Réponse : B.** Les embeddings de modèles différents vivent dans des espaces vectoriels différents, donc la similarité cross-model n’a pas de sens ; la requête et l’index doivent utiliser le même modèle d’embedding. Ce n’est pas du matériel (A) ; monter k (C) ne peut pas corriger des vecteurs incompatibles ; le modèle de génération (D) est sans rapport avec la similarité de récupération. A. Passer à la récupération hybride (BM25 + dense) pour que les identifiants exacts soient classés. B. Récupérer large (k≈50) et ajouter un reranker, en gardant le top 6. C. Augmenter la température. D. Retirer les citations pour accélérer les réponses. E. Passer à un contexte de 1M tokens et tout bourrer. **Réponse : A et B.** La récupération hybride corrige les ratés d’identifiants exacts et le récupérer-large-puis-reranker corrige la précision — les deux leviers canoniques. La température (C) est sans rapport avec la récupération ; retirer les citations (D) nuit à la traçabilité du grounding ; bourrer le contexte (E) gonfle le coût sans améliorer le classement. A. Un ID de corrélation enfilé à travers app → récupération → modèle → outils → aval. B. Des traces par span capturant les IDs des chunks récupérés, l’ordre de rerank, les tokens/coût, et `stop_reason`. C. Uniquement le code de statut HTTP final. D. La propre évaluation du modèle qu’il s’est bien débrouillé. E. Un compte agrégé quotidien de requêtes. **Réponse : A et B.** Un ID de corrélation plus des traces par span (avec le détail de récupération et le coût) rendent un incident reconstructible. Un code de statut (C) et un compte quotidien (E) sont trop grossiers ; l’auto-évaluation (D) n’est pas fiable (anti-patron de l’auto-déclaration). ## À retenir - Le RAG est un pipeline fixe : **ingérer → chunker → embarquer → indexer → récupérer → reranker → grounder → citer** ; chaque décision s’insère dans une étape. - Accordez le **chunking à la forme des données** : document-aware pour le texte structuré, parent–enfant/late pour la prose cross-référentielle, sémantique pour les topiques changeants. - Utilisez la récupération **hybride** (dense + sparse) pour les vrais corpus ; **rerankez** pour la précision ; ajoutez réécriture/HyDE/multi-query pour le rappel. - **Groundez** les réponses au contexte récupéré, citez les sources, et préférez « contexte insuffisant » à la fabrication. - Évaluez la récupération et la génération **séparément** (recall@k, MRR vs faithfulness) ; le confiant-faux-après-rafraîchissement signifie **inspecter d’abord la récupération/l’indexation**. - Choisissez le **RAG pour les faits changeants/cités, le long contexte pour les petits corpus stables, le fine-tuning pour le comportement/style**. - Appliquez le **moindre privilège en supprimant** les outils inutiles (surtout destructeurs) ; gardez les agents à ~4–5 outils avec tool search pour les plus grands catalogues. - Propagez l’**identité de l’utilisateur** aux outils, appliquez les ACL par utilisateur, et exigez **OAuth 2.1** sur les serveurs MCP distants. - Instrumentez **traces, IDs de corrélation et télémétrie tokens/coût** ; utilisez files, clés d’idempotence, webhooks, Batch API et un **pipeline de fraîcheur** pour l’intégration en entreprise. - **Calculez** les métriques de récupération : recall@k = pertinents-dans-le-top-k ÷ requêtes ; MRR = moyenne(1÷rang) ; un reranker relève généralement les deux le plus. - Dans un index partagé, la récupération est une **frontière de sécurité** : filtrez par `tenant_id`/ACL **avant** la recherche vectorielle, propagez l’identité de l’utilisateur final, et cadencez les caches par tenant. - Gardez les **modèles d’embedding de la requête et de l’index identiques** ; la recette canonique est récupérer large (k≈50 hybride) → reranker → garder ~6 → grounder avec citations.