RAG Cookbook (OpenAI)

Le RAG ancre les réponses dans des passages retrouvés au moment de la requête. Tournez-vous vers lui quand le corpus est grand ou changeant et que vous avez besoin de citations. Préférez le long contexte pour un petit corpus stable qui tient confortablement dans la fenêtre ; préférez le fine-tuning pour le style et le format, pas pour les faits. Ce cookbook reflète les objectifs du cours Academy Build with Retrieval-Augmented Generation ; c’est une préparation indépendante construite à partir des objectifs d’apprentissage publiés.

Anatomie du pipeline

 ingest ──► chunk ──► embed ──► store        (build time, offline)
                                   │
 query ──► rewrite ──► retrieve ──► rerank ──► assemble ──► generate ──► cite
                                                              │
                                                        (query time, online)

Deux moitiés échouent pour des raisons différentes. La moitié build-time (chunk, embed, store) échoue silencieusement : un mauvais chunker ou un modèle d’embedding changé dégrade toutes les requêtes futures. La moitié query-time (retrieve, rerank, generate) échoue visiblement, requête par requête. Instrumentez les deux, et évaluez-les séparément.

RAG vs alternatives, quand choisir quoi

Les modèles GPT-5.6 et GPT-6 portent une grande fenêtre de contexte, ce qui tente les équipes de « tout coller ». Cela marche pour un petit corpus stable, mais pour un corpus grand ou changeant c’est plus cher par requête, plus dur à garder frais, et vous n’avez aucune citation à auditer.

Stratégies de chunking avec arbitrages

Règle empirique du chevauchement : 10–20 % de la taille du chunk. Trop peu perd le contexte de frontière ; trop gonfle l’index et produit des hits en double.

Embeddings et vector stores

Les embeddings transforment le texte en vecteurs de sorte que des passages sémantiquement proches se situent près les uns des autres. Deux règles dominent :

1. L’index et la requête doivent utiliser le même modèle d’embedding et la même dimension. Mélanger les modèles est la corruption silencieuse classique : la similarité cosinus entre des vecteurs de deux modèles différents n’a aucun sens.
2. Re-embedez tout le corpus quand vous changez de modèle. Un index à moitié migré retourne du bruit pour la moitié non migrée. Traitez un changement de modèle d’embedding comme une migration de schéma : tout ou rien, verrouillé sur un eval.

Le store contient les vecteurs plus des métadonnées (source, section, ACL, timestamp) et fait une recherche approximative du plus proche voisin. Sur la stack OpenAI, vous pouvez soit laisser la plateforme gérer cela pour vous, soit exécuter le vôtre.

L’outil file search vs un store auto-géré

La règle de décision : tournez-vous vers l’outil file search quand vous voulez des réponses ancrées sur vos fichiers sans monter une stack de retrieval, et vers un store auto-géré quand vous avez besoin d’un contrôle que l’outil n’expose pas — un schéma de chunking précis, du retrieval hybride, un cross-encoder reranker, ou un retrieval sensible aux permissions intégré à votre système d’identité.

Retrieval hybride et reranking

Le retrieval dense (embedding) attrape la paraphrase ; le retrieval sparse (BM25) attrape les IDs exacts, les codes d’erreur et les termes rares. Combinez-les, puis rerank.

retrieval:
  dense:   { top_k: 40 }
  sparse:  { algorithm: bm25, top_k: 40 }
  fusion:  { method: reciprocal_rank_fusion, k: 60 }
  rerank:  { model: cross-encoder, top_n: 8 }

Reciprocal Rank Fusion : le score d’un document est la somme sur les listes de 1 / (k + rank). Avec k=60, un document classé n° 1 dans les deux listes score environ 1/61 + 1/61 = 0.033 ; classé n° 1 dans une liste et absent de l’autre score environ 1/61 = 0.016. La RRF n’a besoin d’aucune calibration de score entre les deux systèmes — elle fusionne par la position de rang seule.

Un cross-encoder reranker lit la requête et chaque candidat ensemble, donnant une bien meilleure précision que le retriever de première étape, à un coût par requête plus élevé. Retrouvez largement (top-k 40–100), puis rerank vers un petit top-n (5–10) pour le modèle.

Grounding et mise en forme des citations

Le grounding n’est réel que si la réponse peut être tracée jusqu’à un passage. Deux disciplines :

• Contraignez la réponse au contexte retrouvé, et fournissez un sentinelle pour « non trouvé » : Answer only from the passages below. If they do not contain the answer, reply NOT COVERED. La sentinelle permet au code de détecter une non-réponse au lieu de livrer une supposition.
• Retournez des citations que le lecteur peut vérifier : un identifiant de source et une section ou un span pour chaque affirmation. Quand le modèle doit synthétiser à travers plusieurs passages, demandez-lui de citer chaque passage porteur plutôt qu’une citation globale à la fin.

Retrieval sensible aux permissions

Le retriever ne doit jamais faire remonter un passage que l’utilisateur demandeur n’est pas autorisé à voir. C’est une affaire d’ingest-et-retrieve, pas une affaire de prompt.

1. Attachez les métadonnées d’accès à l’ingest — stockez l’ACL de chaque chunk (owner, group, sensibilité) à côté de son vecteur.
2. Filtrez au query-time par l’identité de l’utilisateur demandeur — appliquez le filtre de permission dans le retrieval, avant que le modèle ne voie un candidat.
3. Ne comptez jamais sur une instruction de prompt comme « ne révèle pas le contenu restreint » — un passage restreint non filtré dans le contexte est déjà une fuite, quoi que dise le prompt.
4. Re-vérifiez lors des changements de permission — quand un utilisateur perd l’accès, ses futures requêtes doivent cesser de retourner ces chunks ; l’état de permission vit avec la donnée, pas avec la session.

Fraîcheur

Un système RAG n’est aussi à jour que son index. Décidez, par corpus, du niveau de fraîcheur requis et construisez pour cela :

Quelle que soit la cadence, verrouillez les re-ingests sur un eval pour qu’un changement de chunker ou de modèle ne puisse pas dégrader silencieusement le retrieval, et stockez un timestamp de build pour que « confiant mais faux après un rafraîchissement » soit diagnosticable.

Évaluer le retrieval séparément de la génération

Une bonne réponse peut cacher un mauvais retrieval et vice-versa, alors mesurez-les à part.

Comparaison travaillée sur un ensemble de 200 requêtes :

Le reranking ne bouge presque pas le Recall@5 (mêmes candidats) mais relève nettement le MRR et la faithfulness en plaçant le bon passage en premier, là où le modèle le lit le plus tôt. Reportez chaque métrique par segment (type de document, source, langue) — un agrégat de 0,90 peut cacher une source à 0,40.

Taxonomie d’échecs avec correctifs

Exemple travaillé de budget coût et latence

Un assistant de support sur 40 000 articles, cible de latence de bout en bout sous 2 secondes au p95, gpt-5.6-terra pour la génération.

Per query budget (p95 target: 1900 ms)
  query rewrite (gpt-5.6-luna, low effort)   ~120 ms
  hybrid retrieve (dense + BM25, top_k 40)   ~140 ms
  cross-encoder rerank (40 -> 8)             ~180 ms
  generate grounded answer (terra, 8 chunks) ~1200 ms
  citation assembly (code)                    ~20 ms
                                             --------
  total (p95)                                ~1660 ms  ✓ under 1900

Leviers de coût, du moins cher au plus cher : réduisez le nombre de chunks fournis au modèle (8 → 5 avec un reranker plus fort) avant de toucher au tier de modèle ; utilisez gpt-5.6-luna pour l’étape de rewrite ; cachez le préfixe système stable sur l’API ; et réservez un modèle plus gros aux seules requêtes qu’un router marque comme difficiles. Le mauvais réflexe — « utiliser un plus gros modèle pour corriger les réponses fausses » — dépense de l’argent sur un problème de génération qui est d’habitude un problème de retrieval.

Idées reçues fréquentes

Déroulé de scénario

Une équipe fait tourner un assistant KB sur 40 000 articles rafraîchis chaque semaine. Cette semaine, il a commencé à donner des réponses faussement confiantes. Les utilisateurs posent à la fois des questions en langage naturel et des codes d’erreur exacts. Quelle est la PREMIÈRE étape et la bonne architecture ?

1. PREMIÈRE étape — récupérez les traces et vérifiez si le passage en or est même retrouvé. Il est apparu que le re-ingest de cette semaine a changé le chunker (dérive). C’est un problème de retrieval, donc réécrire le prompt gâcherait le cycle.
2. Chunking — structurel ou parent-child pour les articles : chunks enfants pour les matchs précis, sections parentes pour le contexte ; versionnez la config et verrouillez les re-ingests sur un eval.
3. Retrieval — hybride dense + BM25, parce que les codes d’erreur ont besoin du match de terme exact que le retrieval dense rate.
4. Reranking — cross-encoder vers le top-8 ; l’article en or était retrouvé mais siégeait au rang 14 avant reranking.
5. Permissions — filtrez par l’identité de l’utilisateur demandeur au query-time, puisque certains articles sont internes uniquement.
6. Eval — recall@k, MRR et faithfulness, reportés par source, pour qu’une seule source en échec ne puisse pas se cacher derrière l’agrégat.

Alternatives rejetées : réécrire le system prompt (le retrieval était cassé), fine-tuner sur la KB (les faits changent chaque semaine — c’est le boulot du RAG), retrieval dense seul (rate les codes d’erreur), et se fier au score agrégé (il masquait la source en échec).

Points clés à retenir

• RAG pour les corpus grands ou changeants avec citations ; long contexte pour les petits corpus stables ; fine-tuning pour le style, pas les faits.
• Chunkez pour épouser la forme de la donnée ; parent-child équilibre les hits précis et le contexte ; versionnez la config et verrouillez les re-ingests.
• Gardez l’index et la requête sur le même modèle d’embedding ; re-embedez tout le corpus à tout changement de modèle.
• Choisissez l’outil file search pour la vitesse avec moins d’infrastructure, un store auto-géré quand vous avez besoin d’un chunking, d’un retrieval hybride, d’un reranker ou d’une intégration de permissions que vous contrôlez.
• L’hybride (dense + BM25) plus un cross-encoder reranker bat chacun seul ; la RRF fusionne sans calibration de score.
• Imposez les permissions et la fraîcheur au moment du retrieval, et évaluez le retrieval (recall@k, MRR) séparément de la génération (faithfulness), par segment.