Un guide pratique pour les programmeurs agentic

Ton LLM en sait beaucoup. Mais il ne connaît pas tes données. Il ne sait pas ce qu'il y a dans le wiki interne de ta compagnie, ce que disent tes derniers documents de politique, ni ce qu'un client a rapporté dans un ticket de support hier. Il ne peut pas, parce que cette information n'était pas dans ses données d'entraînement — et même si elle l'était, les données d'entraînement ont une date de coupure.

Le Retrieval-Augmented Generation (RAG) règle ça en donnant au modèle un livre ouvert avant qu'il écrive sa réponse. Au lieu de se fier uniquement à ce que le modèle « se rappelle » de son entraînement, le RAG va chercher les documents pertinents dans tes propres sources de données et les injecte dans le prompt. Le modèle génère ensuite une réponse ancrée dans cette preuve.

L'idée est simple. C'est à l'exécution que les équipes trébuchent.

Comment fonctionne le RAG : le pipeline de base

Un système RAG standard a deux phases : une phase offline (préparer la base de connaissances) et une phase online (répondre aux queries).

Offline : construire la base de connaissances

  1. Ingère tes documents sources — PDFs, docs internes, enregistrements de base de données, pages web, peu importe ce que tu as.
  2. Chunke-les en morceaux plus petits. Un document de 50 pages est trop gros pour entrer dans un prompt à côté de la question de l'utilisateur. Il faut le découper en passages — typiquement de 200 à 1 000 tokens chacun.
  3. Embed chaque chunk. Un modèle d'embedding (comme text-embedding-3-small d'OpenAI ou une alternative open-source comme bge-large) convertit chaque chunk en un vecteur dense — une représentation numérique de son sens.
  4. Stocke les vecteurs dans une vector database — Pinecone, Weaviate, Qdrant, pgvector, Chroma, ou même un simple index FAISS pour du prototypage.

Online : répondre à une query

  1. L'utilisateur pose une question.
  2. Embed la question avec le même modèle d'embedding.
  3. Retrieve les top-k chunks les plus similaires depuis la vector database en utilisant une recherche par similarité (typiquement la similarité cosinus ou le produit scalaire).
  4. Augmente le prompt : concatène les chunks récupérés avec la question de l'utilisateur et toutes les instructions système.
  5. Génère : envoie le prompt augmenté au LLM, qui produit une réponse ancrée dans le contexte récupéré.

C'est le pipeline canonique. En diagramme :

User query → Embed → Vector search → Top-k chunks → [System prompt + Chunks + Query] → LLM → Answer

Si tu as déjà bâti un prototype de système RAG, tu as probablement implémenté quelque chose qui ressemble à ça en un après-midi. Le problème, c'est que ce pipeline de base a plusieurs modes d'échec qui ne surgissent qu'au contact de vraies données à vraie échelle.

Là où le pipeline de base casse

1. Le chunking est plus difficile qu'il en a l'air

Un chunking naïf — couper à tous les N tokens avec un peu de chevauchement — fragmente le contexte. Un paragraphe qui explique un concept se fait couper en deux, et aucune des deux moitiés n'a de sens tout seule. L'en-tête d'une table se retrouve dans un chunk et ses lignes dans un autre.

Il existe de meilleures approches. Découpe aux frontières sémantiques en utilisant la structure du document (titres, paragraphes, sections). Utilise Tree-sitter pour le code (comme Cursor le fait). Pour les documents à contenu mixte, considère des parsers spécialisés qui préservent les tables, les listes et les hiérarchies. La taille du chunk elle-même est un compromis : des chunks plus petits sont plus précis au retrieval mais perdent du contexte ; des chunks plus gros préservent le contexte mais peuvent diluer la pertinence. La plupart des systèmes en production s'arrêtent autour de 500 à 1 000 tokens avec 10 à 20 % de chevauchement, mais la bonne réponse dépend de tes données.

2. Le semantic search seul ne suffit pas

La similarité vectorielle trouve des passages sémantiquement liés à la query. Mais parfois tu as besoin d'un match exact sur un mot-clé — un ID de produit, un numéro de politique, le nom d'une personne. Les embeddings ne sont pas forts sur les matchs exacts.

La solution : hybrid search. Combine la vector search dense avec une recherche lexicale (BM25 ou équivalent). Plusieurs vector databases supportent maintenant ça nativement. En pratique, les équipes qui combinent recherche par mots-clés et vector search voient constamment des gains de pertinence significatifs par rapport à l'une ou l'autre méthode seule, surtout pour les queries courtes ou ambiguës.

3. Les chunks récupérés peuvent ne pas être pertinents

Récupérer les top-5 chunks les plus similaires ne veut pas dire que tu as les top-5 chunks les plus utiles. Similarité et pertinence, ce n'est pas la même chose. Un passage qui utilise le même vocabulaire que la query peut parler d'un sujet complètement différent.

La solution : le reranking. Après le retrieval, passe les chunks candidats à travers un reranker cross-encoder (comme Cohere Rerank ou un modèle BERT qui a fait du fine-tuning) qui score chaque chunk contre la query plus soigneusement. Cette deuxième passe est plus lente mais dramatiquement plus précise que la similarité vectorielle brute. Pense-y comme ça : la vector search jette un large filet, le reranker choisit les poissons.

4. La query elle-même peut être mauvaise

Les utilisateurs ne posent pas toujours des questions bien formulées. « C'est quoi l'affaire du changement de politique ? » ne s'embed pas bien. Le retriever ne peut être bon que dans la mesure où la query qu'il reçoit l'est.

La solution : le query processing. Avant le retrieval, réécris la query pour la rendre plus spécifique, étends-la avec des termes connexes, ou génère des réponses hypothétiques (HyDE — Hypothetical Document Embeddings) et utilise-les pour le retrieval. Traite chaque query utilisateur comme une matière brute à normaliser avant qu'elle touche la base de connaissances.

Patterns avancés à connaître

Self-RAG

Le RAG standard fait du retrieval à chaque query, que ce soit nécessaire ou non. Self-RAG entraîne le modèle à décider quand faire du retrieval et à critiquer ses propres sorties pour la groundedness. Le modèle génère des « reflection tokens » — des marqueurs qui indiquent si le retrieval est nécessaire, si les données récupérées soutiennent l'affirmation, et si la réponse est réellement utile. Ça réduit le retrieval inutile (ça sauve de la latence et du coût) et ça attrape des hallucinations que le RAG standard rate.

GraphRAG

Quand tes données ont des relations structurées — hiérarchies organisationnelles, dépendances réglementaires, catalogues de produits — la vector search plate perd le contexte relationnel. GraphRAG combine la vector search avec des knowledge graphs pour capturer et interroger les relations entre entités. L'implémentation GraphRAG de Microsoft, par exemple, utilise des algorithmes de détection de communautés pour créer des résumés hiérarchiques du graphe, permettant à la fois des queries locales (entité spécifique) et globales (niveau thématique).

Agentic RAG

Dans le RAG standard, le retrieval se fait une fois. Dans l'Agentic RAG, le LLM lui-même décide quand et comment faire du retrieval — potentiellement en faisant plusieurs appels de retrieval, en raffinant sa query entre les appels, ou en combinant les résultats de différentes sources. C'est là que le RAG rencontre l'architecture agent : le retriever devient un outil que l'agent peut appeler, pas une étape figée du pipeline. Les inline tools de WHOOP et le context engine de Cursor sont tous deux des variations de ce pattern — le retrieval intégré dans la boucle de décision de l'agent plutôt que boulonné avant la génération.

Construire du RAG qui fonctionne en production

Commence par l'évaluation

L'erreur la plus fréquente en développement RAG : bâtir le pipeline avant de bâtir le framework d'évaluation. Tu dois mesurer trois choses séparément :

  • Qualité du retrieval : est-ce que tu obtiens les bons chunks ? (Précision et rappel contre un jeu étiqueté)
  • Groundedness : est-ce que le modèle utilise vraiment les données récupérées, ou hallucine-t-il à côté ?
  • Qualité de la réponse : est-ce que la réponse finale est utile et exacte ?

Si tu mesures seulement la qualité de la réponse, tu ne peux pas diagnostiquer si une mauvaise réponse vient d'un mauvais retrieval, d'une mauvaise génération, ou des deux. Sépare tes métriques. Beaucoup d'équipes utilisent maintenant le LLM-as-a-judge pour l'évaluation — avoir un modèle qui score les réponses contre des critères — ce qui passe mieux à l'échelle que l'évaluation humaine pour du développement itératif.

La taille du chunk est ton premier hyperparamètre

Ne te rabats pas par défaut sur une taille de chunk fixe. Expérimente. Fais rouler ta suite d'éval sur des chunks de 256, 512 et 1 024 tokens. Mesure le rappel du retrieval et la qualité de la réponse à chaque taille. La taille optimale varie dramatiquement selon le domaine — les documents légaux se chunkent différemment de la documentation de code, qui se chunke différemment des transcriptions de support client.

Les metadata, c'est du contexte de retrieval

Ne jette pas les metadata de tes documents pendant l'ingestion. Source, date, auteur, type de document, titre de section — tout ça peut servir à filtrer les résultats de retrieval avant ou après la vector search. Une question sur « les prix actuels » devrait préférentiellement retrouver des documents récents. Les filtres sur les metadata sont souvent plus efficaces que des améliorations sur les embeddings.

Respecte les contrôles d'accès

Si tes données ont différents niveaux de visibilité — et les données d'entreprise en ont presque toujours — ta couche de retrieval doit appliquer les contrôles d'accès. Un utilisateur qui pose une question ne devrait récupérer que les documents qu'il a le droit de voir. Ce n'est pas un « nice-to-have » ; c'est une exigence de sécurité à bâtir dans le pipeline de retrieval dès le jour un.

Surveille la staleness

Le RAG n'est à jour que dans la mesure où ton index l'est. Si tes documents sources changent et que tes embeddings ne se mettent pas à jour, tu sers du contexte périmé. Bâtis un pipeline de synchronisation qui ré-indexe les documents modifiés sur un calendrier qui correspond au rythme de changement de ton domaine — à l'heure pour les tickets de support, à la journée pour la documentation, immédiatement pour les mises à jour réglementaires.

Quand utiliser le RAG et quand ne pas l'utiliser

Le RAG est le bon choix quand :

  • Tes données changent fréquemment et réentraîner est impraticable
  • Tu as besoin de réponses ancrées dans des sources spécifiques et citables
  • Tu veux garder le modèle de base généraliste et brancher la connaissance de domaine de l'extérieur
  • La vie privée ou la conformité exige que les données propriétaires n'entrent jamais dans l'entraînement du modèle

Le RAG est le mauvais choix quand :

  • La connaissance est déjà bien représentée dans les données d'entraînement du modèle (ne fais pas de RAG pour « qu'est-ce que la photosynthèse »)
  • Tu as besoin que le modèle intériorise profondément des patterns de raisonnement de domaine, pas juste qu'il référence des faits (considère le fine-tuning)
  • Tes données sont assez petites pour tenir entièrement dans la fenêtre de contexte (mets-les juste dans le prompt)
  • Les exigences de latence sont si serrées que l'aller-retour du retrieval est inacceptable

La plupart des systèmes du monde réel finissent par utiliser le RAG à côté du fine-tuning et du prompt engineering — pas à leur place. Le RAG gère la connaissance dynamique. Le fine-tuning gère les patterns de raisonnement et le style. Le prompt engineering gère le cadrage de tâche et le formatage de sortie. Ils sont complémentaires, pas en compétition.

Une implémentation RAG minimale

Pour les équipes qui veulent commencer aujourd'hui, voici un squelette en Python avec LangChain (même si le pattern est indépendant du framework) :

# 1. Load and chunk documents
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.document_loaders import DirectoryLoader

loader = DirectoryLoader("./docs", glob="**/*.md")
docs = loader.load()

splitter = RecursiveCharacterTextSplitter(chunk_size=800, chunk_overlap=100)
chunks = splitter.split_documents(docs)

# 2. Embed and store
from langchain.embeddings import OpenAIEmbeddings
from langchain.vectorstores import Chroma

embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
vectorstore = Chroma.from_documents(chunks, embeddings, persist_directory="./chroma_db")

# 3. Retrieve and generate
from langchain.chat_models import ChatOpenAI
from langchain.chains import RetrievalQA

llm = ChatOpenAI(model="gpt-4o")
retriever = vectorstore.as_retriever(search_kwargs={"k": 5})

qa_chain = RetrievalQA.from_chain_type(llm=llm, retriever=retriever)
answer = qa_chain.invoke("What is our refund policy for enterprise customers?")

Ça te donne un prototype fonctionnel en moins de 50 lignes. À partir de là, le travail est dans l'évaluation, la stratégie de chunking, l'hybrid search, le reranking et les contrôles d'accès — les considérations de production décrites plus haut.

À retenir

Le RAG, ce n'est pas « ajoute du retrieval et les hallucinations disparaissent ». C'est une architecture de système qui demande un chunking réfléchi, du hybrid search, du reranking, du query processing, de l'évaluation et des contrôles d'accès pour fonctionner de manière fiable. Le pipeline de base est un point de départ, pas une destination.

Mais quand il est bien bâti, le RAG donne à tes agents quelque chose qu'ils ne peuvent pas obtenir autrement : l'accès à tes données, en temps réel, avec des citations, sans réentraîner le modèle. C'est la fondation sur laquelle la plupart des systèmes agentic utiles sont bâtis.

Pour aller plus loin